Configuring Triggerable Service Tasks 🚀
Last updated
Last updated
STENG peers perform triggerable tasks that are often related to long-lasting operations, like transports.
The main action is to request the schedule of an operation from a subsystem and to save the exit code in the RC variable if it exists.
When the service task finishes, the flow does not continue immediately. Instead, it enters a wait state that uses no resources until the scheduled operation is complete. At that point, the process engine will resume. The value of the RC variable will be updated to replace the scheduled exit code with the actual code from the completed action, and then the instance will be re-triggered to move to the next step.
All Triggerable Service Tasks are organized with a description of the service task and the variables it includes.
List of Triggerable Service tasks in alphabetical order:
🚀
🚀
By design, all triggerable service tasks wait for a trigger before proceeding to the next step and that is why they always throw a BpmServiceException when receiving a schedule return code that is not 0 (Return Code OK). Otherwise, they will wait for an event that will never come, since the scheduled operation failed.
Description
When a FileSet ID is provided, it will be associated with the designated VirtualBox name.
Variables
File ID
VariableType.LONG
Y
Fileset ID to operate the BIND operation to
Virtual Box
VariableType.VIRTUAL_BOX
Y
Virtual Box name where the given FileSet ID will be bound to
Description
The Data Shaper Processor service task is used in workflow templates to be consumed in Input, Mediation, and Output Contracts to invoke Data Shaper graphs.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster hosting a Data Shaper installation that will be used to execute the graph
Payload
VariableType.DATASHAPER_PAYLOAD
Y
Variable dynamically filled at contract level with the required information to invoke a Data Shaper graph. Follow these steps to configure it: 1. Select a Sandbox. 2. Choose one of the graphs in the selected Sandbox. 3. The variables required by the selected graph to be executed will appear.
Description
The Event Notification service task emits a notification on the "Generic local action" event on the notification channel specified in the service task.
Variables
notificationChannelName
VariableType. NOTIFICATION_CHANNEL
Y
Name of the Notification channel that will receive the event.
actName
VariableType.STRING
Y
Logical name of the operation, used by DataWatcher when rendering a given actCode.
actAttrsPrefix
VariableType.STRING
Y
Prefix used in Action attributes; the default is "actAttrs_". Action attributes are a list of variables injected at runtime in a workflow context. Each attribute is structured as a couple of: - name: string element containing the name of the attribute (starting with the mentioned prefix). - value: string element containing the value of the attribute. Example: actAttrs_MyAttrName= MyAttrValue
actOutcome
VariableType.ENUM
Y
Allowed values: - running - success (default) - failure
actErrCode
VariableType.STRING
N
Attribute applied only when actOutcome is set to failure and indicates the error code associated with the failure.
actErrMsg
VariableType.STRING
N
Attribute applied only when actOutcome is set to failure and indicates the error code associated with the failure.
dcName
VariableType.STRING
Y
Logical name of the data container, typically a filename.
Description
The GUnzip File service task invokes the SpGunzip service on an input file (gzip archive) and gunzips it, producing a new file.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Input File
VariableType.STRING
Y
Full pathname (with filename) for the file to be uncompressed
Output file Path
VariableType.STRING
Y
Full pathname (with filename) for the output file
Return Code variable
VariableType.STRING
Y
Workflow variable where the final return code will be written
Description
It invokes the SpGzip compression service on an input file that produces a gzip archive.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Input File
VariableType.STRING
Y
Full pathname (with filename) for the file to be compressed
Output file Path
VariableType.STRING
Y
Full pathname (with filename) for the output file
Compression strategy
VariableType.COMPRESSION_STRATEGY_LEVEL
Y
Strategy level of compression
Compression level
VariableType.STRING
Y
Level of compression
Return Code variable
VariableType.STRING
Y
Workflow variable where the final return code will be written
Description
It performs an antivirus/DLP check on a file inside the filebox using a specific ICAP engine and returns the outcome of the check.
Input Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Icap
VariableType.ICAP
Y
ID of the ICAP engine that will perform the scan
File ID
VariableType.LONG
Y
ID of the file to be checked (Tip: if the file is in a "FileDetail" variable, its ID can be retrieved with ${file.getRegistryId()} )
Scan mode
VariableType.ENUM
N
Scan mode (ANTIVIRUS or DLP)
Icap method
VariableType.ENUM
N
ICAP method (REQMODE or RESPMODE)
Exception If Harmful
VariableType.BOOLEAN
N
It throws an exception in case of scan error (e.g. the scan has been completed successfully and the file is harmful/contains sensitive data)
Exception On Failure
VariableType.BOOLEAN
N
It throws an exception in case of scan failure (e.g. the scan failed because of a connectivity error or an unexpected error from ICAP server)
Output Variables
icap_rc
VariableType.STRING
Result of scan. For a detailed list of all the possible results, see the table below.
"0"
Scan performed successfully, the file is safe
"64"
Scan performed successfully, the file is harmful
This result can be returned only if throwExceptionIfHarmful == false
"2"
Scan not performed, file not found
This result can be returned only if throwExceptionOnFailure == false
"3"
Scan not performed, file too big
This result can be returned only if throwExceptionOnFailure == false
"4"
Scan not performed, the ICAP server is unreachable
This result can be returned only if throwExceptionOnFailure == false
"5"
Scan not performed, the ICAP server returned an error
This result can be returned only if throwExceptionOnFailure == false
"32"
Scan not performed, some other error prevented it
This result can be returned only if throwExceptionOnFailure == false
Description
When you provide a VirtualBox name, all related files will be listed as ExternalFile objects in the File List variable.
Variables
Virtual Box
VariableType.VIRTUAL_BOX
Y
Virtual Box name where the given FileSet ID will be bound to
File List
VariableType.STRING
Y
Variable that will contain the list of files as a result of the current operation. (Tip: You can cycle through elements of a list using the Subprocess object)
Description
It invokes the Execute Shell command service provider.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Executable
VariableType.STRING
Y
Command to be executed in the command line
Arguments
VariableType.STRING
N
List of arguments to be passed to the command execution 🚀 This field handles blanks and special characters. As per the standard Unix protection methods, enclose filenames in single or double quotes. Examples: ls -l "/tmp/max/Dir with blanks" ls -l '/tmp/max/Dir with blanks' touch "/tmp/max/Dir with blanks/$aa%bb&cc()dd=[]dd{};:zz.txt"
Std Out
VariableType.STRING
Y
Name of a variable that will be filled with standard output logging
Std Err
VariableType.STRING
Y
Name of a variable that will be filled with standard error logging
Return code
VariableType.STRING
Y
Workflow variable where the final return code will be written
Return code management
VariableType.BOOLEAN
N
If checked, it will forcefully fail the command if a Return Code that is not 0 is returned. Otherwise, it completes with SUCCESS whatever the RC will be for backward compatibility
Description
It invokes the "LS" command on the filesystem that lists the content of a local file system folder.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Username
VariableType.STRING
N
Username used by this command
Password
VariableType.STRING
N
Password for the username used by this command
Path
VariableType.STRING
Y
Local path where file listing will be performed
List
VariableType.STRING
Y
Variable that will contain the list of files as a result of the current operation. (Tip: You can cycle through elements of a list using the Subprocess object)
Return Code variable
VariableType.STRING
Y
Workflow variable where the final return code will be written
Description
It invokes SPCONV conversion Command Service that converts an input file codepage and EOL, creating a new file.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Input File
VariableType.STRING
Y
Input file path for conversion
Output file Path
VariableType.STRING
Y
Full pathname (with filename) for the output file to be converted
Input Code Page
VariableType.CODE_PAGE
Y
Codepage of the input file
Output Code Page
VariableType.CODE_PAGE
Y
Codepage that will be written to the output file
Input EOL
VariableType.EOL
N
EOL used in the input file
Output EOL
VariableType.EOL
N
EOL that will be written in the output file
Return code
VariableType.STRING
Y
Workflow variable where the final return code will be written
Description
It invokes the SPGet Service that retrieves a file from a Virtual File System folder and saves it to a local folder.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Source
VariableType.VIRTUAL_PATH
Y
Virtual path where the file will be taken
File
VariableType.STRING
Y
Filename that will be taken in the previously set virtual path
Destination Path
VariableType.STRING
Y
Destination path where the fill will be placed by the task
File Name
VariableType.STRING
N
Filename that will be used for the final file
Resource profile
VariableType.RESOURCE_PROFILE
N
ResourceProfile, if any, to be applied during the operation
Return Code variable
VariableType.STRING
Y
Workflow variable where final return code will be written
Description
It invokes the Local SpPut service that retrieves a file from a local folder and uploads it to a Virtual File System.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
File
VariableType.STRING
Y
Filename that will be get in the previously set virtual path
Source
VariableType.STRING
Y
Source path where the file will be get
Destination
VariableType.VIRTUAL_PATH
Y
Destination virtual path were the file will be placed
Resource profile
VariableType.RESOURCE_PROFILE
N
ResourceProfile, if any, to be applied during the operation applied to the transport
FilesetID created
VariableType.STRING
Y
Name of the variable that will contain the RegistryID (FilesetID) of the created file
Return Code variable
VariableType.STRING
Y
Workflow variable where the final return code will be written
Description
It invokes the VirtualPath SPLS command that lists the content of a Virtual File System folder.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Virtual Path
VariableType.VIRTUAL_PATH
Y
Virtual path to use for file listing in the current operation. (Tip: It's a remote path, so plain String, not a VirtualPath)
File List
VariableType.STRING
Y
Variable that will contain the list of files as a result of the current operation. (Tip: You can cycle through elements of a list using the Subprocess object)
Return code
VariableType.STRING
Y
Workflow variable where the final return code will be written
Description
It invokes the SpMailPull command service that retrieves a Mail from a remote file system and writes it to a Virtual file system.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Transfer profile
VariableType.TRANSFER_PROFILE
Y
TransferProfile to use. Tip: It's a configured server where the current task will happen.
VFS unverified
VariableType.STRING
Y
Virtual file system where email(s) that are not verified will be placed
Remote path
VariableType.STRING
Y
Remote Path
VFS verified
VariableType.STRING
Y
Virtual file system where email(s) that are verified will be placed
VFS discarded
VariableType.STRING
Y
Virtual file system where email(s) that are discarded will be placed
Raw
VariableType.STRING
Y
Virtual path folder name where the raw mail is stored
Attachment Virtual Path
VariableType.STRING
N
Virtual path folder name where the attachment is stored
Disposition
VariableType.STRING
N
Email desired disposition behavior
Return Code variable
VariableType.STRING
N
Workflow variable where the final return code will be written
Description
It invokes the SpMailPush command service that sends a Mail from a Virtual file system.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Transfer profile
VariableType.TRANSFER_PROFILE
Y
TransferProfile to use. Tip: It's a configured server where the current task will happen.
To
VariableType.STRING
Y
Destination of the email
From
VariableType.STRING
Y
Sender of the email
Subject
VariableType.STRING
Y
Subject of the email
Body
VariableType.STRING
Y
Body of the email
Raw
VariableType.STRING
Y
Virtual path folder name where the raw mail is stored
FileSet Id
VariableType.LONG
N
Referenced FilesSet ID for this email
Mail Sign
VariableType.STRING
N
Whether the email sign is required or not
Alias Sign
VariableType.STRING
Y
Email sign alias key (mandatory if 'Sign Mail' is required)
Return Code variable
VariableType.STRING
N
Workflow variable where the final return code will be written
Description
It invokes SpMailPush templated command service.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Transfer profile
VariableType.TRANSFER_PROFILE
Y
TransferProfile to use. Tip: It's a configured server where the current task will happen.
To
VariableType.STRING
Y
Destination of the email
From
VariableType.STRING
Y
Sender of the email
Subject
VariableType.STRING
Y
Subject of the email
TemplateId
VariableType.STRING
Y
Identifier to the HTML template to be used for the body
Return Code variable
VariableType.STRING
N
Workflow variable where the final return code will be written
Description
It invokes the PGP Crypt service on an input file that produces an encrypted file.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Input file
VariableType.STRING
Y
Full pathname (with filename) for the file to be encrypted
Output file
VariableType.STRING
Y
Full pathname (with filename) for the output file
Operation security
VariableType.SECURITY_ OPERATION
Y
Security operation
Recipient
VariableType.STRING
Y
Recipient of the file
Alias key
VariableType.STRING
Y
Alias key to use for encryption
Hash algorithm
VariableType.SECURITY_ SIGNATURE_HASH_ALGO
Y
Hash algorithm of the security signature
Cipher algorithm
VariableType.SECURITY_ CHIPER_ALGO
Y
Cipher security algorithm
Return Code variable
VariableType.STRING
Y
Workflow variable where the final return code will be written
PGP format
VariableType.STRING
Y
PGP format in binary or ascii-armor
Description
It invokes PGP Decrypt service on an input encrypted file and it produces a decrypted file.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Input file
VariableType.STRING
Y
Full pathname (with filename) for the file to be decrypted
Output file
VariableType.STRING
Y
Full pathname (with filename) for the output file
Return Code variable
VariableType.STRING
Y
Workflow variable where the final return code will be written
PGP format
VariableType.STRING
Y
PGP format in binary or ascii-armor
Description
It invokes the Remote SpLs service that lists the content of a remote folder.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Remote path
VariableType.STRING
Y
Remote path to use in the current operation. Tip: It's a remote path, so plain String, not a VirtualPath.
Transfer profile
VariableType.TRANSFER_PROFILE
Y
TransferProfile to use. Tip: It's a configured server where the current task will happen.
Resource profile
VariableType.RESOURCE_PROFILE
N
TesourceProfile, if any, to be applied during the operation
List
VariableType.STRING
Y
Variable that will contain the list of files as a result of the current operation. (Tip: You can cycle through elements of a list using the Subprocess object)
Return code
VariableType.STRING
Y
Workflow variable where the final return code will be written
Description
It invokes the SpMkdir service that creates a new folder on a remote path.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Remote path
VariableType.STRING
Y
Remote path of the folder to create
Transfer profile
VariableType.TRANSFER_PROFILE
Y
TransferProfile to use. Tip: It's a configured server where the current task will happen
Return Code variable
VariableType.STRING
Y
Workflow variable where the final return code will be written
Description
It invokes the SpMv service that moves a file from a source location to a destination.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Source
VariableType.STRING
Y
Source path to be moved
Path
VariableType.STRING
Y
Destination path after the move command has been performed
Transfer profile
VariableType.TRANSFER_PROFILE
Y
TransferProfile to use. Tip: It's a configured server where the current task will happen
Resource profile
VariableType.RESOURCE_PROFILE
N
TesourceProfile, if any, to be applied during the operation applied to the transport
Return Code variable
VariableType.STRING
Y
Workflow variable where the final return code will be written
Description
It invokes the SpPull service that retrieves a file from the file system and writes it to a virtual path.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Remote path and filename
VariableType.STRING
Y
Remote absolute path (path and filename) to pull the file from. 🚀 See "Remote SpPull custom commands for SFTP transfers" after this table.
Transfer profile
VariableType.TRANSFER_PROFILE
Y
TransferProfile to use. Tip: It's a configured server where the current task will happen.
Resource profile
VariableType.RESOURCE_PROFILE
N
ResourceProfile, if any, to be applied during the operation applied to the transport
Destination
VariableType.VIRTUAL_PATH
Y
Destination virtual path where the file will be placed
Dest Filename
VariableType.STRING
Y
Name of the file to set once pulled
FilesetID created
VariableType.STRING
Y
Name of the variable that will contain the RegistryID (FilesetID) of the created file
Return Code variable
VariableType.STRING
Y
Workflow variable where the final return code will be written
🚀 Remote SpPull custom commands for SFTP transfers
Before a Remote SpPull SFTP transfer, cd and ls custom commands can be run to change the directory where files are pulled or to show the list of files/folders in the directory.
The commands must be entered manually during the workflow design phase. They must be written in a Script task brick and added before the RemoteSpPull brick.
The variable to be used for these custom commands is preClientPull_<sequentialNumber> followed by the cd or ls custom command and the absolute or relative directory. The sequential number indicates the order in which the commands are executed in the workflow and starts at 0. The order of execution is always determined by this sequential number, not by the order in which they are entered in the script.
This is an example of two commands of the Script task brick:
execution.setVariable("preClientPull_0", "cd /home/user1/dataone/in");
execution.setVariable("preClientPull_1", "ls ..");
Once inserted into the workflow, the variable will be applied to the following brick. To change the values of the variables in other RemoteSpPull bricks, additional Script task bricks must be added with the new variables.
If the variable contains the cd command, the new directory overwrites the one specified in the remote path of the client connection's directory. The directory can be absolute or relative.
To check that the cd command has been executed correctly, go to Monitoring → Logs and enter the message code SFP1055. This is an example of the message displayed: Master: SFTP Start Executing command: CdCommand{path='/home/user1/dataone/in'}
If the variable contains the ls command, a list of specific files or directories will be created. An absolute or relative directory can be given as input.
Checking that the ls command is executed correctly is done in 2 ways:
In the Steng's messages.log file.
Going to Monitoring → Logs and using the message code SFP1056. This is an example of the message shown: Master: SFTP End Executing command: LsCommand{path='..'}
Description
It invokes the SpPush service that retrieves a file from a virtual path and writes it to a file system path.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
File ID
VariableType.LONG
Y
ID of the file to be pushed (Tip: if the file is in a "FileDetail" variable, its ID can be retrieved with ${file.getRegistryId()} )
Remote Path
VariableType.STRING
Y
Remote path to place the file into. 🚀 See "Remote SpPush custom commands for SFTP transfers" after this table.
Transfer profile
VariableType.TRANSFER_PROFILE
Y
TransferProfile to use. Tip: It's a configured server where the current task will happen.
Resource profile
VariableType.RESOURCE_PROFILE
N
ResourceProfile, if any, to be applied during the operation applied to the transport
Return Code variable
VariableType.STRING
Y
Workflow variable where the final return code will be written
🚀 Remote SpPush custom commands for SFTP transfers
Before a Remote SpPush SFTP transfer, cd and ls custom commands can be run to change the directory where files are pushed or to show the list of files/folders in the directory.
The commands must be entered manually during the workflow design phase. They must be written in a Script task brick and added before the RemoteSpPush brick.
The variable to be used for these custom commands is preClientPush_<sequentialNumber> followed by the cd or ls custom command and the absolute or relative directory. The sequential number indicates the order in which the commands are executed in the workflow and starts at 0. The order of execution is always determined by this sequential number, not by the order in which they are entered in the script.
This is an example of two commands of the Script task brick:
execution.setVariable("preClientPush_0", "cd /home/user1/dataone/out");
execution.setVariable("preClientPush_1", "ls ..");
Once inserted into the workflow, the variable will be applied to the following brick. To change the values of the variables in other RemoteSpPush bricks, additional Script task bricks must be added with the new variables.
If the variable contains the cd command, the new directory overwrites the one specified in the remote path of the client connection's directory. The directory can be absolute or relative.
To check that the cd command has been executed correctly, go to Monitoring → Logs and enter the message code SFP1055. This is an example of the message displayed: Master: SFTP Start Executing command: CdCommand{path='/home/user1/dataone/out'}
If the variable contains the ls command, a list of specific files or directories will be created. An absolute or relative directory can be given as input.
Checking that the ls command is executed correctly is done in 2 ways:
In the Steng's messages.log file.
Going to Monitoring → Logs and using the message code SFP1056. This is an example of the message shown: Master: SFTP End Executing command: LsCommand{path='..'}
Description
It invokes Remote SpRm service that removes a file identified in the remote path.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Remote path
VariableType.STRING
Y
Remote path to use in the current operation. Tip: It's a remote path, so plain String, not a VirtualPath
Transfer profile
VariableType.TRANSFER_PROFILE
Y
TransferProfile to use. Tip: It's a configured server where the current task will happen.
Resource profile
VariableType.RESOURCE_PROFILE
N
ResourceProfile, if any, to be applied during the operation
Return code
VariableType.STRING
Y
Workflow variable where the final return code will be written
Description
Submit JCL in zOS platform.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Dataset
VariableType.STRING
Y
Directory name
Member
VariableType.STRING
N
File name
JES Reader Class
VariableType.STRING
Y
JES Reader Class
FilesetId
VariableType.LONG
Y
ID of the file to be used in ZOs job (Tip: if the file is in a "FileDetail" variable, its ID can be retrieved with ${file.getRegistryId()} )
Return code
VariableType.STRING
Y
Workflow variable where the final return code will be written
Description
It invokes the SpTar service on an input file and produces a tar output file.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
File
VariableType.STRING
Y
Full pathname (with filename) for the file to be compressed
Output file Path
VariableType.STRING
Y
Full pathname (with filename) for the output file
Return Code variable
VariableType.STRING
Y
Workflow variable where the final return code will be written
Description
Given a FileSetID, the association between it and the provided VirtualBox name will be deleted.
Variables
File ID
VariableType.LONG
Y
Fileset ID to operate the BIND operation to
Virtual Box
VariableType.VIRTUAL_BOX
Y
Virtual Box name where the given FileSet ID will be bound to
Description
It invokes the SpUnTar service on a tar input file and produces an untar output file.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
File
VariableType.STRING
Y
Full pathname (with filename) for the file to be uncompressed
Output file Path
VariableType.STRING
Y
Full pathname (with filename) for the output file
Return Code variable
VariableType.STRING
Y
Workflow variable where the final return code will be written
Description
It invokes the SpUnZip service on a zip input file and produces an unzip output file.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Input File
VariableType.STRING
Y
Full pathname (with filename) for the file to be uncompressed
Output file Path
VariableType.STRING
Y
Full pathname (with filename) for the output file
Compression Mode
VariableType.ENUM
N
Compression mode of Compression64Mode (ALWAYS or NEVER)
Return Code variable
VariableType.STRING
Y
Workflow variable where the final return code will be written
Description
It invokes the SpZip compression service on an input file and produces a zip output file.
Variables
Cluster
VariableType.CLUSTER
Y
Cluster to be used
Input File
VariableType.STRING
Y
Full pathname (with filename) for the file to be compressed
Output file Path
VariableType.STRING
Y
Full pathname (with filename) for the output file
Compression Strategy
VariableType.COMPRESSION _STRATEGY_LEVEL
Y
Strategy level of compression
Compression Level
VariableType.STRING
Y
Level of compression
Compression Mode
VariableType.ENUM
N
Compression mode of Compression64Mode (ALWAYS or NEVER)
Return Code variable
VariableType.STRING
Y
Workflow variable where the final return code will be written