# Triggerable service tasks
STENG peers perform triggerable tasks that are often related to long-lasting operations, like file transfers.
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**:
* [Bind VirtualBox](#bind-virtualbox)
* [Data Shaper Processor](#data-shaper-2.0-processor)
* [Event Notification](#event-notification)
* [GUnzip File](#gunzip-file)
* [GZip File](#gzip-file)
* [ICAP](#icap)
* [List files VirtualBox](#list-files-virtualbox)
* [Local Execute Shell Command](#local-execute-shell-command)
* [Local FileSystem SpLs](#local-filesystem-spls)
* [Local SpConv](#local-spconv)
* [Local SpGet](#local-spget)
* [Local SpPut](#local-spput)
* [Local VirtualPath SpLs](#local-virtualpath-spls)
* [Mail pull](#mail-pull)
* [Mail push](#mail-push)
* [Mail push templated](#mail-push-templated)
* [PGP Crypt File](#pgp-crypt-file)
* [PGP Decrypt File](#pgp-decrypt-file)
* [Remote SpJMSPush](#remote-spjmspush)
* [Remote SpLs](#remote-spls)
* [Remote SpMkdir](#remote-spmkdir)
* [Remote SpMv](#remote-spmv)
* [Remote SpPull](#remote-sppull)
* [Remote SpPush](#remote-sppush)
* [Remote SpRm](#remote-sprm)
* [Spjz Sub](#spjz-sub)
* [Tar File](#tar-file)
* [UnBind VirtualBox](#unbind-virtualbox)
* [UnTar File](#untar-file)
* [UnZip File](#unzip-file)
* [Zip File](#zip-file)
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.
## Bind VirtualBox
**Description:** When a FileSet ID is provided, it will be associated with the designated VirtualBox name.
**Variables**
| Parameter | Type | Required | Description |
| ----------- | ---------- | -------- | ------------------------------------------------------------ |
| File ID | Long | Y | Fileset ID to operate the BIND operation to |
| Virtual Box | VirtualBox | Y | Virtual Box name where the given FileSet ID will be bound to |
## Data Shaper 2.0 Processor
**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 workflows.
Variables are documented in the Data Shaper documentation. See the [Defining a Data Shaper workflow template](/data-shaper-1.21/using-data-shaper-in-data-mover/defining-a-data-shaper-workflow-template.md) page.
## Event Notification
**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**
| Parameter | Type | Required | Description |
| ----------------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| notificationChannelName | NotificationChannel | Y | Name of the Notification channel that will receive the event. |
| actName | String | Y | Logical name of the operation, used by DataWatcher when rendering a given **actCode**. |
| actAttrsPrefix | 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 | Enum | Y | Allowed values:
- running
- success (default)
- failure
|
| actErrCode | String | N | Attribute applied only when **actOutcome** is set to failure and indicates the error code associated with the failure. |
| actErrMsg | String | N | Attribute applied only when **actOutcome** is set to failure and indicates the error code associated with the failure. |
| dcName | String | Y | Logical name of the data container, typically a filename. |
## GUnzip File
**Description:** This service task unzips the GZIP archive specified in the `Input File` parameter and extracts its contentsinto a new file at the location defined by the `Output file Path` parameter.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used |
| Input File | String | Y | Full pathname (with filename) for the file to be uncompressed.
It is suggested to define a variable and specify the path value in the contract. If you want to enter the full path, use the following format: <path>/filename |
| Output file Path | String | Y | Full pathname (with filename) for the output file.
It is suggested to define a variable and specify the path value in the contract. If you want to enter the full path, use the following format: <path>/filename |
| Return Code | String | Y | The workflow variable where the final return code will be written. Default: rc. |
## GZip File
**Description:** This service task compresses the input file specified in the `Input File` parameter and generates a gzip archive at the location defined in the `Output file Path` parameter, applying the selected `Compression Level` and `Compression Strategy`*.*
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used |
| Compression level | CompressionLevel | Y | Level of compression, default: 5.
Values allowed: 0-9
0 for no compression and 9 for maximum compression. |
| Compression strategy | CompressionStrategyLevel | Y | Level of the compression strategy. The strategy parameter is used to tune the compression algorithm.
Values allowed:
DEFAULT (default)
FILTERED
HUFFMAN_ONLY |
| Input File | String | Y | Full pathname (path, name and extension) of the file to be compressed: <path>/filename It is suggested to define a variable and specify the path value in the contract. |
| Output file Path | String | Y | Full pathname (path, name and extension) of the output file: <path>/filename No extension will be automatically added to the output filename.
It is suggested to define a variable and specify the path value in the contract. |
| Return Code | String | Y | The workflow variable where the final return code will be written. Default: rc. |
## ICAP
**Description:** It performs an antivirus/DLP check on a file in the filebox using a specific ICAP engine and returns the outcome of the check.
**Triggerable:** Yes
**Input Variables:**
| Parameter | Type | Required | Description |
| -------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cluster | Cluster | Y | Cluster to be used |
| Exception If Harmful | Boolean | Y | 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 | Boolean | Y | 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. |
| File ID | Long | Y | Variable that contains the FilesetID of the file that will be scanned.
If the file is in a FileDetail variable, its ID can be retrieved with ${file.getRegistryId()}
|
| Icap | Icap | Y | ID of the ICAP engine that will perform the scan. |
| Icap method | Enum | N | ICAP method (REQMODE or RESPMODE). |
| Scan mode | Enum | N | Scan mode (ANTIVIRUS or DLP). |
| Return code | String | N | Result of scan. Default: rc
For a detailed list of all the possible results, see the table below.
|
**Output codes**
| Return code | Description | Notes |
|---|
| "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 |
## List files VirtualBox
**Description:** When you provide a VirtualBox name, all related files will be listed as ExternalFile objects in the File List variable.
**Variables**
| Parameter | Type | Required | Description |
| ----------- | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Virtual Box | VirtualBox | Y | Virtual Box name where the given FileSet ID will be bound to |
| File List | 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) |
## Local Execute Shell Command
**Description:** This service task executes the shell commands configured in the Executable parameter of the service task.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used. |
| Executable | String | Y | Command to be executed in the service task. For example, this parameter can contain the full path of a script that will be executed when the service task is executed:
home/doc/executeShellScript.shThe STENG must have permissions to execute the script. |
| Arguments | String | N | List of arguments to be passed to the command execution. Arguments must be separated by blanks.
Blanks and special characters are managed as per the standard Unix protection methods and must be enclosed in single or double quotes.
For example, given a script expecting 3 parameters, the Arguments field will contain:
Jane Smith "Oxford street 125 London UK" |
| Std Out | String | Y | Name of the variable that will be filled with the standard output logging. |
| Std Err | String | Y | Name of the variable that will be filled with the standard error logging. |
| Return code | String | Y | Workflow variable where the final return code will be written. |
| Return code management | 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). |
## Local FileSystem SpLs
**Description:** This service task retrieves a list of files from a directory in the local file system that the user has access to.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
| -------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cluster | Cluster | Y | Cluster to be used. |
| Username | String | N | Username used by this command. |
| Password | String | N | Password for the username used by this command. |
| Path | String | Y | Local path where file listing will be performed. |
| List | String | Y | Variable with the list of files as a result of the current operation.
Tip: You can cycle through the items in this list using the Subprocess object.
|
| Return Code variable | String | Y | Workflow variable where the final return code will be written. |
## Local SpConv
**Description:** This service task converts an input file by modifying its character encoding and/or line-ending format, then saves the result as a new file.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used |
| Input File | String | Y | Full path to the input file. Example: home/<filename> |
| Output file Path | String | Y | Full path to the output file generated by the conversion. Example: home/<filename> |
| Input Code Page | Code_page | Y | Charset of the input file. See the Default charset page for the entire list of supported charsets.
The codepage can be used as well. |
| Output Code Page | Code_page | Y | Charset of the output file. See the Default charset page for the entire list of supported charsets.
The codepage can be used as well. |
| Input EOL | Eol | N | EOL of the input file. |
| Output EOL | Eol | N | EOL of the output file. |
| Return code | String | Y | Workflow variable where the final return code will be written. |
## Local SpGet
**Description:** This service task retrieves a file from a Virtual Path and saves it to a file system directory (destination path).
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
| ---------------- | ----------------- | -------- | ---------------------------------------------------------------------------------------- |
| Cluster | Cluster | Y | Cluster to be used |
| File Name | String | N | Filename that will be used for the final file |
| Destination Path | String | Y | Destination path where the fill will be placed |
| File | String | Y | Name of the file that will be retrieved in the virtual path set in the Source parameter. |
| Resource profile | Resource\_profile | N | ResourceProfile, if any, to be applied during the operation |
| Return Code | String | Y | Workflow variable where final return code will be written |
| Source | Virtual\_path | Y | Virtual path where the file will be retrieved. |
## Local SpPut
**Description:** This service task retrieves a file from a local folder and saves it on a destination Virtual Path with a filename specified in the `destination filename` parameter. The new file in Data Mover will have as filesetId the content of the `FilesetID created` variable.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used. |
| Destination | Virtual_path | Y | Destination virtual path where the file will be placed. |
| Destination Filename | String | Y | Filename of the file on the destination virtual path. |
| Resource profile | Resource_profile | N | ResourceProfile, if any, to be applied to the file before it is put in the destination virtual path. |
| Return code | String | N | The workflow variable where the final return code will be written. Default: rc. |
| FilesetID created | String | Y | Variable that contains the FilesetID of the file put on the destination virtual path.
Default: registryID. |
| Source (path and filename) | String | Y | Source path and filename of the file to retrieve. |
## Local VirtualPath SpLs
**Description:** This service task retrieves the list of contents from the Virtual Path specified in the `Virtual Path` parameter. The resulting list is stored in the variable defined in the `File List` parameter.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used. |
| File List | String | Y | Specify the variable that contains the list of files found in the virtual path configured in the Virtual Path parameter below.
The default value is filelist, but you can change it as needed.
Tip: You can cycle through the items in this list using the Subprocess object. |
| Return code | String | Y | Workflow variable where the final return code will be written. |
| Virtual Path | Virtual_path | Y | Specify the Virtual Path whose contents you want to retrieve.
It is suggested to define a variable and specify the Virtual Path value in the contract.
If you want to enter the full Virtual Path, use the following format:
<vfs-name>:/<virtual-path> |
## Mail pull
**Description:** this service task retrieves an email from a remote mail server set in the `Transfer profile` parameter and checks the presence of **one attachment** and the validity of the email’s digital signature.\
Based on the outcome of these checks, the service task routes the email content to one of three configured Virtual File Systems (VFS):
* **Verified VFS** – used when the email contains an attachment and the signature is successfully verified.
* **Unverified VFS** – used when the email includes an attachment but the digital signature cannot be validated.
* **Discarded VFS** – used when the email has no attachment or has two or more attachments.
In all three cases:
* the raw email body is stored in the appropriate VFS under the virtual path specified in the `Raw` parameter. The filename of the stored email body is the email Subject.
* the attachment is saved as a file within the virtual path defined in the `Attachment Virtual Path` parameter. The filename of the stored attachment is configured using the `Rendering filename` parameter.
Both the `Attachment Virtual Path` and `Raw` parameters are used to build the final virtual paths within each of the three VFS destinations.
All fields are **case‑sensitive** and must match exactly what is defined on the remote mail server. If variables are defined, when specifying their value in the Contract, make sure the field is correct.
The file containing the email raw message and the file containing the attachment are enriched with the following metadata:
* Destination mail address
* Sender mail address
* Mail subject
* Mail Text Overflow
* Mail Sent Date
* Mail Receive Date
* Mail Sign State
* Mail Sign State Msg
* Mail Sign Date
* Mail Sign Dn
* Mail Sign Cert
* Mail Raw Size (this metadata is only on the file containing the attachment)
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Attachment Virtual Path | String | Y | Virtual path where the email attachment is stored. This path is combined with the selected VFS (Verified, Unverified, or Discarded) to determine the final storage location. The attachment is saved as a file using the name defined in the Rendering filename parameter.
It is suggested to define a variable and specify the path value in the contract.
If you want to enter only the virtual path, use the following format: <virtual_path> |
| Cluster | Cluster | Y | Cluster to be used |
| Rendering Filename | String | N | Filename used when storing the email attachment in the VFS. Enter one of the following values (or leave the field blank to use the default NAME option): - (default) NAME: the original filename of the email attachment is used.
- SUBJECT: the email’s Subject is used as the filename.
- FROM: the sender’s email is used as the filename.
- DATE: the email’s date is used as the filename.
|
| VFS discarded | String | Y | Virtual file system where emails without attachments or with more than one attachment are stored. Raw email bodies are saved here under the path defined in Raw.
It is suggested to define a variable and specify the VFS name in the contract.
If you want to enter the VFS name, use this format: <VFS_name> |
| Raw | String | Y | Virtual path where the the raw email body is stored. Regardless of the processing outcome (Verified, Unverified, or Discarded), the full email content in its original raw format is saved in the virtual path defined by this parameter.
This path is combined with the selected VFS to determine the final storage location.
The email body filename is the email's Subject.
It is suggested to define a variable and specify the path value in the contract.
If you want to enter only the virtual path, use the following format: <virtual_path> |
| Remote path | String | Y | Name of the monitored mailbox folder.
Different mail providers may use different names such as inbox or spam. The mailbox folder name must match exactly the value of the mailbox "country" field and must be written exactly as they appear on the mail server. E.g.,
- Inbox
- INBOX
- Posta in arrivo
It is suggested to define a variable and specify the folder in the contract.
If you want to enter only the mailbox folder, use the following format:
<mailbox_folder> |
| Return Code | String | N | The workflow variable where the final return code will be written. Default: rc. |
| Transfer profile | Transfer_profile | Y | Client Connection to be used to connect to the server email to collect the email with the attachment.
It is suggested to define a variable and specify the Client Connection name in the contract. |
| VFS unverified | String | Y | Virtual file system used to store emails with an attachment and whose digital signature cannot be verified. Raw email bodies are saved here under the path defined in Raw. The attachment is saved under the path defined in Attachment Virtual Path.
It is suggested to define a variable and specify the VFS name in the contract.
If you want to enter the VFS name, use this format: <VFS_name> |
| VFS verified | String | Y | Virtual File System used to store emails with an attachment and whose digital signature has been successfully verified. When an email passes both checks, the email body is stored under the Raw virtual path and the attachment under the Attachment Virtual Path.
It is suggested to define a variable and specify the VFS name in the contract.
If you want to enter the VFS name, use this format: <VFS_name> |
## Mail push
**Description**: This service task sends one email to a remote mail server set in the `Transfer profile` parameter. The body of the email is set in the `Body` parameter. An attachment can be defined in the `FileSet Id` parameter. The email might be signed or not, depending on the value of the `Mail sign` parameter.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Body | String | Y | Body of the email |
| Cluster | Cluster | Y | Cluster to be used |
| FileSet Id | Long | N | The FilesetID of the file that will be attached to the email. Only one file can be attached to each email. |
| From | String | Y | Email sender |
| Return Code | String | Y | The workflow variable where the final return code will be written. Default: rc. |
| Alias Sign | String | Y | Key ID of the private key used to sign the email.
Email sign alias key (mandatory if 'Sign Mail' is required) |
| Mail Sign | String | N | Whether the email sign is required or not. |
| Subject | String | Y | Email subject |
| To | String | Y | Email recipient |
| Transfer profile | Transfer_profile | Y | Client Connection to be used to send the email to the configured email address.
It is suggested to define a variable and specify the Client Connection name in the contract: ${profile} |
## Mail push templated
**Description:** This service task sends one email with attachment to a remote mail server set in the `Transfer profile` parameter. The body of the email does not need to be defined since the email template defined in the `Template ID` parameter is used.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
| ---------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cluster | Cluster | Y | Cluster to be used |
| FileSet Id | Long | N | The FilesetID of the file that will be attached to the email. Only one file can be attached to each email. |
| From | String | N | Email sender |
| Return Code | String | N | The workflow variable where the final return code will be written. Default: `rc`. |
| Subject | String | Y | Email subject |
| Default replacer | String | N | If the mail template contains variables that are not populated, Data Mover will use the value specified in this field.
Example: NoInfo
|
| Template ID | String | Y | Identifier of the HTML template to be used for the body. Templates are configured in Setup → [Email Templates](/data-mover-1.21/notification-channels/manage-templates/email-templates.md). |
| To | String | Y | Email recipient |
| Transfer profile | TransferProfile | Y | Client Connection to be used to send the email to the configured email address.
It is suggested to define a variable and specify the Client Connection name in the contract.
${profile}
|
## PGP Crypt File
**Description:** It invokes the PGP Crypt service on an input file that produces an encrypted file.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used |
| Input file | String | Y | Full pathname (with filename) of the file to be encrypted.
It is suggested to define a variable and specify the path value in the contract. If you want to enter the full path, use the following format: <path>/filename |
| Alias key | String | Y | Alias key (Key ID) to use for encryption. |
| Output file | String | Y | Full pathname (with filename) of the output file.
It is suggested to define a variable and specify the path value in the contract. If you want to enter the full path, use the following format: <path>/filename |
| PGP format | String | Y | PGP format: binary or ascii-armor |
| Recipient | String | Y | Recipient of the file |
| Return Code | String | Y | The workflow variable where the final return code will be written. Default: rc. |
| Cipher algorithm | CipherAlgorithmSecurity | Y | Cipher security algorithm. Values allowed:
- DES
- DES_EDE3
- AES128
- AES192
- AES256
- RC2 |
| Operation security | OperationSecurity | Y | Security operations. Allowed values:
- NONE (no security applied)
- ENVELOPE (envelope‑based security applied)
- OPEN (Security enabled based on open standards)
- SIGN_AND_ENVELOPE (both signing and envelope‑based security applied)
- SIGN (digital signature only applied) |
| Hash algorithm | HashAlgorithmSecuritySignature
| Y | Hash algorithm of the security signature. Values allowed:
- MD2
- MD5
- SHA1
- SHA256
- SHA384
- SHA512 |
## PGP Decrypt File
**Description:** It invokes PGP Decrypt service on an input encrypted file and it produces a decrypted file.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used |
| Input File | String | Y | Full pathname (with filename) of the file to be decrypted.
It is suggested to define a variable and specify the path value in the contract. If you want to enter the full path, use the following format: <path>/filename |
| Output file Path | String | Y | Full pathname (with filename) of the output file.
It is suggested to define a variable and specify the path value in the contract. If you want to enter the full path, use the following format: <path>/filename |
| PGP format | String | Y | PGP format in binary or ascii-armor |
| Return Code | String | Y | The workflow variable where the final return code will be written. Default: rc. |
## Remote SpJMSPush
**Description**
This service task splits file into one or more messages, maps file metadata into JMS message attributes and sends JMS messages. These 2 triggers are associated with this service task:
* [system\_newfile\_JMS-push](https://docs.primeur.com/data-mover-1.21/workflow-templates/service-tasks/pages/JanyWTlsU58FTA4llglA#id-4.-push-new-file-as-jms-message) – New File – triggered
* [system\_vBind\_JMS-push](https://docs.primeur.com/data-mover-1.21/workflow-templates/service-tasks/pages/JanyWTlsU58FTA4llglA#id-3.-push-vbox-bind-file-as-jms-message) – Virtual Box Bind - triggered
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used. |
| JMS delivery modes | String | N | Method of delivery of JMS messages. Options are: - Persistent (the message is saved and its delivery is ensured). - Non_persistent (the message must not be saved and could be lost, for example in case of problems on the server). |
| File ID | 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 JMS destination | String | Y | Name of the JMS destination |
| Remote JMS destination type | JMS_type | Y | Type of JMS destination. Options are: queue or topic |
| Splitting Message Processing Rule | Message_processing_rule | N | Splitting Message Processing Rule to be applied. It is configured in Setup → Message processing rule. |
| JMS Message priority levels | Integer | N | Priority assigned to the messages that are created when splitting the file. It must be an integer between 0 and 9. Default is 4. |
| Propagates Data One Metadata | Boolean | N | This variable propagates system metadata to JMS Properties. See the Metadata mapping for split file content page for details. |
| Resource profile | Resource_profile | N | File resource, if any, to be applied during the operation. |
| Return code | String | N | The workflow variable where the final return code will be written. Default: rc. |
| JMS Message time to live | Long | N | This variable sets how many seconds messages will live. A number higher than 0 is accepted. |
| Transfer profile | JMS_transfer_profile | Y | Client Connection that must be used to push the file to the remote path. See Client Connection: JMS for details. |
## Remote SpLs
**Description:** This service task retrieves the list of contents from path specified in the `Remote Path` parameter. The resulting list is stored in the variable defined in the `List` parameter.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used |
| Remote path | String | Y | Specify the remote path of the contents you want to retrieve.
It is suggested to define a variable and specify the path value in the contract.
If you want to enter the full remote path, use the following format:
<remote-path> |
| Transfer profile | Transfer_profile | Y | Client Connection to be used to connect to the remote location.
It is suggested to define a variable and specify the Client Connection name in the contract. |
| Resource profile | Resource_profile | N | File resource, if any, to be applied during the operation. |
| List | String | Y | Variable that will contain the list of files as a result of the current operation.
You can cycle through the items in this list using the Subprocess object. |
| Return code | String | Y | The workflow variable where the final return code will be written. Default: rc. |
## Remote SpMkdir
**Description:** This service task creates a new folder with the path configured in the `Remote path` parameter on the remote server identified by the `Transfer profile`. parameter.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used |
| Remote path | String | Y | Remote path of the folder to create |
| Return code | String | Y | The workflow variable where the final return code will be written. Default: rc. |
| Transfer profile | Transfer_profile | Y | Client Connection to be used to create the folder on the remote path.
It is suggested to define a variable and specify the Client Connection name in the contract. |
## Remote SpMv
**Description:** This service task removes files from the remote path specified in the `Remote path` parameter.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used |
| Remote path | String | Y | Specify the remote path of the contents you want to remove.
It is suggested to define a variable and specify the path value in the contract.
If you want to enter the full remote path, use the following format:
<remote-path> |
| Resource profile | Resource_profile | N | File resource, if any, to be applied during the operation. |
| Return code | String | Y | The workflow variable where the final return code will be written. Default: rc. |
| Transfer profile | Transfer_profile | Y | Client Connection to be used to connect to the remote location.
It is suggested to define a variable and specify the Client Connection name in the contract. |
## Remote SpPull
**Description:** This service task pulls the file specified in the `Remote path and Filename` parameters from the remote server configured in the `Transfer profile` parameter.
The pulled file will be placed in the virtual path configured in the `Destination` parameter, using the name specified in the `Dest Filename` parameter.
The *filesetID* of the file is returned in the variable configured in the `FilesetID` parameter.
An optional **file resource** can be set in the `Resource profile` parameter. When configured, the file resource defines one or more processing steps to be applied to the pulled file **before** placing it into the destination virtual path.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used |
| Destination | Virtual_path | Y | Destination virtual path where the file will be placed. |
| Dest Filename | String | Y | Name of the file to set once pulled. |
| Remote path and filename | String | Y | Absolute remote source path (path and filename) where the file is collected.
For SFTP transfers, see "Remote SpPull custom commands for SFTP transfers" below.
It is suggested to define a variable and specify the path value in the contract. If you want to enter the full remote path, use the following format: /<remote-path/filename> |
| Resource profile | Resource_profile | N | File resource, if any, to be applied during the operation. |
| Return Code variable | String | Y | The workflow variable where the final return code will be written. Default: rc. |
| FilesetID created | String | Y | Name of the variable that will contain the RegistryID (FilesetID) of the created file. |
| Transfer profile | Transfer_profile | Y | Client Connection to be used to retrieve the file and write it to a virtual path.
It is suggested to define a variable and specify the Client Connection name in the Contract. |
**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** service task and added before the **RemoteSpPull** service task.
The variable to be used for these custom commands is `preClientPull_` 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** service task:
`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 service task. To change the values of the variables in other **RemoteSpPull** service tasks, additional **Script task** service tasks 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:
1. In the Steng's `messages.log` file.
2. 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='..'}
## Remote SpPush
**Description:** This service task transfers a file to a remote server. The file to be transferred is identified by the fileset ID configured in the `File ID` parameter. The remote server where the file will be sent is configured in the `Transfer profile` parameter. The file is uploaded to the remote server under the `Remote path` specified.
An optional file resource can be set in the `resource profile`. When configured, the file resource defines one or more processing steps to be applied to the file **prior to transfer**.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used |
| File ID | 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 | String | Y | Destination remote path where the file will be placed.
For SFTP transfers, see "Remote SpPush custom commands for SFTP transfers" below. |
| Resource profile | Resource_profile | N | File resource, if any, to be applied during the operation. |
| Return code | String | Y | The workflow variable where the final return code will be written. Default: rc. |
| Transfer profile | Transfer_profile | Y | Client Connection to be used to retrieve the file from the virtual path and write it to the file system path.
It is suggested to define a variable and specify the Client Connection name in the contract. |
**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** service task and added before the **RemoteSpPush** service task.
The variable to be used for these custom commands is `preClientPush_` 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** service task:
`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 service task. To change the values of the variables in other **RemoteSpPush** service tasks, additional **Script task** service tasks 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:
1. In the Steng's `messages.log` file.
2. 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='..'}
## Remote SpRm
**Description:** This service task removes files from the remote path specified in the `Remote path` parameter.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used |
| Remote path | String | Y | Specify the remote path of the contents you want to remove.
It is suggested to define a variable and specify the path value in the contract.
If you want to enter the full remote path, use the following format:
<remote-path> |
| Resource profile | Resource_profile | N | File resource, if any, to be applied during the operation. |
| Return code | String | Y | The workflow variable where the final return code will be written. Default: rc. |
| Transfer profile | Transfer_profile | Y | Client Connection to be used to connect to the remote location.
It is suggested to define a variable and specify the Client Connection name in the contract. |
## Spjz Sub
**Description:** This service task submits a JCL to the zOS platform.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
| ---------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cluster | Cluster | Y | Cluster to be used |
| Dataset | String | Y | Directory name |
| FilesetId | Long | Y | ID of the file to be used in the zOS job (Tip: if the file is in a "FileDetail" variable, its ID can be retrieved with `${file.getRegistryId()} )` |
| JES Reader Class | String | Y | JES Reader Class |
| Member | String | N | File name |
| Return code | String | Y | The workflow variable where the final return code will be written. Default: `rc`. |
## Tar File
**Description:** It invokes the SpTar service on an input file and produces a tar output file.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used |
| Input File | String | Y | Full pathname (path, name and extension) of the file to be compressed: <path>/filename It is suggested to define a variable and specify the path value in the contract. |
| Output file Path | String | Y | Full pathname (path, name and extension) of the output file: <path>/filename No extension will be automatically added to the output filename.
It is suggested to define a variable and specify the path value in the contract. |
| Return Code | String | Y | The workflow variable where the final return code will be written. Default: rc. |
## UnBind VirtualBox
**Description:** Given a FileSetID, the association between it and the provided VirtualBox name will be deleted.
**Variables**
| Parameter | Type | Required | Description |
| ----------- | ------------------------- | -------- | ------------------------------------------------------------ |
| 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 |
## UnTar File
**Description:** This service task invokes the **SpUnTar** service on an input TAR file and generates an extracted output file. If the input `.tar` file contains multiple files, the output file will include only the first file in the archive.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used |
| Input File | String | Y | Full pathname (path, name and extension) of the file to be uncompressed: <path>/filename It is suggested to define a variable and specify the path value in the contract. |
| Output file Path | String | Y | Full pathname (path, name and extension) of the output file: <path>/filename
It is suggested to define a variable and specify the path value in the contract. |
| Return Code | String | Y | The workflow variable where the final return code will be written. Default: rc. |
## UnZip File
**Description:** It invokes the SpUnZip service on a zip input file and produces an unzip output file.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used |
| Input File | String | Y | Full pathname (with filename) of the file to be uncompressed.
It is suggested to define a variable and specify the path value in the contract. If you want to enter the full path, use the following format: <path>/filename |
| Output file Path | String | Y | Full pathname (with filename) of the output file.
It is suggested to define a variable and specify the path value in the contract. If you want to enter the full path, use the following format: <path>/filename |
| Compression Mode | Enum | N | Compression mode of Compression64Mode. Values allowed:
ALWAYS - Compression is always applied.
NEVER - Compression is never applied. |
| Return Code | String | Y | The workflow variable where the final return code will be written. Default: rc. |
## Zip File
**Description:** It invokes the SpZip compression service on an input file and produces a zip output file.
**Triggerable:** Yes
**Variables:**
| Parameter | Type | Required | Description |
|---|
| Cluster | Cluster | Y | Cluster to be used. |
| Input File | String | Y | Full pathname (with filename) of the file to be compressed.
It is suggested to define a variable and specify the path value in the contract. If you want to enter the full path, use the following format: <path>/filename |
| Output file Path | String | Y | Full pathname (with filename) of the output file.
No extension will be automatically added to the output filename.
It is suggested to define a variable and specify the path value in the contract. If you want to enter the full path, use the following format: <path>/filename |
| Compression Strategy | Compression_strategy_level | Y | Level of the compression strategy. The strategy parameter is used to tune the compression algorithm.
Values allowed:
DEFAULT (default)
FILTERED
HUFFMAN_ONLY |
| Compression Level | String | Y | Level of compression, default: 5.
Values allowed: 0-9
0 for no compression and 9 for maximum compression. |
| Compression Mode | Enum | N | Compression mode of Compression64Mode. Values allowed:
ALWAYS - Compression is always applied.
NEVER - Compression is never applied. |
| Return Code | String | Y | The workflow variable where the final return code will be written. Default: rc. |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.primeur.com/data-mover-1.21/workflow-templates/service-tasks/triggerable-service-tasks.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.