Workflow XML config

i18n Text Lists

Many of the workflow step attributes are used to create the portal user interface. As such all text should be entered in an internationalized form so that the user can experience the interface in their prefered language.

This is typically

• EN - English
• FR - French

Therefore i18n text lists are expressed in Xml as:

<ContainerElement>
    <EN>This is a test approve step</EN>
    <FR>Test d'approbation</FR>
</ContainerElement>

<WorkflowStep>

Mandatory/Defaults

Yes
No default(s)

Description

The root container element for the definition of a complete step. A step may be enabled or disabled.

Attributes

enabled: true/false (default false)

<WorkflowStep><FlowName>

Mandatory/Defaults

No
anonymous

Description

Used when a message can be involved in more than one workflow at the same time. This endures each uniquely named ‘flow’ will be managed separately.

Attributes

None

<WorkflowStep><Description>

Mandatory/Defaults

No
No default(s)

Description

i18n list of step description

Attributes

None

<WorkflowStep><AllowMessageEdit>

Mandatory/Defaults

Yes
ADMIN

Description

Determines by whom a message can be edited by once it has entered an active workflow. Possible values are: - ASSIGNEE - ADMIN - ORIGINATOR

Attributes

None

<WorkflowStep><ViewNames><Item>

Mandatory/Defaults

No
MessageInfo

Description

The ‘viewname’ to be used in generated <flink> elements referring to ‘instance’ message

Attributes

None

<WorkflowStep><ViewNames><WorkItem>

Mandatory/Defaults

No
WorkItem

Description

The ‘viewname’ to be used in generated <flink> elements in the instance message referring to ‘WorkItem’ message

Attributes

None

<WorkflowStep><AllowRecall>

Mandatory/Defaults

Yes
false

Description

Restricts the ability of a user to issue a recall action on a message at this step in the workflow

Attributes

None

<WorkflowStep><AllowApproverDelegation>

Mandatory/Defaults

Yes
false

Description

Restricts the ability of a user to delegate the action of a message to another user Attributes

None

<WorkflowStep><SendEmails>

Mandatory/Defaults

Yes
false

Description

Should the workflow assignees be sent notification emails?

Attributes

None

<WorkflowStep><EmailTemplate>

Mandatory/Defaults

No
""

Description

The URI to a FreeMarker template to be used to generate an email message content. For example: file://${B2BOX_DATA}/resources/templates/awfApproval.ftl

The model presented to FreeMarker will automatically include ${FirstName}, ${LastName} and ${Email}. Additional attributes can be bound into the model by returning pipeline variables from the modelScript.

See: http://freemarker.org/docs for template syntax.

Attributes

modelScript - A Script that is called to enhance the email model.

Input parameters:

• platform6.request.cluster
• platform6.request.concept
• platform6.request.ids

The following pipeline variables can be returned to influence the email template values:

• Subject
• From
• CC

<WorkflowStep><Ttl>

Mandatory/Defaults

No
0

Description

The Time To Live for the current workflow step. This is expressed as a number of minutes. A value of 0 means never expire. Once a workflow step expires a configured expiry action is run and the active workflow instance is closed.

Attributes

• id: The id of the defined action within this step configuration to run once expiry is detected. If no id is given the first action of type EXPIRE will be executed. (see later for details of expire action behaviour)

<WorkflowStep><WorkItem>

Mandatory/Defaults

No
""

Description

A work item enhancer script. The given script is executed and all output variables are assigned to a name/value property lists that is stored within the work item.

The following input pipeline variables are made available to the script:

• platform6.request.cluster
• platform6.request.concept
• platform6.request.ids
• _wf_activeInstanceId The <ActiveInstanceId> value to be used with the current message
• _wf_statusId The id of the current status of the message
• _wf_assignedToId The id of the assignee(s)
• _wf_stepId The current step id
• _wf_stepXml The XML step definition
• _wf_instanceStartDate The date the current workflow instance was started (ISO 8601 format)

Example Script

// *** Workflow Work Item Enhancement ***

// Response pipeline content will be added as additional work item attributes
def ixml = pipeline.getXml '_DEFAULT_'

// 1.  Add project specific values to show in work item view
pipeline.put 'CreationDate', ixml.CreationDate.text(), 'text/plain'
pipeline.put 'BusinessDocumentName', ixml.BusinessDocName.text(), 'text/plain'
pipeline.put 'BusinessDocumentNumber', ixml.BusinessDocNumber.text(), 'text/plain'

// 2.  Add project specific summary work item description
def dt = new Date().toString()
def descMap = [EN:'This is a short work item summary: ' + dt, FR:"Il s'agit d'un court résumé d'article de travail: " + dt]
pipeline.put '_DESCRIPTION', descMap, 'application/b2box.i18n'

// 3.  Add common work item attributes required by the standard b2box 'Work Items' view
def stepXml = pipeline.get '_wf_stepXml'
def statusMap = workflow.localeText stepXml, "StatusLabels/Label[@name='" + pipeline.get( '_wf_statusId' ) + "']"
pipeline.put 'Status', statusMap, 'application/b2box.i18n'
def assigneeMap = workflow.localeText stepXml, 'Assignee/Label'
pipeline.put 'AssignedTo', assigneeMap, 'application/b2box.i18n'
pipeline.put '_ASSIGNEDTONAME', pipeline.get('_wf_assignedToId' ), 'text/plain'
pipeline.put 'StartDate', pipeline.get( '_wf_instanceStartDate' ), 'text/plain'

Attributes

• script: Mandatory if using this element. The name of a script to process and enhance a work item.

<WorkflowStep><Assignee>

Mandatory/Defaults

Yes
""

Description

This defines who will be assigned work items when this step is called.

Attributes

• name: An id that is added to message xml to define the ‘assignee’
• path: A path to a node in the organizational tree
• type: User resolution at the given node in the tree; UNIT or BRANCH. UNIT means all users who hold the given position with the tree, BRANCH means all users holding the given position and all those who hold any position below the given node.
• scope: The required scope that a user must have to be assigned. E.g. ‘approvalworkflow=role(‘Invoice Approver’)’

<WorkflowStep><Assignee><Label>

Mandatory/Defaults

No
""

Description

i18n list of UI labels associated with this names assignee.

Attributes

none

<WorkflowStep><StatusLabels><Label>

Mandatory/Defaults

No
""

Description

i18n list of UI labels associated with workflow statuses. Each status is given an internal name which is used in the associated message XML. To dereference this name to display, these configuration elements are used as a internationalized cross reference.

Attributes

• name: The status name used in the XML

<WorkflowStep><Actions><Action>

Mandatory/Defaults

Yes
""

Description

The definition of actions that can be taken at this step in a workflow and the resulting status a message will attain.

Attributes

• id: A internal id for an action. Used internally.
• status: The status that will be written into the message XML and possibly dereference using <StatusLabels>
• type: ACTION, FORM, RECALL, EXPIRE or DELEGATE
• ACTION: A typical action where a user will be prompted for parameter input that will be stored with a message for subsequent processing
• FORM: Display a custom form generated by a server side groovy script (see <FormGenerator>)
• RECALL: Close the current active workflow and removes a message from the workflow processing
• EXPIRE: Used when a work item Ttl expires
• DELEGATE: Allows a user to assign the action of a workflow item to another user
• display: true/false (Default: true). Hint to the UI to show or hide this action.
• script: The name of a script that will be executed and passed the cluster/concept/ids parameters.
• stop: true/false (Default: false). When true this action will terminate the workflow for the current message. It’s the final step.

<WorkflowStep><Actions><Action><Assignee>

Mandatory/Defaults

No:  DELEGATE action only
""

Description

This defines the possible users that the current message can be delegated to

Attributes

• path: The path to a node in the organizational tree
• type: UNIT or BRANCH

<WorkflowStep><Actions><Action><Expiry>

Mandatory/Defaults

No:  EXPIRE action only
""

Description

This defines the behaviour of a work item expiry. If it is regarded as an error and wether or not an email is sent notifying an admin user.

Attributes

• error: true/false (default: true) If true then a b2box ERROR log is raised when a work item expires
• adminEmail: The email address of the workflow admin user to notify upon expiry (Not mandatory)

<WorkflowStep><Actions><Action><Expiry><EmailTemplate>

Mandatory/Defaults

No:  EXPIRE action only
""

Description

The URI to a FreeMarker template to be used to generate an email message content. For example: file://${B2BOX_DATA}/resources/templates/awfExpiry.ftl

The model presented to FreeMarker will automatically include ${FirstName}, ${LastName} and ${Email}. Additional attributes can be bound into the model by returning pipeline variables from the modelTransformer.

Attributes

• modelScript - The Script that is called to enhance the email model. Input parameters: cluster/concept/ids The following pipeline variables can be returned to influence the email template values:
  • Subject
  • From
  • CC

<WorkflowStep><Actions><Action><Style>

Mandatory/Defaults

Yes
""

Description

A formatted string to describe the render of the action button on the UI. The string is composed of 3 parts :

• icon: => the value will determine the icon used in the action button. Available icons are listed here: http://fontawesome.io/icons/
• btn: => css string to customize the button render. Any css classes used in the Portal UI can be set here. Most common used classes are in the screenshot below:

  

• color: => this is used in the confirm modals for actions without parameters (like “REJECT”). Available color codes are: “danger” (red), “info” (blue), “success” (bright green), “primary” (green), “default” (light grey), “warning” (orange) In the screenshot below, the “color:danger” part of the style string will set to red the label (“reject”) and the “ok” button of the confirm modal

icon:fa-share,btn:btn-info btn-trans,color:info

Work item display example:

Attributes

none

<WorkflowStep><Actions><Action><Label>

Mandatory/Defaults

Yes
""

Description

i18n list of UI labels associated to the action button

Attributes

none

<WorkflowStep><Actions><Action><Parameter>

Mandatory/Defaults

No
none

Description

You can add any number of parameters for a given action. On the UI, those parameters will be prompted to the user as a form when he triggers the action. All the filled values will be sent to the corresponding script. You can set various types of parameters: text, files, boolean, dropdown.

If an action doesn’t have any parameter set, a confirm modal will pop up when the user triggers it (this can prevent a missed click on certain actions…).

The DELEGATE action is a specific case and will display a form with the assignee user selection list based on the <Assignee> parameter.

Attributes

none

<WorkflowStep><Actions><Action><Parameter><Name>

Mandatory/Defaults

Yes
""

Description

Name of the parameter. This will be the variable name passed to the action script.

Attributes

none

<WorkflowStep><Actions><Action><Parameter><InputType>

Mandatory/Defaults

Yes
""

Description

The parameter type is mandatory and determines which form component the UI will display.

Possible values are: - TEXTAREA - TEXT - FILES - SELECT - CHECKBOX - SWITCH

Attributes

none

Here is an example for each input type, the screenshot shows a preview of what it looks like in the UI:

<WorkflowStep><Actions><Action><Parameter><Choices>

Mandatory/Defaults

Yes if the InputType of the action is SELECT or CHECKBOX
""

Description

Choices are a list of <Choice> elements to describe the available options for dropdown inputs or checkboxes

Attributes

none

<WorkflowStep><Actions><Action><Parameter><Choices><Choice>

Mandatory/Defaults

Yes
""

Description

A choice is composed by a label:

• SELECT input type => displayed in the list of options
• CHECKBOX input type => displayed alongside the checkbox control

A value which is used internally and sent to the script for the selected options by the user:

• SELECT input type => only one option can be selected by the user and the defined value is sent as a string to the script
• CHECKBOX input type => multiple options can be selected. The value sent to the server is a comma separated list of the selected values

Attributes

none

Example:

Configuration of the above checkboxes:

<Parameter>
    <Name>reasons</Name>
    <Label>
        <EN>Checkboxes</EN>
        <FR>Cases à cocher</FR>
    </Label>
    <Mandatory>false</Mandatory>
    <InputType>CHECKBOX</InputType>
    <Choices>
        <Choice>
            <Label>
                <EN>Value 1</EN>
                <FR>Valeur 1</FR>
            </Label>
            <Value>val_1</Value>
        </Choice>
        <Choice>
            <Label>
                <EN>Value 2</EN>
                <FR>Valeur 2</FR>
            </Label>
            <Value>val_2</Value>
        </Choice>
        <Choice>
            <Label>
                <EN>Value 3</EN>
                <FR>Valeur 3</FR>
            </Label>
            <Value>val_3</Value>
        </Choice>
    </Choices>
    <DefaultValue>val_3,val_2</DefaultValue>
</Parameter>

<WorkflowStep><Actions><Action><Parameter><DefaultValue>

Mandatory/Defaults

No
""

Description

Default value of the parameter. This is not applicable to files input.

Warning

For SELECT input type, if you want to select a default value, you should provide a value which is part of the defined ones in the <Choices> parameter For CHECKBOX input type, you can select multiples default values (multiple checkbox already selected) by providing the values as a string with comma separated values For SWITCH input type, if no default value is supplied (true or false) there will be a default state of the switch anyway (which is the “false” state)

Attributes

none

<WorkflowStep><Actions><Action><Parameter><Label>

Mandatory/Defaults

Yes
""

Description

i18n list of UI labels associated to the parameter. This will be displayed as the field label in the form.

Attributes

none

<WorkflowStep><Actions><Action><Parameter><Mandatory>

Mandatory/Defaults

Yes
""

Description

Possibles values are false or true. If the parameter is set as mandatory, the form won’t validate until a value is provided by the user.

Warning

Please note that for CHECKBOX and SWITCH input types, setting the input as mandatory will have no effect on validation as those inputs always have some default values. However, it will display a red asterisk ( * ) on the input label to indicate the user that this field is required.

Attributes

none

<WorkflowStep><Actions><Action><FormGenerator>

Mandatory/Defaults

No
""

Description

The name of a Script to call to request the ‘form’ and ‘model’ used to render a custom page on a UI.

This is typically implemented on the UI as a call to the script execute endpoint:

It is convention to pass item index attributes to the script using the form-urlencoded fields:

• itemConceptName
• itemDataClusterName
• itemIds (comma separated list)

Attributes

none

Example Configuration:

<Workflow enabled="true">

    <FlowName>InvoiceApproval</FlowName>

    <Description>
        <EN>This is a test review step</EN>
        <FR>Test de vérification</FR>
    </Description>

    <AllowMessageEdit>ASSIGNEE</AllowMessageEdit>
    <ViewNames>
        <Item>MessageInfo</Item>
        <WorkItem>Work Items</WorkItem>
    </ViewNames>

    <AllowRecall>false</AllowRecall>
    <AllowApproverDelegation>true</AllowApproverDelegation>

    <SendEmails>true</SendEmails>
    <EmailTemplate modelTransformer="AWF_BuildEmailModel">file://${B2BOX_DATA}/resources/templates/awfReview.ftl</EmailTemplate>

    <Ttl id="expire">300</Ttl>

  <WorkItem script="AWF_WorkItemEnhancer"/>

  <Assignee  name="INVOICE_REVIEWERS" path="/dev-v51/Branch_test" type="UNIT" scope="approvalworkflow=role('Invoice Approver')">
        <Label>
            <EN>Invoice review team</EN>
            <FR>Équipe d'examen des factures</FR>
        </Label>
    </Assignee>

  <StatusLabels>
        <Label name="PENDING_REVIEW" >
            <EN>Pending review</EN>
            <FR>En attente de vérification</FR>
        </Label>
        <Label name="REVIEWED" >
            <EN>Reviewed</EN>
            <FR>Vérifié</FR>
        </Label>
        <Label name="DELEGATED">
            <EN>Delegated</EN>
            <FR>Délégué</FR>
        </Label>
    </StatusLabels>

    <Actions>
        <Action id="review" status="REVIEWED" type="ACTION" script="AWF_Review">
            <Style>icon:fa-check,btn:btn-success</Style>
            <Label>
                <EN>Review</EN>
                <FR>Vérifier</FR>
            </Label>
            <Parameter>
              <Name>comments</Name>
                <Label>
                    <EN>Comments</EN>
                    <FR>Commentaires</FR>
                </Label>
                <Mandatory>false</Mandatory>
                <InputType>TEXTAREA</InputType>
            </Parameter>

            <Parameter>
              <Name>switchtest</Name>
                <Label>
                    <EN>True/False switch</EN>
                    <FR>Bouton on/off</FR>
                </Label>
                <DefaultValue>true</DefaultValue>
                <InputType>SWITCH</InputType>
            </Parameter>
        </Action>

        <Action id="reject" status="REJECTED" type="ACTION" stop="true" script="AWF_Reject">

            <Style>icon:fa-times,btn:btn-danger,color:danger</Style>

            <Label>
                <EN>Reject</EN>
                <FR>Rejeter</FR>
            </Label>

        </Action>

        <Action id="delegate" status="DELEGATED" type="DELEGATE">
      <Assignee name="REVIEW_DELEGATES" path="/dev-v51/Branch A/Sub A-1" type="BRANCH" >
            <Label>
                <EN>Anyone at unit b</EN>
            </Label>
        </Assignee>

            <Style>icon:fa-share,btn:btn-info btn-trans,color:info</Style>

          <Label>
                <EN>Delegate</EN>
                <FR>Déléguer</FR>
            </Label>

        </Action>

        <Action id="expire" status="EXPIRED" type="EXPIRE" display="false">

      <Expiry error="false" adminEmail="rd+wfadmin@amalto.com">
          <EmailTemplate modelTransformer="AWF_BuildEmailModel">file://${B2BOX_DATA}/resources/templates/Expired.ftl</EmailTemplate>
            </Expiry>

        </Action>

        <Action id="recall" status="RECALLED" type="RECALL" script="AWF_Recall">

            <Style>icon:fa-ban,btn:btn-danger btn-trans,color:danger</Style>

          <Label>
                <EN>Recall</EN>
                <FR>Annuler</FR>
            </Label>

        </Action>

    </Actions>

</Workflow>

Custom FORM Request/Response Actions

<Action id="flipRequest" status="FLIPPED" type="FORM" stop="true" script="AwfFlip">
    <Style>icon:fa-check,btn:btn-success</Style>
    <Label>
        <EN>Flip</EN>
        <FR>Flip</FR>
    </Label>

    <FormGenerator>EndpointExample</FormGenerator>

    <!-- These parameters are only used by the server to validate parameter submission when this action is triggered -->

    <Parameter>
        <Name>comments</Name>
        <DefaultValue>No comment!</DefaultValue>
        <Mandatory>false</Mandatory>
        <InputType>TEXTAREA</InputType>
    </Parameter>
    <Parameter>
        <Name>code</Name>
        <Mandatory>false</Mandatory>
        <InputType>TEXT</InputType>
    </Parameter>
    <Parameter>
        <Name>files</Name>
        <Mandatory>false</Mandatory>
        <InputType>FILES</InputType>
    </Parameter>
</Action>