The Workflow subsystem allows you to automate simple actions in any of our Platform-based systems, as well as assign tasks for users to complete.


TABLE OF CONTENTS

1. Overview

The Workflow subsystem is divided into two main components: Processes and Automations. Processes are a set of tasks to complete in a defined order, and Automations are a set of simple actions that run automatically. These two components can interact with each other. For example, a process task could be to run an automation to completion, and an automation action could kick off a process.


1.1. Relationship Diagram

The following diagram may help to illustrate the relationships between these components:

  • An Automation consists of one or more Actions.
  • A Process consists of one or more Tasks.
  • An Action can optionally start one (and only one) Process.
  • A Task can optionally run one (and only one) Automation.


1.2. Where to Find the Workflow Subsystem

To find the workflow subsystem, log into your system of choice and choose an instance. If you have the correct access roles, you should see a gear-shaped icon in the left sidebar; it will have the label "Settings" when you hover over it. Click it and then open the tab called "Workflow". You will see four options, Automation, Automation Logs, Process Definitions, and My Tasks. These options will be explained in the sections below.


You can also view the status of all Automations and Processes related to a particular entity on its view.

2. Processes and Tasks

2.1. Process Definitions

To create a Process, we must first create a template for it, referred to as a Process Definition. This ensures that Processes can be instantiated multiple times. In the Settings sidebar, click on Process Definitions. Here, you will see a list of Process Definitions that have already been created, and you can click on the "New Process Definition" button to make a new one.


When creating a new Process Definition, you will have to enter a name for it, as well as choose its main component. This component can be any of our PicksmartEntity classes. The main component determines what entity can be used to kick off the process. Click "Save" when the required information has been entered.


You will then be taken to your new Process Definition. There are three main areas of interest here: the definition's information (where a kanban board will appear later); a list of Complete Process Instances; and a list of Task Definitions.


2.2. Task Definitions

Similarly to Process Definitions, tasks also require a template called a Task Definition. Click on "New Task Definition" to create a new definition. Task Definitions have several important fields to set:

  1. The first category is General Fields. Here, you set the Task Definition's name, its type (whether it's a Manual task or an Automation task), an optional component, and the Task Definition's delay (in hours). The delay will prevent a task from running until a certain number of hours have passed after its creation.
  2. The second category is Appearance. Here, you set the Task Definition's rank, its icon, and its color. The rank determines in what order the tasks will be run, with higher ranks (larger numbers) being run first. The icon and color are only used on the Process Definition's kanban board to give a visual representation of the Task Definition.
  3. The third category depends on what your Task Definition's type is. For manual tasks, you will see Manual / Approval Fields, and for automation tasks, you will see Automation Fields.
    1. Manual / Approval Fieldsinclude an assignment type. This determines how the task will be assigned to users for completion.
      1. A Claim assignment type means it won't be assigned to anyone, and users can claim it via the My Tasks page.
      2. A Direct assignment type allows you to pick a user to whom instances of the task will always be assigned.
      3. A Load Balanced assignment type assigns tasks to users based on the selected access roles. The user with the least amount of tasks will receive it.
      4. Finally, a Round Robin assignment type also assigns tasks based on the selected access roles, but in this case it assigns tasks by going down a list of applicable users.
    2. Automation Fields simply let you pick an automation to run.


After creating a Task Definition, you will see that a kanban board has appeared on the Process Definition's page. This provides a visual representation of all the Task Definitions (and their underlying tasks) you have created so far. The columns on the board are ordered by rank or (if the ranks are the same) alphabetically. Above the kanban board you will also see a button called "Start Process Manually". This will allow you to choose an entity (related to your main component) and kick off the process.


If you open one of your new Task Definitions, you will see several points of interest:

  • A kanban board. This is different from the Process Instance's kanban board in that it shows the possible states your Task Definition can have. A few states have been created for you already, but you can define your own Task State Definitions further down the page.
  • Complete Task Instances. This section shows instances of this Task Definition that have been completed.
  • Task State Definitions. Here, you can define what states your task can be in. Every task requires (at most) one Initial state, and one or more Final states.
  • Task Transitions. A transition defines where a process can go next once a task is completed. A task with no transitions is considered a final task. Once a final task completes, the entire process will complete.


2.3. Task State Definitions

A Task Definition can be in one of several states. By default, each task has one Initial state and one Final state, but you can add more states as you see fit. Just bear in mind that a task may only have one Initial state.


2.4. Task Transitions

Task Transitions determine where a process can go next after a task completes. A transition consists of a "From Task", a "To Task", and Transition Filters. The "From Task" is the task you are moving from, and the "To Task" is the task you are moving to. A task can also transition to itself. To avoid infinite loops, you should make use of Transition Filters. The "Overall Match Type" determines how the filters will be read - "Match All" means the filters will be taken as "filter AND filter AND filter..." while "Match Any" will be taken as "filter OR filter OR filter..."


When creating a new Transition Filter, select the field you would like to filter on. A Task Definition requires a component class for filters to work. Then, select your operator ("EQUALS", "IS NOT EQUAL TO", etc), and then finally enter the value you want to compare to.


2.5. Starting a Process

Once your Process Definition has been fully set up with Task Definitions, you can kick off a process. Click the "Start Process Manually" button on the Process Definition's page, or create an Automation that triggers your process. Once a process has started, you can see tasks assigned to you on the My Tasks page. The My Tasks page can be accessed via the left sidebar or your notification center in the topbar.


On the My Tasks page, you will see three lists.

  • The first one is My Outstanding Tasks, which are tasks assigned to you that have not been completed yet. You have several actions available in the righthand menu - Change State (if the task is incomplete), Transition Task, Snooze (if it has a due date set and it is not past its due date), and View.
  • Snoozing a task moves it to the My Snoozed Tasks list which will be temporarily hidden until you choose to action it.
  • The third list is Unassigned Tasks, which are claimable tasks that haven't been claimed yet. In its actions menu, you can Claim the task or View it. Claiming a task moves it to your Outstanding Tasks list and removes it from everyone's Unassigned Tasks lists.

3. Automations and Actions

3.1. Automations

An Automation is a set of small, simple Automation Actions that are completed in order. To create an Automation, navigate to Settings > Workflow > Automations in the sidebar and click the "New Automation" button.


An Automation has several sections of information that are visible depending on the trigger type you choose.

  1. The Generalsection includes information that every Automation requires.
    1. A name.
    2. Whether it is enabled or not.
    3. Whether it is global or not. A global automation will be available on any application instance. Non-global automations will only be available within the instance they were created.
    4. The automation's trigger type.
  2. If you choose "On Automation/Task", "On Button Press", "On Create", or "On Update" as the trigger type, the Componentsection will appear.
    1. Select the Component. This determines which PicksmartEntity this automation operates on.
    2. Enter a Component Search Depth. This is used when selecting fields from your component class for Automation Actions. With the default depth of 3, you will be able to select fields three levels deep in your entity (e.g. Contact -> CreatedBy -> AppInstance -> AppInstance's fields)
  3. If you choose "On Button Press" as the trigger type, the Buttonsection will appear.
    1. Enter a name for your button, choose its icon, and choose its color. Buttons will be shown on the Component entity's view.
  4. If you choose "On Schedule" as the trigger type, the Schedule option will appear. Choose how often you want the scheduled automation to run.


After creating your Automation, you will see a few points of interest on its view:

  • Filter Groups and Filters determine what specific entities this Automation runs on. For example, you could filter the entities so that the Automation only runs on ones with an enabled status.
  • Automations should have at least one Action. For example, it could send an email, or start a Process.


3.2. Filter Groups

To create a new filter group, click on "New Automation Filter Group". Here, you will be able to choose if Filters within the group have a match type of "Match All" or "Match Any". "Match All" means the filters will be taken as "filter AND filter AND filter..." while "Match Any" will be taken as "filter OR filter OR filter..." Click "Save".


Next, you can create Filters for your Filter Group. Choose the field you want to filter on, the operator (e.g. "EQUALS", "IS NOT EQUAL TO", etc.), and the value you want to compare to. Then save your changes.


3.3. Actions

When creating a new Automation Action, you must first choose the Action Type. Depending on your choice, several sections on the page will appear or disappear.


  • When the Action Type is Field Update, you will be shown a list of fields from your Component class. Select the checkbox next to the fields you want to update, and then enter (or choose) your new field value.


  • When the Action Type is New Record, you will choose the new record's entity class, and then fill in all the fields as necessary. The Dynamic Input column allows you to pull information from your Component entity and use it on this new record.


  • When the Action Type is New Subrecord, you will choose a field from your Component class. This field must allow you to add multiple child entities. You can then fill in the fields as needed, making use of the same Dynamic Input column as in New Record.


  • When the Action Type is Run Bot, simply choose a Selenium bot in our system to run.


  • When the Action Type is Send Email, choose the Recipient Type. A Static recipient is an email address directly you type in on the action, whereas a Dynamic recipientallows you to choose an email field from your Component class. You should then also select an Email Template to use.
    • Similarly, if the Action Type is Send SMS or Send Notification, you can choose whether the recipient is Static or Dynamic.


  • If the Action Type is Start Process, select a Process Definition to run.


  • Finally, if the Action Type is Webhook, select a Webhook to trigger.


After saving your Action, you will see a section below your Action's information called "Automations to Run on Failure". Here, you can define if the Action should start another Automation when it fails. For example, if an Action fails, you might want to send a notification to an admin. The priority of the On Failure Automation determines the order in which it will be run. A higher priority (larger number) Automation will run first.


3.4. Running an Automation

To run an Automation, perform its Trigger (create a new entity, update an entity, press a button, etc.) or click on "Run This Automation Now" on its view. There will be feedback to inform you if the automation ran successfully or not. Every automation run also generates several Automation Logs; one for each action carried out. To access Automation Logs, navigate to Settings > Workflow > Automation Logs in the sidebar or click on "Open Log (History) of Executions" on an automation's view.


If you are logged in as a system admin, you can also retry all failed Automations over the past 7 days, or manually clear all logs older than 60 days. Automations can only be retried twice.