Connection selection

About worker connection

Workers need to select appropriate connections:

  • When creating workers, where connections are pre-set on worker creation.
  • During assignment, where tasks are created without connections, and later assigned, before the partner process is sent and the partner worker created.
  • As part of a share, where tasks can create multiple connections to other partners.

Connection selection involves terminology, conventions and components.


When selecting a connection, a distinction can be made between:

  • The connectionRole. This is the reference that will be used for the role within the worker's Connections field. For example, the task conventions use a standard connection role of "partner" to identify the partner task.
  • The searchRole. This is a role reference that will be used to look up connections.

The searchRole defaults to the connectionRole, but it can make sense for them to be different. For example, you could have a worker that needs a "partner" connection, but which uses a search role of "auditor" to look for partners who are auditors.


Most workers use the Send process to send a process to a partner. This allows the specification of a path that identifies a folder at the recipient's end in which the recipient's worker should be created. This path is know as the "local path", because it is local to the recipient.

When specifying a connection, it is useful to be able to specify the local path. Local paths are recorded in the Address book field of a connection's connection group, at the sender's end.

Adding a "*" suffix to a search role is used to mean "search for both a connection and a local path".


Group Connections Script is used to retrieve a list of possible connections, optionally with local paths, that could be used for a particular role. Roles are resolved from a group, or from the primary group of a worker. It is passed a role (a search role) to be used to look up connections, which are then resolved from the group. "Group Connections Script" is a misnomer - select connections would be better.

Group Connections Script uses a number of different strategies for identifying suitable connections. Each strategy is attempted in turn, and the first to return any connections is used.

  • Connections data: The "connections" data area for the group and all its parents are merged. If this contains any entries for the role, those entries are returned as suitable connections. This means that using the connections data area overrides any other method of specifying connections. This is the preferred way of letting users specify suitable connections. The connections data area will contain local paths if appropriate.
    Within the connections data, the role specifiers, which are search roles, may have the * suffix. Individual roles may then have a numeric suffix, so a role of "partner*.2" means "the second connection in the list of partners with address books".
  • Pre-set connections: If no connections data is found, if the group's connection list contains the searched-for role, those connections are returned. Group connections are inherited down the hierarchy, so this effectively looks at the group and all its parents. All address book entries are returned if the role has a "*" suffix.
  • Self folder role: If the group itself is a connection group and has a matching folder role, use the associated connection.
  • Folder roles: Search for all connections that have connection groups that identify the role as their folder role, or which have the role as their path. This is a way of globally setting connections with a particular role or path. All address book entries are returned if the role has a "*" suffix.
  • All connections: It no connections can be found, and if the strict option is not set, return all connections. All address book entries are returned if the role has a "*" suffix.

Worker Connections Script is used to manage the list of potential and actual connections in a worker or a group. As well as being used by the task assignment processing, this is used by two step types:

  • Workers can use Connections to manage multiple connections for a share. This uses Group Connections Script to look up possible connections.
  • Groups can use Manage connections to set the group's "connections" data area, which can then be used by Group Connections Script. Manage connections does not set group-level connections.