Implementing pipelines

Introduction

As a platform admin, you can do the following when implementing a pipeline:

• Restrict access to a state of the pipeline to specific audiences so that you can allow only authorized employees to perform actions at this point in the workflow.
• Integrate tasks with some states; choose the states for which you want to create pending tasks for approvers.
• Enable pre-configured system actions in transitions. For example, you can set up automatically-triggered push notifications to all employees who have access to a particular pipeline state.

Objective

In this tutorial, you will learn how to implement the listed requirements in an expense reimbursement pipeline.

Procedure

1. Assign audiences to a state
2. Integrate a task with the state
3. Customize the transition associated with the state

Step 1: Assign audiences to a state

You can set an audience or a collection of audiences for a state. You can specify multiple audiences, and be very granular with who can do what.

To assign audiences to a state, go to the Audiences tab (in the Edit state dialogue) and click the Audience field. From the displayed drop-down list, select the audiences that you want to assign to the state.

You can also create a new audience from inside the state itself. To do this, scroll to the bottom of the list and click + Create New.

Assigning audiences in Advanced mode

Although audience selection is a powerful capability, audiences don't understand a few basic elements within the platform.

For example, you might want to select "My leave approver", "My Manager", or vary the audience if someone is away on leave. In such cases, you can use the Audience post selection script field.

See the following sample post-selection script for selecting the manager of a requestor (employee):

const eid = context.data.employeeId;
console.log(eid);
const managers = await ehr.sql("SELECT * FROM `Manager-Employees` WHERE employeeId=" + eid);
console.log(managers);
console.log(eid);
if(!managers.length) return [];

const managerIds = managers.map(e=>e.managerId);
const managerEmployees = await ehr.sql("SELECT * FROM Employee where employeeId IN (" + managerIds.toString() + ")");
return managerEmployees;

Additionally, a new feature is in development and will be available in a few weeks. We are introducing syntactic sugar keywords, such as My Manager, My Leave Approver, My Delegate, and more, which can simply be dropped in Audience post selection script. In conjunction with FEEL scripting, this means you will be able to use English language type scripting in this field.

Step 2: Integrate a task with the state

When configuring a state, you can use the set of controls in the Tasks tab (in the Edit state dialogue) to specify whether and how the state is displayed in Tasks:

(This example illustrates setting up a pending task for expense request approval.)

	Integrate the state with Tasks You can enable Integrate with task (toggle button) to associate the state with a pending task, which is assigned to all assigned audiences.
	Customize the details displayed in the task You can select a data container in Task Data container. The content of the data container determines what is displayed in the task. You can even display a different view of the pipeline for every task (ie for each audience) using multiple data containers.
	Enable email notifications You can enable Notify audience (toggle button) to send email notifications to the configured audiences. Email notifications can inform users about their pending tasks and provide them with details about the transition to the state and the status of the object (for example, as in this case, the status of the expense request).
	Specify the template for email notifications If you have enabled notifying audiences, you can configure a previously-added email template for the notifications. To do this, select a template in Email template. Adding an email template to the platform As a platform admin, to add a new email template, do the following: In the sidebar, in the Business section, click Settings. Go to Customization > Emails. Click + Add a new template. Enter the required details and template body. Click Create & Activate. The following example illustrates how a template for expense request notification emails to managers would look:
	Customize the Tasks table You can granularly customize how the Tasks table displays details of the object by configuring columns in the Task Display section. You can add columns and customize their Column header, Width, and Template.

Step 3: Customize the transition associated with the state

When configuring a transition, you can use the set of controls in the Basic tab (in the Edit state dialogue) to do the following:

(This example illustrates configuring the transition that enables approvers to reject expense requests.)

	Customize the action buttons displayed in button mode If you have enabled button mode, you can customize the the look and feel of the respective action button. To do this, configure the Color and Icon of the button. In button mode, the UI displays a button grid to represent all the actions that you can perform based on your current position in the pipeline. For more information, see What is button mode a.k.a. Dummies mode?
	Associate the transition with a pre-defined system action You can associate the transition with one of around sixty different actions pre-defined on the platform. In most cases, these actions are executed within the workflow engine. Writing new system actions is simple as they are structured into a workflow using a set of common interfaces.  To configure a pre-defined transition, select an option in Transition (Workflow | Integration). Depending on the selected system action, you might need to configure parameters and their values to provide external input for the process. You can do this in the Properties tab. For more information, see Configuring parameters.
	Display custom content during the transition To display custom content during the content in a dialogue, you can select a data container in Data container for transition (Dialog). For example, you can set up a data container that enables the user to enter details related to the action, such as the reason for rejecting a request.
	Enable automatic transition between states You can set up an automatic transition, which means that the transition is automatically executed after arriving at the previous state. You can make a chain of automated actions by linking intermediate states with automatic transitions. The entire chain of actions would execute one after another until a state with multiple possible future states is reached. This could be one of the following: A state that requires a user decision. A transition configured with a data container that requires user input. To set up an automatic transition, enable Automatic (toggle button).

Configuring parameters

You can add parameters and configure their values to pass them to the workflow. For example, you can configure a parameter to:

• Assign an audience to a state
• Configure the template to be used in any action in a transition.

To configure a parameter, in the Properties tab (in the Edit state dialogue), click + Add option to add a new row. Then, enter the name and value in Option and Value, respectively.

See the following examples:

• Example 1: Using parameters when enabling email notifications for a transition
• Example 2: Using parameters when setting up push notifications

Example 1: Using parameters when enabling email notifications for a transition

To send email notifications to all audiences configured for the next state, you must do the following in the Edit state dialogue:

1. In the Basic tab, in Transition (Workflow | Integration), select EmiratesHR-Email-Send-To-Audience.

   

   This transition requires only one parameter; the name of the email template to be used.

2. In the Properties tab, enter template in Option and the name of the template in Value.

   

Example 2: Using parameters when setting up push notifications

The Yomly platform has a provision to send push notifications to mobile devices and registered web browsers. To enable this, do the following in the Edit state dialogue:

1. In the Basic tab, in Transition (Workflow | Integration), select EmiratesHR-Push-Notification-To-Audience.

   

   This transition does the following:

   • Renders the template passed and makes substitutions from the current context
   • Sends a push notification to the list of employees, emails, or audiences.

    This transition requires the following parameters:

   Parameter	Description
   template	A text string with the name of the push notification template to be used. It honours overrides in the local business before looking for the global template.
   sendto	An array of destinations. You can specify any combination of the following: Email addresses  Audience names Audience IDs manager (the manager dynamic audience) employee (the employee dynamic audience)

2. In the Properties tab, do the following:

   1. Enter template in Option and the name of the push notification template in Value.

      A UI that enables you to add a push notification template to the platform or update an existing template by yourself is currently in development. However, we can add or update a template in the database on request.

      See the following sample push notification template:

      "en": "A new payslip is now available for {{employee.fullName}}.",
      "ar": "قسيمة راتب جديدة متاح لك الآن{{employee.fullName}}"

      The template format supports the following:

      • Multiple languages (for example, here, both English and Arabic are supported) 

      • Substitution of variables from the current context.

      • Around 4000 characters of text in the message, which is adequate for a push notification

   2. Click + Add option to add another row for the second parameter.

   3. Enter sendto in Option and add the list of destinations based on your requirements in Value.