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 preferred language.

This is typical:

• 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

The only attribute is enabled (boolean, default false).

<FlowName>

Mandatory/Defaults

No
anonymous

Description

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

Attributes

None.

<Description>

Mandatory/Defaults

No
No default(s)

Description

I18n list of step description.

Attributes

None.

<AllowTransactionEdit>

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.

<TransactionDataModel>

Mandatory/Defaults

No
TransactionInfo

Description

The data model to use for transactions in this flow. This value can also be defined via in the application.conf as: p6.service.workflowsteps.datamodel.

Attributes

None.

<ViewNames>

<Item>

Mandatory/Defaults

No
TransactionInfo

Description

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

Attributes

None.

<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.

<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.

<AllowApproverDelegation>

Mandatory/Defaults

Yes
false

Description

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

Attributes

None.

<SendEmails>

Mandatory/Defaults

Yes
false

Description

Should the workflow assignees be sent notification emails?

Attributes

An optional attribute profile containing the mail profile to use to send the mail. The profile name may contain a dot ‘.’ separated appKey and name. An appKey of “” will be assumed if no dot is specified.

<EmailTemplate>

Mandatory/Defaults

No
""

Description

The URI to a FreeMarker template to be used to generate an email message content. For example: file://${P6_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.

Attributes

The only attribute is modelScript, which designates a script that is called to enhance the email model.

Input parameters:

• platform6.request.dataPartition
• platform6.request.dataType
• platform6.request.ids

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

• Subject
• From
• CC

<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

The only attribute is 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).

<WorkflowTaskEnhancer>

Mandatory/Defaults

No
""

Description

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

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

• platform6.request.dataPartition
• platform6.request.dataType
• 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 Workflow Task Enhancement ***

// Response pipeline content will be added as additional workflow task attributes
def ixml = p6.pipeline.getXml '_DEFAULT_'

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

// 2.  Add project specific summary workflow task description
def dt = new Date().toString()
def descMap = [
    EN: "This is a short workflow task summary: " + dt, 
    FR: "Il s'agit d'un court résumé d'une tâche de travail: " + dt
]
p6.pipeline.put '_DESCRIPTION', descMap, 'application/p6core.i18n'

// 3.  Add common workflow task attributes required by the standard Platform 6 'Work Items' view
def stepXml = p6.pipeline.get '_wf_stepXml'

def statusMap = p6.workflow.localeText stepXml, "StatusLabels/Label[@name='" + p6.pipeline.get('_wf_statusId') + "']"
p6.pipeline.put 'Status', statusMap, 'application/p6core.i18n'

def assigneeMap = p6.workflow.localeText stepXml, 'Assignee/Label'
p6.pipeline.put 'AssignedTo', assigneeMap, 'application/p6core.i18n'

p6.pipeline.put '_ASSIGNEDTONAME', p6.pipeline.get('_wf_assignedToId'), 'text/plain'
p6.pipeline.put 'StartDate', p6.pipeline.get('_wf_instanceStartDate'), 'text/plain'

Attributes

The only attribute is script. Mandatory if using this element, it’s the name of a script to process and enhance a workflow task.

<Assignee>

Mandatory/Defaults

Yes
""

Description

This defines who will be assigned workflow tasks 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 means all users who hold the given position within 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 (eg: approvalworkflow=role('Invoice Approver')).

Note

The token ${INSTANCE_ID} in organizational tree paths will be auto expanded to the value of the current Platform 6 instance’s id. This is essential when packaging workflow steps in Platform 6 applications.

<Label>

Mandatory/Defaults

No
""

Description

I18n list of UI labels associated with this names assignee.

Attributes

None.

<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 an internationalized cross-reference.

Attributes

The only attribute is name, the status name used in the XML.

<Actions><Action>

Mandatory/Defaults

Yes
""

Description

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

Attributes

• id: an 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: 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 workflow task Ttl expires.
• DELEGATE: allows a user to assign the action of a workflow task to another user.
• display: boolean (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 dataPartition/dataType/ids parameters.
• stop: boolean (default false), when true this action will terminate the workflow for the current message. It’s the final step.
• allowMultiAction: boolean (default false), when true multiple workflow tasks can be selected and actioned in a single UI operation.

<Assignee>

Mandatory/Defaults

No:  DELEGATE action only
""

Description

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

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 means all users who hold the given position within 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 (eg: approvalworkflow=role('Invoice Approver')).

Note

The token ${INSTANCE_ID} in organizational tree paths will be auto expanded to the value of the current Platform 6 instance’s id. This is essential when packaging workflow steps in Platform 6 applications.

<Expiry>

Mandatory/Defaults

No:  EXPIRE action only
""

Description

This defines the behaviour of a workflow task expiry. If it is regarded as an error and whether or not an email is sent notifying an admin user.

Attributes

• error: boolean (default true), if true then a b2box ERROR log is raised when a workflow task expires.
• adminEmail: the email address of the workflow admin user to notify upon expiry (not mandatory).
• mailProfile: the mail profile to use to send the mail. The profile name may contain a dot ‘.’ separated appKey and name. An appKey of “” will be assumed if no dot is specified.

<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://${P6_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.

Attributes

The only attribute is modelScript, which designates a script that is called to enhance the email model.

Input parameters:

• platform6.request.dataPartition
• platform6.request.dataType
• platform6.request.ids

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

• Subject
• From
• CC

<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.
• btn: CSS string to customize the button render. Any CSS classes used in the Portal can be set here. Most commonly 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 read the label REJECT and the Ok button of the confirm modal.

  

The resulting string would be:

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

Work task display example:

Attributes

None.

<Label>

Mandatory/Defaults

Yes
""

Description

I18n list of UI labels associated with the action button.

Attributes

None.

<Parameters><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.

<Name>

Mandatory/Defaults

Yes
""

Description

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

Attributes

None.

<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.

Example

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

<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 drop-down inputs or checkboxes.

Attributes

None.

<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

The configuration of the above checkboxes:

<Parameters>
    <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>
</Parameters>

<DefaultValue>

Mandatory/Defaults

No
""

Description

The 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 checkboxes already selected) by providing the values as a string with comma separated values.

For SWITCH input type, if no default value is supplied (boolean) there will be a default state of the switch anyway (which is the false state).

Attributes

None.

<Label>

Mandatory/Defaults

Yes
""

Description

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

Attributes

None.

<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.

<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:

• itemDataType
• itemDataPartition
• itemIds (comma separated list)

Attributes

None.

Examples

Example of an XML configuration

<WorkflowStep enabled="true">
    <FlowName>InvoiceApproval</FlowName>

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

    <AllowTransactionEdit>ASSIGNEE</AllowTransactionEdit>

    <ViewNames>
        <Item>TransactionInfo</Item>
        <WorkItem>Work Items</WorkItem>
    </ViewNames>

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

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

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

    <WorkflowTaskEnhancer script="AWF_WorkItemEnhancer"/>

    <Assignee name="INVOICE_REVIEWERS" path="/dev/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>

            <Parameters>
                <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>
            </Parameters>
        </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 path="/dev/Branch A/Sub A-1" type="BRANCH" />

            <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 modelScript="AWF_BuildEmailModel">file://${P6_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>
</WorkflowStep>

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 -->
    <Parameters>
        <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>
    </Parameters>
</Action>

XSD validation

The structure of the XML is verified using a XSD.

To help you develop your application you can use that XSD to validate the code in your IDE (ie. if you are using P6Sync). Simply add the attributes to the root element as shown bellow:

<WorkflowStep  
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://documentation.amalto.com/platform6/latest/reference/built-in-services/workflow/workflow-tasks-guide/resources/WorkflowStep.xsd">
    ...
</WorkflowStep>

The documentation displayed in the XSD has been extracted from that page.