Reference Smart Notifications

Overview

Smart notifications in Workgrid are an important mechanism by which your organization can interact with users. There are many use cases for Smart Notifications such as sending approvals, announcements or anything of particular interest to your users. This document will cover the high-level concepts you need to understand as an engineer creating Smart Notifications in Workgrid.

Lifecycle

Smart Notifications in Workgrid have a lifecycle as shown below:

Lifecycle State	Description
Created	This is the first state for a Smart Notification immediately after the job to create it has been completed
Actioned	In the Actioned state, the user who received the Smart Notification has clicked on a button of type Action.Submit. Workgrid can notify your system when a Smart Notification enters the actioned state, or your system can poll for actioned events. Please see the Events API reference.
Processed	A Smart Notification enters the processed state after the user’s action has been successfully processed in the source system and the completion has been reported back to Workgrid. This will also inform the user that the action has been completed. Please see the Events API reference for details on how to process an event.
Deleted	The user deleted the Smart Notification

Correlation Ids

As noted in the Jobs Reference a correlation identifier may be optionally included in a job request. This value can be any string and it links your source system to Workgrid. Correlation identifiers make it possible to associate multiple actions taken in Workgrid with events in the source system, creating a one-to-many relationship among actions taken in Workgrid as jobs. The most common value for a correlation identifier would be a unique identifier that represents a transaction (such as an approval) in the source system. In the examples below we'll demonstrate how you can use correlation identifiers to work through various approval scenarios.

Example Scenarios

Sending smart notifications that require an approval or rejection from a user is one of the most common use cases in Workgrid. These examples outline common approval scenarios and how you can make use of the Workgrid APIs to complete each scenario. These examples do not cover all the possible approval scenarios, but they should give you a good understanding of the possibilities of Workgrid enabling you to mix and match the patterns below to meet your need.

Single Approver

Description

This is quite possibly the simplest approval flow. It consists of a single approve and the transaction is complete once the user takes action.

Steps

1. Create a job request to create a smart notification sent to the specific user providing a correlationId that uniquely identifies the transaction in your source system, and optionally store the jobId received in the response.
2. If the user actions the smart notification in Workgrid and you receive the event (see receiving events in Workgrid).
   1. Make the appropriate API call in your source system.
   2. Mark the event as processed using the Workgrid Events API.
3. If the user actions the transaction in the source system create a smart notification deletion request using the Workgrid Jobs API and passing in the correlationId or jobId.

Single Approver with Multiple Levels of Approvers

Description

In this flow once an approver takes action on an item, like approving a request, the next approver needs to approve it until all required approvals have happened.

Steps

1. Create a job request to create a smart notification sent to the specific user providing a correlationId that uniquely identifies the transaction in your source system, and optionally store the jobId received in the response.
2. If the first approver approves the smart notification in Workgrid and you receive the event (see receiving events in Workgrid).
   1. Make the appropriate API call in your source system.
   2. Mark the event as processed using the Workgrid Events API
   3. Create a job request sending a new smart notification to the second approver providing a correlationId that uniquely identifies the transaction in your source system, and optionally store the jobId received.
   4. If the second approver actions the second notification:
   5. Follow steps 2.1 and 2.2 above
3. If the first approver approves the transaction in the source system:
   1. Create a smart notification deletion request using the Workgrid Jobs API and passing in the correlationId or jobId that removes the approval from the first approver in Workgrid
   2. Create a job request sending a new smart notification to the second approver providing a correlationId that uniquely identifies the transaction in your source system, and optionally store the jobId received.
4. If the first approver rejects the smart notification in Workgrid and you receive the event (see receiving events in Workgrid).
   1. Make the appropriate API call in your source system.
   2. Mark the event as processed using the Workgrid Events API.
5. Create a job request to create a smart notification sent to the specific user providing a correlationId that uniquely identifies the transaction in your source system, and optionally store the jobId received in the response.

Note: That Steps 2 and 3 above would apply to any number of additional approvers that you require in your system.

Multiple Approvers with Single Approval/Rejection Required

Description

In this scenario multiple approvers are associated with a single transaction and when one individual approvers or rejects the transaction is complete.

Steps

1. Create a job request to create a smart notification sent to all the required approvers providing a correlationId that uniquely identifies the transaction in your source system, and optionally store the jobId received in the response.
2. If one of the users actions the smart notification in Workgrid and you receive the event (see receiving events in Workgrid).
   1. Make the appropriate API call in your source system.
   2. Mark the event as processed using the Workgrid Events API.
   3. Create a smart notification deletion request using the Workgrid Jobs API and passing in the correlationId or jobId that removes the approval from the other approvers associated with the transaction.
3. If the user actions the transaction in the source system create a smart notification deletion request using the Workgrid Jobs API and passing in the correlationId or jobId to remove the approval from the other approvers associated with the transaction.

Multiple Approvers Where an Approver Needs to Be Removed and Added

Description

In this scenario multiple approvers are associated with a single transaction and when one individual approvers or rejects the transaction is complete. A situation ocurrs such that Bob (see Current State below) needs to be removed from the approval and replaced with Joe (see Target State), after which any one of the users approves or rejects the transaction.

Steps

1. Create a job request to create a smart notification sent to all the required approvers providing a correlationId that uniquely identifies the transaction in your source system.
2. To remove Bob create a smart notification deletion request using the Workgrid Jobs API and passing the correlationId as well as an audience that contains the email for Bob.
3. To add Joe submit a smart notification creation request using the Workgrid Jobs API and providing the same correlationId as step 1.
4. If one of the users actions the smart notification in Workgrid and you receive the event (see receiving events in Workgrid).
   1. Make the appropriate API call in your source system.
   2. Mark the event as processed using the Workgrid Events API.
   3. Create a smart notification deletion request using the Workgrid Jobs API and passing in the correlationId that removes the approval from the other approvers associated with the transaction.
5. If the user actions the transaction in the source system create a smart notification deletion request using the Workgrid Jobs API and passing in the correlationId to remove the approval from the other approvers associated with the transaction.

Multiple Approvers with All Approvals Required

Description

In this scenario multiple approvers are associated with a single transaction and all approvers are required to approve the transaction for it to complete and any rejection cancels the entire transaction.

Steps

1. Create a job request to create a smart notification sent to all the required approvers providing a correlationId that uniquely identifies the transaction in your source system, and optionally store the jobId received in the response. In your own data store you should store who you sent the smart notification to, and set the current status to unacted (as an example).
2. If one of the users approves the smart notification in Workgrid and you receive the event.
   1. Make the appropriate API call in your source system.
   2. Mark the event as processed using the Workgrid Events API.
   3. Update your data store to mark the notification as approved by the user in the Workgrid event.
   4. Check your data store to determine if the transaction has been approved by all required users and take any necessary API action in your source system.
3. If the user approves the transaction in the source system
   1. Update your data store to mark the notification as approved by the user
   2. Create a smart notification deletion request using the Workgrid Jobs API and passing in the correlationId or jobId as well as a audience that contains the email for the user who approved the transaction to remove the approval from the user in Workgrid.
   3. Check your data store to determine if the transaction has been approved by all required users and take any necessary API action in your source system.
4. If a user rejects the smart notification in Workgrid and you receive the event.
   1. Make the appropriate API call in your source system to reject the transaction.
   2. Create a smart notification deletion request using the Workgrid Jobs API and passing in the correlationId or jobId that removes the approval from the other approvers associated with the transaction.
5. If a user rejects the smart notification in the source system
   1. Create a smart notification deletion request using the Workgrid Jobs API and passing in the correlationId or jobId that removes the approval from the other approvers associated with the transaction.

Multiple Approvers with Multiple Levels of Approvers

Description

In this flow once an approver takes action on an item, like approving a request, the transaction is removed from all approvers in level 1 (see below) and all the approvers in level 2 (see below) now receive a smart notification to take action on the transaction.

Steps

This flow is a combination of the Single Approver with Multiple Levels of Approvers and Multiple Approvers with Single Approval/Rejection Required patterns. Conceptually each level of approvals follows the ‘multiple approvers’ pattern and if someone approves the transaction it follows the ‘single approver’ pattern in that a new smart notification creation request needs to be submitted to a group of approvers.