How to Add a Call Task Task Step

Prerequisites

In order to add a Call Task The Call Task tool is used to trigger an external task to run. Using variables, BPA Platform data can be passed between the two tasks at run-time, if required. task step, the following prerequisites must be met.

(Recommended) Creating a Dedicated Call Task User

Although not necessary, it is recommended you create a dedicated user for the Call Task tool to use. This prevents Call Task tasks not being able to run because the credentials are being used elsewhere, for example, to log into the BPA Platform client.

Connecting to the Task Folder

You must create global connections to the required task folders first. You open this interface from the resources tree — expand System > Tools > Execute and double-click Call Task in the items list.

Tip: You cannot select individual tasks for at this stage, only task folders. It is recommended you organise your task list, not only according to business process or your organisational structure, but also to whether available to the Call Task tool. This way, those tasks that should not be used elsewhere are "locked out" of the tool.

For more information about using task folders, see Managing Task Folders.

To begin creating a new connection, click Add.
Provide the connection details for the BPA Platform server containing the called tasks — avoid the use of localhost, see below. Use the credentials of the dedicated Call Task user created previously.
How Do I Do This?
In Server, enter the hostname or IP address of the BPA Platform server hosting the required tasks.
Note: Do not enable Use Localhost or type localhost as the Server address if the BPA Platform client and server are located on separate computers. If you are using a remote client, use only the hostname or IP address of the BPA Platform server. Using localhost causes the task to fail as it tries to locate and run a task not present on the server computer.
Enter the credentials (Username and Password) of a BPA Platform account that has permissions to:
► Use the Call Task tool
► Access the folder and required task inside
Tip: Create a separate BPA Platform account specifically for running called tasks — this prevents clashes with logged in users. Windows accounts are not supported.
For more information, go to the main Connection tab topic.
Go to the Folder tab and choose the relevant task folder.
Note: You cannot select an individual task at this point. The layout of the Folder tab is only to allow you to view the folder contents. Individual task selection is made when adding a Call Task step.
Click OK to save and close this connection.

Adding a Call Task Step

To add a new Call Task step to an existing task:

Open the relevant task (if creating a new task, see How to Create a Basic Task).
Either:

►

Click and drag the Call Task icon from the Task Browser to the task Design area.

–OR–

►

From the task's Design tab, right-click on empty space and select New > Execute > Call Task.

Use the General tab to choose the BPA Platform data source to be mapped to the called task's objects. The data source must be in XML form. To map BPA Platform recordsets, configure a Convert Recordset to XML The Convert Recordset to XML tool converts one or more flat-structure BPA Platform recordsets into a hierarchical XML structure. It provides "translation services" between the standard BPA Platform tools, such as Database Query (ODBC), and advanced BPA Platform tools that accept XML as their input. or Transform Data Transform Data is a Format tool that enables a new structure to be created from an existing XML or recordset data source. The output generated by this tool is ready for use in a destination system which consumes or requires XML. step in the task before the Call Task step, then select this as Task step (see below).

How Do I Do This?

Click the image to view full size.

Provide a meaningful Name and Description for this step.

TIP: If this task instance makes use of two or more Call Task steps, ensure the Name used is unique for each individual step.

Choose your Data source . This can either be:

►

No data source — If you don’t make use of a dedicated XML input source, select this option to use BPA Platform variables in place of the XML objects’ fields.

For example, you can extract various bits of information from an email and store them in BPA Platform variables. The variables are then mapped to the called task'soperational objects and fields for use by the called task during its run time.

►

Task step — The data source can be set to an available BPA Platform XML data source.

Only those steps that are capable of natively exposing an XML document at runtime are listed. This may be another Call Task step, or a tool such as Convert Recordset to XML or Transform Data.

►

Custom schema — An XML schema defines the structure of the parsed XML: what tags are present, and the nesting of the tags. You Define the schema of the XML that is used as the input data source for this step. The Call Task tool uses the industry standard XSD format. Any XML processed by this step must conform to this schema else an error will be reported.

If the XSD schema is available, either import it into the Custom Schema Configuration (use the Import XSD/XML File button), or copy and paste it into the configuration box.

Click the image to view full size.

If the XSD schema is not available, you can import an example of the runtime XML (Import XSD/XML File), or copy and paste it into the configuration box. Use the Parse button to create the schema.

■

Input source variable — As well as defining the schema, you must specify the BPA Platform variable that contains the XML data at runtime.

Go to the Connection tab and choose the relevant folder connection for this task step.
How Do I Do This?
All connections created in the are presented here.
Alternatively, you can use a BPA Platform variable or formula to create a dynamic connection, where the connection used is determined by runtime circumstances. At runtime, the contents of the variable must match the name of one of the global connections — this is case-sensitive.
Note: Where variables or formulas are being used to create dynamic connections, you are prompted to select a template connection first to populate the Object and Operation drop-downs in the Mapping tab.

Go to the Mapping tab and choose the operation for this task step. If required, map any input data fields.

The Object drop-down shows the available tasks. The Operations drop-down shows the operations available for the selected Object:

►

RunSync — Runs the called task when called by the original task; the original task waits for the called task to complete before continuing. Parameter-type variables can be used to pass data between the tasks; with RunSync operations, the original task cannot complete until the data is passed back.

The data passed back is store in the output XML of the original task. This in turn can be consumed by another step capable of processing XML, such as the Convert XML to Recordset The Convert XML to Recordset tool is used to convert XML data into a flat-format BPA Platform recordset, allowing the data to be used by recordset-only consuming tools. This could then be used to power alerts via fax, email, or SMS, create reports, power a workflow, perform FTP transfer, and so on. tool.

Use this operation if the original task requires data from the called task.

►

Queued — Queues the second task but continues to run the original task to completion; both tasks run independently of each other. Data can be passed to a parameter-type variable in the called task. However, this operation does not allow data to be passed back as the original task has already completed running before the second task initialises.

Use this option when only triggering a task to run, with or without data from the originating task.

How Do I Do This?

The Mapping tab is used to select the task to run. However, you do not need to map data if the called task does not require any input data.

The Object drop-down shows the available tasks from the selected task folder. The Operations drop-down shows the operations available for the selected Object

Further down, the left-hand XML tree structure shows those data source fields available for mapping . The right-hand XML tree structure displays those input fields for the selected Object and Operation.

TIP: If you have selected No data source in the General tab, you must add BPA Platform formulas and variables to the left-hand data source XML tree structure before mapping.

Creating Mappings

You create links by dragging and dropping a data source field (left) onto its corresponding Call Task input field (right). Only linked fields are used in the output XML.

Note: You do not need to map data (create links) if the called task does not require any input data from this step during run-time.

BPA Platform formulas and variables can be included in the source data even when using a Task step or Custom schema — drag them from the Task Browser to the data source’s XML; these can then be linked to the relevant input fields. BPA Platform recordsets must first be converted to XML using either the Convert Recordset to XML or Transform Data tool before they can be used here.

Each operation has an additional field, SupplementaryReference, which allows for traceability when transferring data from one place to another. When mapped, the data resides locally at runtime. It is added to the output, and creates a record for reference purposes only — you can choose to map any field to SupplementaryReference to assist with checking where the data originated from or at what time the data transfer occurred, for example.

The tool uses eXtensible Stylesheet Language Transformations (XSLT) to translate the received XML. The Advanced Translations (XSLT) tab shows the XSLT generated for the links created for the object and operation. Use Enable Free Type Mode to directly edit the XSLT — this is particularly useful when translating a non-standard requirement.

Refreshing the Called Task's Schema

If new task data, such as variables, are added to the called task after this step was created, you must refresh the called task's schema in order to see the new data in the InputData schema — click Schema Refresh (first ensure Update Objects and Operations is selected in the relevant global connection).

For more information, go to the main Mapping tab topic.

Go to the Options tab and select the relevant error handling options for this task step.
How Do I Do This?
The Options tab allows you to define how errors in this step are handled at task runtime.
If an error occurs, you can decide whether the step should Continue processing, or terminate the step immediately (Abort Step).
If the step is aborted, you can choose to Continue processing onto the next step in the task, or terminate the whole task immediately (Abort Task). By allowing the task to Continue, you can use the error XML received back in a Save File The Save File tool saves output from another task step capable of producing document, as one or more files on the local drive, on-premise file server, external server, or cloud based server. step for investigation purposes, for example.
Click to save the task step.