Workflow Steps 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
: EnglishFR
: 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 MessageInfo
Description
The data model to use for transactions in this flow.
This value can also be defined via in the application.conf
as: service.workflow.datamodel
.
Attributes
None.
<ViewNames>¶
<Item>¶
Mandatory/Defaults
No MessageInfo
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://${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
.
Attributes
The only attribute is modelScript
, which designates 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
<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).
<WorkItem>¶
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.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 Workflow Task Enhancement *** // Response pipeline content will be added as additional workflow task attributes def ixml = pipeline.getXml '_DEFAULT_' // 1. Add project specific values to show in 'Work Items' 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 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 ] pipeline.put '_DESCRIPTION', descMap, 'application/b2box.i18n' // 3. Add common workflow task attributes required by the standard Platform 6 '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
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 treeUNIT
means all users who hold the given position with the treeBRANCH
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 (defaulttrue
), 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
: boolean (defaultfalse
), when true this action will terminate the workflow for the current message. It’s the final step.
<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
orBRANCH
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 (defaulttrue
), 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://${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
.
Attributes
The only attribute is modelScript
, which designates 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
<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.
<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:
<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>
<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:
itemConceptName
itemDataClusterName
itemIds
(comma separated list)
Attributes
None.
Examples¶
Example of an XML configuration
<Workflow 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>MessageInfo</Item> <WorkItem>Work Items</WorkItem> </ViewNames> <AllowRecall>false</AllowRecall> <AllowApproverDelegation>true</AllowApproverDelegation> <SendEmails>true</SendEmails> <EmailTemplate modelScript="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/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/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 modelScript="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>