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

NameDescriptionNote
BOOLEANBooleanSelect True/False
CLUSTERClusterSelect with the Cluster List
CODE_PAGEFile Code PageSelect with the enum (/ghibli-rest/v2/resources/enums/Charsets)
COMPRESSIONCompressionSelect with the enum (/ghibli-rest/v2/resources/enums/Compression)
COMPRESSION_STRATEGY_LEVELCompression strategy levelSelect with the enum (/ghibli-rest/v2/resources/enums/CompressionStrategyLevel)
CRON_EXPRESSIONCron expressionCron expr wizard
DATEDateInput type date
DATETIMEDate timeInput type date-time
DECIMALDecimalInput type numeric
ENUMEnumerationInput type string
EOLFile End of Line typeSelect with the enum (/ghibli-rest/v2/resources/enums/ResourceEol)
EXPRESSIONExpressionInput type text
FILEFileInput type text
INTEGERIntegerInput type numeric
LONGLongInput type numeric
RESOURCE_PROFILEResource profile(Cascader all the file resources associated with the selected partner and company)
SECURITY_CHIPER_ALGOSecurity Chiper AlgorithmSelect with the enum (/ghibli-rest/v2/resources/enums/SecurityCipherAlgorithm)
SECURITY_OPERATIONSecurity OperationSelect with the enum (/ghibli-rest/v2/resources/enums/SecurityOperation)
SECURITY_SIGNATURE_HASH_ALGOSecurity Signature Hash AlgorithmSelect with the enum (/ghibli-rest/v2/resources/enums/SecuritySignatureHashAlgo)
STRINGStringInput type time
TIMETimeInput type time format hh:mm:ss SSS
TIMEZONETime zoneSelect with the Timezone List
TRANSFER_PROFILETransfer profile(Cascader all the remote servers associated with the selected partner and company)
VIRTUAL_PATHVirtual path(Cascader all the virtual paths associated with the selected partner and company)
GBI_PROCESS_IDENTIFIERStringSelect 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.

OperatorPurpose
=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