Performance activity relationships
- Simon Coggins
Performance activities make extensive use of relationships to identify participants, send notifications and manage participant selection. See the relationships documentation for more information on relationships and resolvers.
Participating vs view-only relationships
Relationships are added to performance activities in order to specify who should be involved in the activity as a participant. Relationships are always relative to the subject user - who is the user that was assigned to the activity via the Assignment tab.
While the subject is often a participant in their own activity, they don't have to be - it's possible to create an activity with others participating about a subject who is not involved.
When a relationship is added it can be either as a participating relationship or a view-only relationship. Both types of relationships result in a participant instance for the user, but only participating relationships require the participant to respond to questions.
View-only participants gain access to the activity and can view other user's responses but do not have their progress tracked in the activity and have no impact on when it is considered complete.
Relationships are assigned per section, so it's possible to be a participant in one section, view-only in another and have no involvement in a third within the same activity.
Users who are not involved in a specific section will not see that section when they view the activity.
Viewing other user's answers
View only participants are always allowed to view other participant's responses. For participating relationships, there is a checkbox that determines if the relationship is allowed to view other's responses or not.
Manual vs calculated relationships
Some relationships (such as subject or manager) can be automatically calculated from the subject user and potentially some other data that is passed in (such as a job assignment). These are known as calculated relationships.
Separate from that there are some other relationship types which are manual, meaning the participants must be manually selected by a system user.
The activity has settings which determine who can manually select participants. These settings also use a relationship (this time a calculated one) so a relationship resolver is used to identify who will select participants, those users are notified that they should select, then the actual participants are created.
Note that unlike participant instances (which are only created once then left unchanged), the system which checks for who should do the selecting will continue to add new users who meet the relationship resolver criteria, and not remove users who no longer meet it. So if a user doesn't have a manager and managers must select the relationship, then adding a manager later will still give that user access to select.
External relationships
There is one special relationship called 'External participants' which works differently to the other relationship types, in that it resolves to an external user who does not have a system account or record in the user table. This is handled by requesting a name and email address and generating a secret token for the participant. External participants are sent an email to ask them to participate, and they are then authorised by the token in the URL.
In order to access the correct participant you must use a combination of participant_source (internal or external) and participant_id (which is the id from either the user table or the perform_participant_external table).
1-0 and 1-N relationships
The subject relationship will always resolve to exactly one user, but other relationship types don't have any such guarantee. There can be cases where relationships resolve to no users or many users.
Empty relationships
In some cases a relationship might not resolve to any users. This can happen for many reasons:
- For the manager relationship - the user doesn't have any job assignments
- For the manager relationship - the user has one or more job assignments but no manager is assigned to any of them
When a relationship returns no users, no participant instances are created for that relationship. That can mean relationship progress might aggregate to complete without any responses coming in. Users who can manage participation can identify subject instances with no participants in a specific relationship and manually add participants if required. If the activity progress has moved on they can manually re-open the activity.
In the future we may add additional configuration options to progress criteria so you can require responses before progress continues.
One to many relationships
In other cases a relationship might be fulfilled by multiple participants. For example:
- For the manager relationship - the user has multiple jobs and each has a manager assigned.
When this happens multiple participant instances are created, one for each user, each with the same relationship.
The exact behaviour in these cases is dependent on the area, but in general there are two types of behaviour:
- First wins
For example, when selecting participants for a manual relationship, the user doing the selecting only occurs once. In this situation all managers would be able to select participants but the action would be complete when the first to do it submitted their participants. At this point the action is complete and other managers will no longer have the option to select participants. - All take part
For example, when completing an activity if there are multiple managers they all will receive their own participant instance and each of them will have the opportunity to give feedback. Their responses are grouped together by relationship but attributed separately to them as individuals. The subject instance progress will only be complete when all managers have completed their participant instances. A user with manage participation can manually override this by closing unwanted manager participant instances.