Workflows and contracts interaction

This section describes the interactions between workflows and contracts, including the variables that can be configured in a workflow and initialized in the contract.
The filters to be configured in a contract against specific triggers and how to use custom scripts, through a service called Script Task.

Variable types

Name	Description	Note
BOOLEAN	Boolean	Select True/False
CLUSTER	Cluster	Select with the Cluster List
CODE_PAGE	File Code Page	Select with the enum (/ghibli-rest/v2/resources/enums/Charsets)
COMPRESSION	Compression	Select with the enum (/ghibli-rest/v2/resources/enums/Compression)
COMPRESSION_STRATEGY_LEVEL	Compression strategy level	Select with the enum (/ghibli-rest/v2/resources/enums/CompressionStrategyLevel)
CRON_EXPRESSION	Cron expression	Cron expr wizard
DATE	Date	Input type date
DATETIME	Date time	Input type date-time
DECIMAL	Decimal	Input type numeric
ENUM	Enumeration	Input type string
EOL	File End of Line type	Select with the enum (/ghibli-rest/v2/resources/enums/ResourceEol)
EXPRESSION	Expression	Input type text
FILE	File	Input type text
INTEGER	Integer	Input type numeric
LONG	Long	Input type numeric
RESOURCE_PROFILE	Resource profile	(Cascader all the file resources associated with the selected partner and company)
SECURITY_CHIPER_ALGO	Security Chiper Algorithm	Select with the enum (/ghibli-rest/v2/resources/enums/SecurityCipherAlgorithm)
SECURITY_OPERATION	Security Operation	Select with the enum (/ghibli-rest/v2/resources/enums/SecurityOperation)
SECURITY_SIGNATURE_HASH_ALGO	Security Signature Hash Algorithm	Select with the enum (/ghibli-rest/v2/resources/enums/SecuritySignatureHashAlgo)
STRING	String	Input type time
TIME	Time	Input type time format hh:mm:ss SSS
TIMEZONE	Time zone	Select with the Timezone List
TRANSFER_PROFILE	Transfer profile	(Cascader all the remote servers associated with the selected partner and company)
VIRTUAL_PATH	Virtual path	(Cascader all the virtual paths associated with the selected partner and company)
GBI_PROCESS_IDENTIFIER	String	Select GBI Process using GBI Rest Interface

Filter

Every flow template triggered by a "NewFile/IncomingTransfer" event, not timers, has a field in its definition referred to as "Filter" so that the trigger will fire a new instance only if the filter is matched.

When the Filter is empty, it will always create a new instance no matter what the file will be.

The syntax used in the expression uses Groovy scripting.

It's not required to know the whole groovy language, just its operators to provide proper expressions resulting in the return of a "true or false" variable.

Operator	Purpose
=	equal
!=	different
<	less than
<=	less than or equal
>	greater than
>=	greater than or equal
&&	logical "and"
\|\|	logical "or"
!	logical "not"

These operators will work on Objects and their properties.

Here are some examples of real cases:

Trigger Type: NEW FILE

File variable is created when the trigger "New File" starts an instance, it is referred as file and its values come from the filesetEvent and their nature is as follows:

file {
  registryId = 11
  clusterName = "cluster1"
  virtualPath = "part1-vfs:/inbox"
  virtualFolder = "/inbox"
  virtualFS = "part1-vfs"
  name = "myFileName.txt"
  nameNoExtension = "myFileName"
  extension = "txt"
  absoluteFileName = "/home/ghibli/vfs/internal-volume/myFileName.txt.A00069E0.B0EA621E"
}

filesetEvent {
  fsrFilesetId = 9
  internalFile = true
  absoluteFilename = "/home/ghibli/vfs/internal-volume/myFileName.txt.A00067B6.B8519525"
  fileAccessUrl = "file:/home/ghibli/vfs/internal-volume/myFileName.txt.A00067B6.B8519525"
  originalFileName = "myFileName.txt"
  resourceId = "3f18857208cc5640d2fa0ab7a596ea28d40a923d"
  virtualPath = "part1-vfs:/inbox"
  creationTimestamp = null
  updateTimestamp = null
  databox = "part1-vfs:/inbox"
  databoxVersion = 0
  peerId = null
  clusterName = "cluster1"
  eventUTCDate = "Thu Jul 19 11:35:44 CEST 2018"
  timezoneId = "Europe/Rome"
  userName = null
  errorMessage = null
  errorMsgArgs = null
}

Trigger Type: INCOMING/OUTGOING TRANSFER

File variable is created when the trigger "Incoming transfer" or "Outgoing transfer" starts an instance, it is referred as file and its values come from the transferEvent and their nature is as follows:

file {
  registryId = 11
  clusterName = "cluster1"
  virtualPath = "part1-vfs:/inbox"
  virtualFolder = "/inbox"
  virtualFS = "part1-vfs"
  name = "myFileName.txt"
  nameNoExtension = "myFileName"
  extension = "txt"
  absoluteFileName = "/home/ghibli/vfs/internal-volume/myFileName.txt.A00069E0.B0EA621E"
}

transferEvent {
  eventId = "/b3705c37-a39c-423b-a0a2-3a8dbb6d39bc/86df2978-720c-46f8-bf34-aa9be4d0384c"
  eventType = "NOTIFICATION"
  eventUTCDate = "2020-06-12 09:55:59,995 +0200"
  timezoneId = "CET"
  emitterType = "TRANSPORT"
  eventSeverity = "OK"
  eventClassification = "TRANSFER_EVENT"
  peerId = "peer1"
  clusterName = "cluster1"
  userName = "part1"
  errorMessage = null
  errorMsgArgs = null
  transferId = 2018
  transferStatus = "COMPLETED"
  direction = "PUSH"
  mode = "SERVER"
  fsrFilesetId = 55
  filesize = 0
  sourceFile = "/test8.txt"
  destinationFile = "//IVNQM1/LOCALE/test8.txt"
  protocol = "FTP"
  tag = "test8.txt"
  transferRetry = 0
  sender = "172.18.0.1"
  contract = null
  contractVersion = 0
  databox = "part1-vfs:/IVNQM1/LOCALE"
  databoxVersion = 0
  partner = "part1
  partnerVersion = 0
  incomingcall = null
}

Trigger Type: INCOMING UPDATE METADATA

File variable is created when the trigger "Incoming update metadata" starts an instance, it is referred as file and its values come from the filesetMetadataEvent and their nature is as follows:

file {
  registryId = 11
  clusterName = "cluster1"
  virtualPath = "part1-vfs:/inbox"
  virtualFolder = "/inbox"
  virtualFS = "part1-vfs"
  name = "myFileName.txt"
  nameNoExtension = "myFileName"
  extension = "txt"
  absoluteFileName = "/home/ghibli/vfs/internal-volume/myFileName.txt.
A00069E0.B0EA621E"
}

filesetMetadataEvent {
  fsrFilesetId = 9
  internalFile = true
  absoluteFilename = "/home/ghibli/vfs/internal-volume/myFileName.txt.
A00067B6.B8519525"
  fileAccessUrl = "file:/home/ghibli/vfs/internal-volume/myFileName.txt.
A00067B6.B8519525"
  originalFileName = "myFileName.txt"
  resourceId = "3f18857208cc5640d2fa0ab7a596ea28d40a923d"
  virtualPath = "part1-vfs:/inbox"
  creationTimestamp = null
  updateTimestamp = null
  databox = "part1-vfs:/inbox"
  databoxVersion = 0
  peerId = null
  clusterName = "cluster1"
  eventUTCDate = "Thu Jul 19 11:35:44 CEST 2018"
  timezoneId = "Europe/Rome"
  userName = null
  errorMessage = null
  errorMsgArgs = null
  metadata = {
    key1 = "value1"
    key2 = "value2"
  }
}

A couple of examples will follow to better understanding how the Filter will behave, according to sample data provided here, with some of the following expressions specified in the Contract:

Expression:
file.registryId==666
Result:
FALSE, no instance will be created

Expression:
file.registryId==11
Result:
TRUE, a new instance will be created

Expression:
file.name=="myFileName.txt" && filesetEvent.clusterName=="clusterFake"
Result:
FALSE, no instance will be created

Expression:
file.name=="myFileName.txt" && filesetEvent.clusterName=="cluster1"
Result:
TRUE, a new instance will be created

Expressions that will return TRUE according above provided data:
file.name.contains("ileNam") && file.extension == "txt"
file.name.matches("myFileName.txt")
file.name.matches("myFileNam(.*)")
file.name.startsWith("myFil")

Syntax scripting Filter field


- Syntax Boolean matches(String regex) - Meaning Tests whether this string matches the desired regular expression (with regular expression syntax). - Parameters Regex − the expression for comparison.
- Syntax Boolean startsWith(String prefix) - Meaning Tests whether this string starts with the specified prefix. - Parameters Prefix – The prefix to search for
- Syntax Boolean endsWith(String suffix) - Meaning Tests whether this string ends with the specified suffix. - Parameters Suffix – The suffix to search for
- Syntax Boolean isEmpty() - Meaning Tests whether this string has a value. - Parameters NA

Scripting and Script Task

A Script Task is executed by a business process engine. The modeler or implementer defines a script in a language that the engine can interpret. When the Task is ready to start, the engine will execute the script. When the script is completed, the Task will also be completed.

— BPMN 2.0.2 Standard, 10.3.3, Script Task

In Primeur DATA ONE, Script Tasks are used to execute scripts in a JSR-223 compatible scripting language, for instance JavaScript or Groovy.

Scripts Tasks are mainly used to perform simple calculations or operations.

Here we leave snippets of an example used when developing Script Tasks to clarify the usage of some basic scripting operations and their syntax.

Example: DataType Conversion

testMe is a Process Variable inside a running instance, its type is int but we need to convert it to a String because we need to place it into a Map<String,String>.

This is the result according to the content of a Log Info Service Task containing:

TESTVARIABLE: ${testMe} - TOSTRING: ${execution.getVariable("testMe").concat("")} 
-  APPENDSTR: ${execution.getVariable("testMe").concat("example")} 
-  ADDNUMBER: ${execution.getVariable("testMe") +5}

The resulting log, once set testMe as an int variable assigned with 2 as value will be:

2018-07-30 16:18:00,264 
INFO  [com.primeur.ghibli.workflow.bpm.boundary.services.log.BpmLogInfoService] (pool-13-thread-1247) 
TESTVARIABLE: 2 - TOSTRING: 2 - APPENDSTR: 2example  - ADDNUMBER: 7