Notifications - kwantu/platformconfiguration GitHub Wiki
Notifications alert users to information or a request so that they can act on it. They are generated by the workflow and will appear on the notifications page for the user receiving them. Users will also receive notifications by email unless they turn this feature off. This is managed from the settings page.
Notifications may be configured either at the process level or at the step level. Process level notifications will trigger whenever a step in that process meets the relevant conditions are met. Step level notifications only trigger when the relevant conditions are met for the specific step they are configured on.
There are two basic types of notifications
- Implicit (Assignment/acceptance/ReAssignment) which goes automatically to the user and users list is pre-calculated by the system. In case of assignment, notification goes to the user to which workflow is assigned (by any of the functions: role, profileRole etc.
- Explicit - Where you define via actions, preActions, postActions and you define user function as well (role, profileRole)
Notification users are identified by notification functions that include
The following table summarises the different types of notifications and at which level they operate at.
| Notification type | Explanation | Level |
|---|---|---|
| Assignment | Triggered when the workflow is assigned to a new user in a step | Process and step |
| Acceptance | Triggered when the workflow advances to a step for which there are multiple users assigned the role for the step | Process |
| Re-assignment | Triggered when the workflow is manually re-assigned to another user | Process |
Acceptance and re-assignment notifications may only be configured at the process level. Assignment notifications may be configured at either the process or step level. In practice configuring assignment notifications at the step level gives more flexibility over the messaging and the steps on which they are associated.
The following parameters may be used when configuring notifications.
This determines the action that will be taken when the user clicks on the link in the notification. It may either call a specific URL or open the workflow. URL (opens a URL you specify), | Parameter | Details | | "goto": "profile" | Opens the default page for the profile in which the workflow is located| | "goto": "processListing" | Opens the workflow page for the profile.| | "goto": "subProcessInstance" | Opens the sub process instance for the workflow| | "goto": "subProfile" |Used in cases where the workflow is at the sub profile level. | | "goto": "subProfileListing" | Used in cases where the workflow is at the sub profile level. | | "goto": "subProfileSubProcessInstance" | Used in cases where the workflow is at the sub profile level. |
Notifications may be to inform or to request an action. Options are: | Parameter | Details | | info| Information type| | action| Action type|
Specifies the priority of the notification. Options are | Parameter | Details | | normal | Default for normal notifications | | action | Flags that the notification expects some action to be taken | | critical | Critical notifications are presented on an overlay which blocks the page until an action is taken.|
This parameter manages who receives the notifications. It may either be assigned directly to the user assigned the workflow for a step or to all users with the role associated with the step. In the latter case replace "Capturer" with the relevant role ID Options are | Parameter | Details | | role | with the role assigned | | profileRole | All users with the role assigned in the context of the current profile| | subProfileRole | All users with the role assigned in the context of the current subProfile | | userId | The user with that userId| | currentStepUser | The user that was assigned to the step | | currentStepRole | Replace "Capturer" with the relevant role ID eg stepAssignee or role":"Capturer"|
You may personalise notifications using one or more of the variables. The following variables may be used to personalise the notification messaging.
| Variable | Explanation |
|---|---|
| "#PROFILE_ID#" | Displays the UUID of the profile in which the workflow is located |
| "#PROFILE_NAME#" | Displays the name of the profile in which the workflow is located |
| "#COMMUNITY_ID#" | Displays the UUID of the community in which the workflow is located |
| "#COMMUNITY_NAME#" | Displays the name of the community in which the workflow is located |
| "#APPLICATION_ID#" | Displays the UUID of the app in which the workflow is located |
| "#APPLICATION_NAME#" | Displays the name of the app in which the workflow is located |
| "#CURRENT_USER_ID#" | Displays the UUID of the user to which the notification is being sent |
| "#LOGIN_USER_NAME#" | Displays the login username for the current user |
| "#CURRENT_USER_NAME#" | Displays the name of the user to which the notification is being sent |
| "#SUB_PROCESS_ID#" | Displays the UUID of the sub process for the workflow |
| "#SUB_PROCESS_NAME#" | Displays the name of the sub process for the workflow |
| "#VALID_DATE#" | Displays the UUID of the user to which the notification is being sent |
| "#NODE_TITLE#" | Displays the name of the sub profile in which the workflow is located |
| "#STEP_ID#" | Displays the UUID of the step to which the notification is related |
| "#STEP_NAME#" | Displays the name of the step to which the notification is related |
| "#STEP_CREATED_DATE_TIME#" | Displays the date and time on which the step associated with the notification is created |
| "#NOTIFICATION_DATE_TIME#" | Displays the date and time on which the notification is generated |
| "#DUE_DATE#" | Displays the date on which the workflow sub process instance is due |
Following are examples of process level notifications. These are configured at the root level of the workflow process.
The following example code is for a process level assignment notification. This will trigger a notification each time a step in the workflow process is assigned to a user.
"assignment": {
"message": {
"i18n": {
"_id": "en",
"en": "Hi #CURRENT_USER_NAME#, A new workflow is assigned to you. Please follow below link to move to subprocess"
}
},
"messageType": "action",
"notificationAction": {
"action": {
"goto": "subProcessInstance"
},
"label": {
"i18n": {
"_id": "en",
"en": "Open subprocess"
}
}
},
"priority": "normal",
"title": {
"i18n": {
"_id": "en",
"en": "Workflow acceptance #SUB_PROCESS_NAME# Test"
}
}
}
The following example code is for a process level acceptance notifications. This will trigger a notification each time a step in the workflow process is assigned to a role. All users with that role will receive the notification. This alerts users that a workflow is waiting for one of them to accept it. Once one person accepts it, an assignment notification will then be sent (if configured).
"assignmentAcceptance": {
"message": {
"i18n": {
"_id": "en",
"en": "The workflow to approve outcome #SUB_PROCESS_NAME# is waiting for you or other users with your role to accept. Please click the link below to open the workflow and accept it."
}
},
"messageType": "action",
"notificationAction": {
"action": {
"goto": "subProcessInstance"
},
"label": {
"i18n": {
"_id": "en",
"en": "Open outcome"
}
}
},
"priority": "normal",
"title": {
"i18n": {
"_id": "en",
"en": "Acceptance - Workflow acceptance"
}
}
},
The following example code is for a process level re-assignment notifications. This will trigger a notification each time a step in the workflow process is manually re-assigned to a role.
"reAssignment": {
"message": {
"i18n": {
"_id": "en",
"en": "The workflow to approve outcome #SUB_PROCESS_NAME# has been assigned to you."
}
},
"messageType": "action",
"notificationAction": {
"action": {
"goto": "subProcessInstance"
},
"label": {
"i18n": {
"_id": "en",
"en": "Open outcome"
}
}
},
"priority": "normal",
"title": {
"i18n": {
"_id": "en",
"en": "Re-assignment - Workflow reassignment"
}
}
}
Following is an example of a step level notification. These are configured as a pre or post action on the step to which they apply.
The following example code is for a step level assignment notification. This will trigger a notification each time a step in the workflow process is assigned to a user. The main difference to the process level acceptance notification is that this code also specifies if the workflow is assigned to a user role or the assigned user.
{
"_id": "wfNotificationEmailNew",
"_seq": 2,
"description": {
"i18n": {
"_id": "uuid",
"en": "test"
}
},
"method": {
"notification": {
"message": {
"default": {
"i18n": {
"_id": "en",
"en": "The outcome #SUB_PROCESS_NAME# has been assigned to you for review"
}
},
"rtf": {
"markup": {
"i18n": {
"_id": "en",
"en": "The outcome #SUB_PROCESS_NAME# has been assigned to you for review"
}
}
},
"title": {
"i18n": {
"_id": "en",
"en": "Harvest transition - Outcome #SUB_PROCESS_NAME# waiting for review"
}
}
},
"messageType": "action",
"notificationAction": {
"action": {
"goto": "subProcessInstance"
},
"label": {
"i18n": {
"_id": "en",
"en": "Open outcome"
}
}
},
"notificationType": "workflow",
"priority": "normal",
"recipients": {
"role": "projectmanager"
}
}
}
}
Notification test cases are documented here.
See also How to configure overdue notifications.
Parameters
| Parameter | Options | meaning |
|---|---|---|
notificationAction |
URL "goto": "profile" "goto": "processListing" "goto": "subProcessInstance" "goto": "subProfile" "goto": "subProfileListing" "goto": "subProfileSubProcessInstance" |
Open a specific URL Open the profile details tab Open the workflow tab Open the workflow subprocess Open the sub-profile details tab Open the sub-profile workflow tab Open the sub-profile subprocess |
messageType |
info action readReceipt actionReceipt |
Will be a simple notification with a dismiss button Will include action button configured via notificationAction Will be like info but with a Dismiss button (not in scope yet) Includes action buton (not in scope yet) |
priority |
|
|
Variables |
"#PROFILE_ID#" "#PROFILE_NAME#" "#COMMUNITY_ID#" "#COMMUNITY_NAME#" "#APPLICATION_ID#" "#APPLICATION_NAME#" "#CURRENT_USER_ID#" "#CURRENT_USER_NAME#" "#SUB_PROCESS_ID#" br> "#SUB_PROCESS_NAME#" "#VALID_DATE#" "#NODE_TITLE#" "#STEP_ID#" "#STEP_NAME#" "#STEP_CREATED_DATE_TIME#" "#NOTIFICATION_DATE_TIME#" "#DUE_DATE#"
|
|
recipients |
{"stepAssignee": } {"stepAssigneeFromStep": } |
Notification will be sent to use that is assigned the workflow |
{"role":"Capturer"} |
Notification be sent to any user with the designated role (Users with role of Capturer in this case) | |
| "indicator": { "indicatorSetId": "desteaClientInteractionsRecord", "elementId": "agencySupportStaff"} | Select the userid from the data object |
Notifications are configured at the process level or the step level. Process level notifications are designed to cover a range of generic circumstances where notifications are needed. Step levels notifications may be customised to the specific step.
These notifications are automatically generated by workflow within the lifecycle of a sub process instance. These includes
| Name | Purpose |
|---|---|
| Assignment | A generic notification triggered every time a user is assigned the workflow for a step in a process |
| Acceptance | A generic notification triggered every time the workflow is assigned to a role and there are multiple users with that role |
| Re-assignment | A generic notification triggered every time the workflow is re-assigned to a new user |
All these three implicit notifications are configurable can contain actions to goto subprocess and take actions there.
Note
In case of email links it will only open the subprocess
if the current user has access to specific subprocess
Example configurations:
"assignment": {
"message": {
"i18n": {
"_id": "en",
"en": "\u003cdiv\u003eHi #CURRENT_USER_NAME#,\u003cbr/\u003e A new workflow is assigned to you. Please follow below link to move to subprocess\u003c/div\u003e",
"pt": "Workflow is assigned to you. Please follow action."
}
},
"messageType": "action",
"notificationAction": {
"action": {
"goto": "subProcessInstance"
},
"label": {
"i18n": {
"_id": "en",
"en": "Open subprocess",
"pt": "Open subprocess(pt)"
}
}
},
"priority": "normal",
"title": {
"i18n": {
"_id": "en",
"en": "Workflow acceptance #SUB_PROCESS_NAME# Test",
"pt": "Workflow acceptance"
}
}
} "assignmentAcceptance": {
"message": {
"i18n": {
"_id": "en",
"en": "The workflow to approve outcome #SUB_PROCESS_NAME# is waiting for you or other users with your role to accept. Please click the link below to open the workflow and accept it."
}
},
"messageType": "action",
"notificationAction": {
"action": {
"goto": "subProcessInstance"
},
"label": {
"i18n": {
"_id": "en",
"en": "Open outcome"
}
}
},
"priority": "normal",
"title": {
"i18n": {
"_id": "en",
"en": "Acceptance - Workflow acceptance"
}
}
}, "reAssignment": {
"message": {
"i18n": {
"_id": "en",
"en": "The workflow to approve outcome #SUB_PROCESS_NAME# has been assigned to you."
}
},
"messageType": "action",
"notificationAction": {
"action": {
"goto": "subProcessInstance"
},
"label": {
"i18n": {
"_id": "en",
"en": "Open outcome"
}
}
},
"priority": "normal",
"title": {
"i18n": {
"_id": "en",
"en": "Re-assignement - Workflow reassignment"
}
}
}These are notifications configured in the pre-action block for the step in which you want them to trigger.
{
"_id": "wfNotificationEmailNew",
"_seq": 2,
"description": {
"i18n": {
"_id": "uuid",
"en": "test"
}
},
"method": {
"notification": {
"message": {
"default": {
"i18n": {
"_id": "en",
"en": "The outcome #SUB_PROCESS_NAME# has been assigned to you for review"
}
},
"rtf": {
"markup": {
"i18n": {
"_id": "en",
"en": "The outcome #SUB_PROCESS_NAME# has been assigned to you for review"
}
}
},
"title": {
"i18n": {
"_id": "en",
"en": "Harvest transition - Outcome #SUB_PROCESS_NAME# waiting for review"
}
}
},
"messageType": "action",
"notificationAction": {
"action": {
"goto": "subProcessInstance"
},
"label": {
"i18n": {
"_id": "en",
"en": "Open outcome"
}
}
},
"notificationType": "workflow",
"priority": "normal",
"recipients": {
"role": "projectmanager"
}
}
}
}