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 - TBD

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 - TBD

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 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.

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>

RESTA DA VERIFICARE:

1. Se l'email non ha attachment o non viene verificata la firma, il STask termina con errore?

2. Metadati: Il file con il messaggio salvato e gli attachments vengono arricchiti con tutto o parte di questi metadati: https://forge.primeur.com/jira/browse/DAT-11148

• 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 push

Description: It invokes the SpMailPush command service that sends an email to a Virtual file system.

Triggerable: Yes

Variables:

Parameter	Type	Required	Description
Cluster	Cluster	Y	Cluster to be used
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.
To	String	Y	Email recipient
From	String	Y	Email sender
Subject	String	Y	Email subject
Body	String	Y	Body of the email
Raw	String	Y	Virtual path folder name where the raw mail is stored
FileSet Id	Long	N	Referenced FilesSet ID for this email
Mail Sign	String	N	Whether the email sign is required or not
Alias Sign	String	Y	Email sign alias key (mandatory if 'Sign Mail' is required)
Return Code	String	N	The workflow variable where the final return code will be written. Default: rc.

Mail push templated

Description: It invokes SpMailPush templated command service.

Triggerable: Yes

Variables:

Parameter	Type	Required	Description
Cluster	Cluster	Y	Cluster to be used
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.
To	String	Y	Email recipient
From	String	Y	Email sender
Subject	String	Y	Email subject
TemplateId	String	Y	Identifier to the HTML template to be used for the body
Return Code variable	String	N	The workflow variable where the final return code will be written. Default: rc.

🚀 Remote SpPull

Description: This service task pulls the file specified in the Remote path and filename parameter from the remote server configured in the Transfer profile parameter.

Il pulled file verrà messo nel vpath cfg nel par Destination con nome configurato nel Dest Filename. Il filesetID del file è ritornato nella variabile configurata nel parametro FilesetID .

Opzionale: file resource per cfg operazioni sul pulled file prima di metterlo nel 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

Description: It invokes the SpPush service that retrieves a file from a virtual path and writes it to a file system path.

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 to place the file into. 🚀 For SFTP transfers, see "Remote SpPush custom commands for SFTP transfers" below.
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.
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.

🚀 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. These 2 triggers are associated with this service task:

• 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

Description: It invokes the SpMkdir service that creates a new folder on a remote path.

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
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.
Return Code variable	String	Y	The workflow variable where the final return code will be written. Default: rc.

Remote SpMv

Description: It invokes the SpMv service that moves a file from a source location to a destination.

Triggerable: Yes

Variables:

Parameter	Type	Required	Description
Cluster	Cluster	Y	Cluster to be used
Source	String	Y	Source path to be moved
Path	String	Y	Destination path after the move command has been performed
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.
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.

SOAP

Description: It invokes the SOAP Service.

Triggerable: No

Variables:

Parameter	Type	Required	Description
URL	String	Y	The url of the soap service
Envelope	String	Y	The envelope for the SOA service
Response	String	Y	The response of the SOA service
Connection Timeout	Integer	Y	Maximum time, in milliseconds, to wait when opening a communication link to the resource
Response Code	String	Y	The HTTP response code of the SOAP service invocation will be saved in the declared variable

Spjz Sub

Description: Submit JCL in zOS platform.

Triggerable: Yes

Variables:

Parameter	Type	Required	Description
Cluster	Cluster	Y	Cluster to be used
Dataset	String	Y	Directory name
Member	String	N	File name
JES Reader Class	String	Y	JES Reader Class
FilesetId	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	String	Y	The workflow variable where the final return code will be written. Default: rc.