Remote Operations service tasks

• REST Invoker

• Remote SpLs

• Remote SpRm

• Mail Pull

• Mail Push

• Mail Push Templated

• 🚀 Remote SpPull

• 🚀 RemoteSpPush

• 🚀 Remote SpJMSPush

• Remote SpMkdir

• Remote SpMv

• SOAP

• BDI SOAP Service

• Spjz Sub

REST Invoker - DAT-12211

Description: HTTP TASK - REST Invoker.

Triggerable: No

Variables:

Parameter	Type	Required	Description
Throw exception	Boolean	N	When selected, an exception will be thrown if a failure occurs. You can handle this exception by catching it with a boundary error event or letting it escalate to terminate the process.
Disallow redirects	Boolean	N	Determines whether HTTP redirects are allowed or not. By default, redirects are allowed.
Handle status codes	String	N	List of status codes for which the task throws a BpmnError which can be caught by a boundary error event. Code ranges can be set with an X: Example: 400, 404, 5XX. Status codes in handleStatusCodes override those in failStatusCodes when they are set in both.
Request body	String	N	Request body to be sent, for example a JSON file. You can use EL expressions, e.g. {'clientId': ${clientId}, 'name': ${name}}
Request body encoding	String	N	Http Request body encoding expression, for example UTF-8
Request headers	String	N	HTTP request headers. Each request header must be on a new line. For example: Content-Type: application/json Accept: application/json
Request method	Long	Y	Request method to be used in the HTTP call: GET, POST, PUT or DELETE.
Request timeout	Integer	N	Request timeout in milliseconds.
Request URL	String	Y	Request URL of the HTTP call. It can contain EL expressions, e.g. 'http://your-system.example.com/your-endpoint/${someVariable}'
Response variable name	String	Y	The variable name where the HTTP response is stored.
Result variable prefix	String	N	A prefix that is added to the result variable name for easier grouping. The following variables are affected: responseProtocol, responseReason, responseStatusCode, responseHeaders, responseBody, errorMessage.
Save request variables	Boolean	N	Determines whether all request variables are stored. By default, only response related variables are stored as variables. Da chiedere al LAB dove li salva.
Save response parameters	Boolean	N	Determines whether response variables including HTTP status, headers, etc. are stored. By default, only the response body is stored as a variable. Da chiedere al LAB dove li salva.
Save response variable as Json	Boolean	N	Determines whether the response variable is stored as a JSON variable instead of a String. Da chiedere al LAB dove li salva.

Remote SpLs - TBD

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. LINK all'esempio di subprocess
Return code	String	Y	The workflow variable where the final return code will be written. Default: rc.

Remote SpRm - DAT-12212

Description: This service task removes files from the remote path specified in the Remote path parameter.

Da verificare se rimuove tutto il contenuto della cartella o è possibile specificare cosa rimuovere.

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.

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 - DAT-12209

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) - LAB (pr)
Mail Sign	String	N	Whether the email sign is required or not. Boolean? Cosa mettiamo? - LAB (pr)
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	Se il template mail ha delle variabili non valorizzate, Data Mover utilizzerà il valore specificato in questo campo. Es. NoInfo Accetta più valori? Come? Optional default replacer to be used in every missing variable of the email template
Template ID	String	Y	Identifier of the HTML template to be used for the body ID dell'email template. Ved. Setup > email templates
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}

🚀 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_<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 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 - ok

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()} ) LINK A PAGINA VARIABILI
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_<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 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 SpJMSPush

Description: This service task splits file into one or more messages, maps file metadata into JMS message attributes and sends JMS messages. This service task is associated with:

• system_newfile_JMS-push – New File – triggered

• system_vBind_JMS-push – 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 SpMkdir - ok

Description: This service task creates a new folder con path configurato nel parametro Remote path sul server remoto identificato dalla 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 - DAT-12213

Description: This service task moves a file from a source location defined in the Source parameter to a destination location defined in the Path parameter. Both locations are on the remote server configured in the Transfer profile parameter.

Triggerable: Yes

Variables:

Parameter	Type	Required	Description
Cluster	Cluster	Y	Cluster to be used
Path	String	Y	Destination path (and filename?) where the file will be moved.
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.
Source	String	Y	Source path and filename of the file that will be moved.
Transfer profile	Transfer_profile	Y	Client Connection to be used to move the file. It is suggested to define a variable and specify the Client Connection name in the contract.

SOAP - ok

Description: It invokes the SOAP Service configured in the URL parameter.

Triggerable: No

Variables:

Parameter	Type	Required	Description
Connection Timeout	Integer	Y	Maximum time, in milliseconds, to wait when opening a communication link to the SOAP service
Envelope	String	Y	The full envelope of the SOAP service request. See below.
Response	String	Y	The workflow variable where the SOAP response will be written. Default: soapResponse
Response Code	String	Y	The HTTP response code of the SOAP service invocation will be saved in the declared variable The workflow variable where the HTTP response code of the SOAP service invocation will be written. Default: rc
URL	String	Y	The url of the soap service to be called. Per configurare la URL come variabile, inserire: ${WSDL_url}

Use the SOAP official format: Envelope → Header → Body.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope>
    <soap:Header>
        ...
    </soap:Header>
    <soap:Body>
        ...
    </soap:Body>
</soap: Envelope>

Spjz Sub - ok

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()} ) LINK A NUOVA PAGINA
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.