Workflow

overview servicely provides the ability to create complex custom workflows activity type icon description comment allows the placing of comments onto workflows user action represents a status and a set of actions that are to be made available to users typically used to present a set of options to the user when the workflow is at a point where there are manual actions or decisions that must be made by the user available actions will be presented to the user on the form to allow the user to advance the workflow approval allows approval steps to be added to a workflow complete represents the end/completion of a workflow scriptable provides the ability to run a custom script as part of the workflow designed to be a synchronous script that executes once per pass does not generate a workflow status by default, as the workflow does not pause here scriptable async provides the ability to run a custom script as part of the workflow designed to be used when the action is asynchronous (e g triggering an integration or awaiting other tickets/actions) generates a workflow status so the associated record indicates the wait state timer allows a timer to be scheduled to progress the ticket (e g could be used for auto closure or any other time based progression) if/else provides the ability to branch the workflow based on a simple conditional query switch provides the ability to branch the workflow based on a custom script designed to be a synchronous script that executes once per pass does not generate a workflow status by default, as the workflow does not pause here switch async provides the ability to branch the workflow based on a custom script designed to be used when the action is asynchronous (e g triggering an integration or awaiting other tickets/actions) generates a workflow status so the associated record indicates the wait state run action provides the ability to run an intelligent action exception provides the ability to respond to an exception anywhere in the workflow making updates check in/check out a workflow can only be updated by a single person at any given time this is because that in order to edit a workflow, one must "check out" the workflow first when a workflow is not checked out by you, you will not be able to update it after you have made your changes and published it, you should "check in" the workflow so that another administrator can check it out if they need to, to make required updates the "check in workflow" and "checkout workflow" buttons are available at the bottom of the workflow screen if a workflow is checked out by someone, you will see who that is in the workflow definition screen's "checked out by" field publishing an update every workflow's change needs to be published before it takes effect to publish, find and left click on the publish version button on the workflow editor screen you will then be requested to provide a summary of your update for version history purposes example below in the workflow definition screen, you will also see "versions" tab that lists the versions to date after you had created a workflow, ensure that you have published it before you can use it if you made a change to an existing workflow with existing published version, you will need to publish it before the changes take effect however, note that existing records running the workflow will continue running the respective workflow versions that the workflow had at the time of those respective record's creation only records created after you publish the workflow's latest changes, will get those changes workflow activities user action the user action workflow activity typically represents a status and provides the ability for end users to control the workflow, by presenting the the user with multiple options to progress the workflow status to adding transition options press the ‘add new transition’ button (crosshair icon on the right of the activity box), an enter the new transition name a transition can run a before script for purposes such as making a field to be mandatory before the status transition can take place an example is, to make the assignee field on incident table before moving the incident off from new to work in progress status you would code something like below you will need to end the before script with a return true; statement, so that the rest of the form checks can run to completion linking to next activity drag from the circle in the transition to the left most corner of the target workflow activity timer you can configure a workflow to wait for a fixed or dynamic duration example below is to wait for 2 seconds note that this is pretty common way to start a workflow if the first workflow activity is to be an approval this is so that the created record, e g itsmrequest has completed its creation process and everything is in place for the workflow to start asking for approvals approval this activity requests approvals and will stop the records running the workflow from proceeding any further what you can configure item description example approval mechanism section approval requirement whether this approval step only requires one or more approvers to approve before the associated record can proceed to the next step of the approvals options are all approvals required one approval required percentage of approvals required scripted one approval required approval requirement script appears when “approval requirement” is set as “scripted” this is to handle more complex scenarios that the other 3 approval requirement types cannot the script needs to return the answer variable, a value of true indicates an approval while a value of false is for a rejection complete on first rejection appears when the “approval requirement” is set as “one approval required” or “percentage of approvals required” if set to yes, this will move the workflow to the next step on first rejection yes force comment if set to yes, both approval and rejection reasons will ask for comment no approvers section assignees users that will be requested to approve groups groups whose members will be requested to approve dynamic approver source select a field that has the approver(s) needed for this activity it can be a reference or multi reference field for example in work table, there is a multi reference field called approver that is commonly used for itsmrequest ad hoc approval or change's first level approval approver advanced approval set to yes if the approver list is not static, e g approver should be ticket’s requestor’s manager yes business logic appears when “advanced approval” is set to yes this needs a script and should return a queried table record object more information on table record, please view table api (server) refer below this table for examples approve if no assignees if set to yes, the approval will be automatically approved if no one is found to be the approvers otherwise the approval will be rejected no templating section subject used in forms and notifications to describe the purpose of the approval cab approval instructions used in forms and notifications to provide instructions to the user about the purpose of the approval approve/reject once cab meeting had been held below is an example of business logic script when the approvers are members of a group whose id is defined in an application property let approverarr = table("group") get(applicationpropertymanager getproperty("change approval cab group id")) relation("member") map(approver => approver id()); if (approverarr length !== 0) { table("user") in("id", approverarr) map(r => r); } below an example of business logic script when the approver is a manager selected in a catalog item's question if (current questions() eomanager hasvalue()) { table("user") equal("id", current questions() eomanager value()) map(r => r); } scriptable the ‘scriptable’ activity allows the workflow author to run server side code (e g send a scripted notification, set field values, call integrations, etc) this activity is typically transient and does not have a workflow status associated with the activity example below shows a workflow that when it gets to a scriptable activity called "change status to emergency", it will set a field called "category" to value of "emergency" script context the ‘scriptable activity’ receives the following script context items item description current a tablerecord object representing the object associated with the workflow context a plain json map object which can be used to store state associated with the workflow log a script logger that allows logs to be written to the workflowhistory log there is no need to run current update(); if you need to modify one or more fields in the "current" object scriptable async the ‘scriptable async’ activity allows the workflow author to run server side arbitrary code usage is similar to the ‘scriptable activity’ with the primary difference being that this activity is designed to be used when the result of the script is asynchronous (i e the activity needs to wait on something external happening) this activity creates an associated workflow status example below shows a workflow for hrcase records when it gets to a scriptable async activity called "wait for subtasks", it will create a hrcasetask record, and then not progress further until all hrcasetasks for the current record are closed off the scriptable async activity exposes two scripts an initialization script and an evaluation script the initialization script is called once when the activity is initiated, and is designed to be used to perform any initialization associated with the activity (initiate an integration, raise subtasks, etc ) the evaluation script is called asynchronously to determine whether the activity has completed this needs to be performed by an external action (e g on completion of an integration) a convenience method is available to automatically evaluate paused workflows for related tickets (e g for subtasks or other related information) table property description example workflow\ trigger parent field a table property that specifies a relationship that will trigger an asynchronous workflow evaluation of the related record can also be a comma delimited list of relationships on the hrcasetask table, specifying the value “parenthrcase” will enable the evaluation of the workflow related to hrcase records, on updates of hrcasetask records script context the ‘scriptable async activity’ receives the following script context items item description current a tablerecord object representing the object associated with the workflow context a plain json map object which can be used to store state associated with the workflow log a script logger that allows logs to be written to the workflowhistory log activityoptions constants used for the return value or other items within the script scriptable async actions that have not yet completed their requirements should return the value activityoptions delay evaluation scriptable async actions that have completed their requirements should return true switch a switch allows a workflow's path to branch to different parts of the workflow it is transient and should not be linked to a status example below shows three possible paths a workflow can take depending on the outcome of the switch the switch's script has access to the current object (the record the workflow runs for) and its related catalog questions' answers, if the current record was submitted from the catalog to decide which path a switch will take a workflow instance to, the script needs to set variable "answer" with the "code" of one of the switch's available transitions in the example above, there are three transitions sydney, melbourne and singapore to find out of a transition's code, double left click on it to bring up the definition if you want to add more possible transitions for a switch, left click on the crosshair icon, the same way as adding transitions to a user action activity other configuration initial activity ensure that you have an initial activity set or the workflow will not start an initial activity has the triangle play button to the left of the activity label below shows an activity named "initialise" set as the workflow's initial activity to set an activity to be the workflow's initial activity, right click on the activity header and left click on "set initial activity" alternatively, you can also find "initial activity" field in the workflow's definition record execution order when there are multiple workflows for the same table, e g itsm request table having multiple workflows for different catalog items, please ensure that they are ordered accordingly this is necessary for the use case where the workflow is attached to the table not because of service catalog, e g raising itsm request directly when a record such as itsm request is directly created (not via catalog item that has its own workflow), servicely will select the workflow with lowest order number this means a workflow with order of 10 will take precedence over the one with order of 20