Workflow Steps Guide

Overview

Workflow configuration is split into named workflow steps. Routes define which step will be executed when matching transaction criteria are met.

Workflow steps are maintained using the Portal. Read the Workflow user interface guide for more information about the interface use.

Workflow steps are defined using an XML model. The XML elements and attributes are a mix of mandatory and conditional values that define the behaviour of the workflow steps service.

Workflow step invocation

The service is typically called via the Routes service as the result of a p6route route evaluation. Possible headers values are:

Header value Description
step The workflow step’s name (required)
appkey The workflow step’s application key
flowName Fixed value for flow name. Use %UUID% to auto generated uuid formatted flow name.
status The initial status of the message (required)
script The name of the step template script
pipelineVar The input pipeline content to script, a pipeline is a map to share variables between scripts

Here is an example of a workflow step invocation via a route deployment script.

from("seda:wfroute.test")
    .when(xpath("/TransactionMetaData/TechnicalStatusCode='Pending'"))
        .setHeader("platform6.request.action").constant("invoke")
        .setHeader("status").constant("PENDING")
        .setHeader("step").constant("Dispatch Field Ticket")
        .setHeader("flowname").constant("%UUID%")
        .to("p6route://workflowsteps")   
    .otherwise()
        .throwException(com.amalto.b2box.core.api.B2boxException, "No matching rule found for item!")
    .end()
    .routeId("WF_Route.Test")

Note

Item Primary Key component headers are auto generated by the P6route component.

Header value: script

The script header allows a script to generate the workflow step definition XML.

This is useful when, for example, a transaction containing a cost centre is received and depending upon the value of this field, different workflow assignees are required.

Using the script header allows a steps XML configuration to be templated.

Script input pipeline

Header’s key Description
platform6.request.cluster The cluster (primary key component)
platform6.request.concept The item type (primary key component)
platform6.request.ids The ids as a comma separated list (primary key component)
templateStepXml The content of the current step XML defined by the step parameter as type text/xml

Script output pipeline

Header’s key Description
stepXml The new step XML configuration generated by the script (required)
stepName If available, will be used as the name of the new step stored as part of the service configuration

Note

A script defined with a none empty appKey that provides a stepName output variable will generate a step with an Id of: [appKey].[stepName] This is essential otherwise script generated steps could overwrite steps defined in other apps!

If the stepName is not available a new auto-generated service step configuration will be created with the name format: ___[paramstepname]_[GUID].

Note

A step XML generated via a script is not stored as a service’s configuration. However, it is stored in the generated workflow task for the lifetime of this workflow step.

Workflow custom forms

It is possible to use custom forms triggered by Workflow.

Workflow step modification

Inside the Action that is going to call the custom form, add a FormGenerator element with the name of the custom form.

 <Actions>
     <Action id="review" status="REVIEWED" type="FORM" transformer="AWF_Review">
         <Style>icon:fa-check,btn:btn-success</Style>
         <Label>
             <EN>Review</EN>
             <FR>Vérifier</FR>
         </Label>

         <FormGenerator>MyCustomForm</FormGenerator>
      ...
     </Action>
 ...
 </Actions>

The FormGenerator name must match that of a script in the Scripts service.

Parameters passed to the script

Four parameters are passed to the script from the pipeline:

  • pk: a JSON string containing the primary key of the workflow task.
{
    "dataCluster": "B2BOX",
    "concept": "AWFWorkItem",
    "ids": ["64cb15dafd0a11e699620242ac120005"]
}
  • xml: an XML string with the content of the workflow task.
  • user: the user’s email (id).
  • itemLinks: a JSON Array (string) with the list of Items Links (name, pk and type) of the workflow task.

[
    {
        "name": "MessageLink",
        "pk": {
            "dataCluster": "B2BOX",
            "concept": "MessageInfo",
            "ids": ["WFTestForm-2017-02-27 04:32:54 GMT"]
        },
        "type": ""
    }
]
Recovering the underlying Transaction (typically a MessageInfo)

Two solutions:

  1. Directly from the workflow task XML.

    def xml = pipeline.getXml "xml"
def mpk = transaction.buildPK(xml.itemDataClusterName.text(), xml.itemConceptName.text(), xml.itemIds.text().split('\\.'))
def message = transaction.get(mpk)

  2. From the Item Links (the Transaction is the first link).

    def itemLinks = pipeline.get "itemLinks"
def ils = new JsonSlurper().parseText(itemLinks)
def mpk = transaction.buildPK(ils[0].pk.dataCluster, ils[0].pk.concept, ils[0].pk.ids.toArray(new String[ils[0].pk.ids.size()]))
def message = transaction.get(mpk)

Sending the actual form

The form must be developed in JavaScript (or TypeScript) and available in the Scripts service.

The form can be passed a JSON model with data to be displayed in the form.

def model = [
    user: 'John Doe',
    companySiret: "48432937000049",
    latestProduct: [
        name: "b2box",
        url: "http://www.amalto.com"
    ]
]
pipeline.put "model", JsonOutput.toJson(model)
pipeline.put "form", scriptResources.getCompiled("MyCustomForm")

Implementing a custom workflow form

To get you started quickly on how to create your first custom workflow form, you can find a demo project in the platform6-custom-workflow-form repository.

It will allow you to generate a JavaScript bundled file which can be simply copy-pasted to any Script of your Platform 6 instance.

Please follow the instructions in the README.md of the repository to create, test and deploy your form on your instance.

Scripting

You can manage workflow steps with the Scripts service using the workflow DSL.

Actions

When a user takes an action defined in a workflow step (either built-in or custom form based) any script that is defined to be run upon that action will receive the following pipeline variable:

  • _wf_ui_action_origin

This variable indicates where in the portal user interface the action submission was made. The following string values are supported:

  • WORKFLOWTASKS_LIST
  • TRANSACTION_LINK
  • WORKFLOWTASK_LINK

Given this information a workflow step action script can make a decision regarding where the user should be directed following the sucessfull processing of the action submission.

To influence where the user is directed after action submission the action script should set the pipeline variable:

  • _wf_ui_action_destination

The following string values are supported:

  • WORKFLOWTASKS_LIST
  • WORKFLOWTASKS_LIST_REFRESHED
  • TRANSACTIONS_LIST
  • TRANSACTIONS_LIST_REFRESHED
  • LINK_ITEM
  • LINK_ITEM_REFRESHED

The REFRESHED modifier will cause the LIST or ITEM to be re-evaluated