Skip to content

Knowledge Base

White Paper Libary

Call Task Tool

Introduction to the Call Task Tool

What is the Call Task Tool?

The Call Task tool is used to trigger another task to run from the current task. If required, you can use consumed XML from another step or variables to pass task data between the two during run-time.

Tasks initiate all steps irrespective of whether they are required. This can result in extended completion times. The best use of the Call Task tool is to break down large tasks into smaller, manageable tasks consisting of a few steps, with a central “control” task to trigger the other tasks. By doing this, you balance the load on the computer as the BPA Platform server only needs to initiate those tasks and steps required for that process.

Call Task Call Tool Features

  • Configure the Call Task API via an easy-to-use interface
  • Trigger another task to run either in sync with the original task or after
  • Call other tasks to run that are present on another BPA Platform server
  • Pass variables and XML data into a Call Task step for use in the task to be run
  • Retrieve data back from the called task when run in sync
  • Create a record of a task call for reference purposes
White Paper - Call Task Tool

White Paper - Call Task Tool

The Call Task white paper describes how to use the tool.

Download Whitepaper

Call Task Tool – Working with Other Tools

Consuming from Other Tools

IconTool NameTool Category
Import Flat File ToolImport Flat FileInput
Call Task ToolImport XML DocumentInput
Call Task ToolRetrieve Text MessageInput
Call Task ToolConvert Recordset to XMLFormat
Call Task ToolTransform DataFormat
Call Task ToolCall TaskExecute
Call Task ToolApplications Platform ConnectorData Connectors

Objects Consumed

The Call Task tool consumes the following objects exposed by other steps:

  • XML — XML data from any BPA Platform tool capable of exposing XML (see above)

Exposing to Other Tools

The following lists those tools that can directly consume a Call Task step’s output. This is useful when the tool retrieves output data back from the called task and saves to a variable. The variable data can then be used in the original task.

IconTool NameTool Category
Import Flat File ToolRetrieve Text MessageInput
Call Task ToolConvert XML to RecordsetFormat
Call Task ToolFormat as Flat FileFormat
Call Task ToolRun Microsoft Reporting ServicesFormat
Call Task ToolTransform DataFormat
Call Task ToolSave FileOutput
Call Task ToolCall TaskExecute
Call Task ToolApplications Platform ConnectorData Connectors
Call Task ToolWeb Service ConnectorData Connectors

Objects Exposed

The Call Task tool outputs the following objects which can be consumed by other tools:

  • InputData

    This document contains the XML received by the Call Task tool. It is only available if a task step has been selected as the Data Source.

  • OutputData

    The OutputData object contains two sub-objects:

    • XmlString — This is the XML document produced by the tool, containing data returned from the called task for all operations. Also included are the key fields for the mapped elements affected by the used operation and a SupplementaryReference field for task auditing purposes.

      The mappings made in the Mapping tab define the structure of this XML document.

    • XmlSchema — This contains the output schema in XSD format.
  • ErrorData

    The ErrorData object also contains two sub-objects:

    • XmlString — This contains any error data reported by the called task

      <Error> — All errors are created as an <Error> node, with the following sub-nodes:
      <Object /> — The name of the requested object
      <CODE /> — The error code returned by the called task
      <MESSAGE /> — The corresponding error message
      <EXTENDEDINFO /> — A string containing additional information about the error
      <INPUTDATA /> — The header input data (excluding child nodes) mapped for the object, plus all data contained in SupplementaryReference
      </Error>

    • XmlSchema — This contains the output schema in XSD format.
  • Step Properties

    Standard step properties are also available allowing you to use statistical data of the Call Task step.

Where Can the XML Output be Used?

Both the OutputData and ErrorData documents can be directly used by succeeding task steps that can consume XML data, as part of an application integration or synchronisation process. To use the documents in a non-XML consuming tool, use a Convert XML to Recordset step first to create a recordset copy of the XML data.

The XML documents are also available as consumable objects from the BPA Platform Browser (XmlString). When used in a task step, such as Format as Text or Save File, this exposes the actual XML string.

Global Configuration

Before using the Call Task tool in a task, you must select the folders which contain the tasks available to use elsewhere.

You open the Call Task – Global Configuration interface by:

Oppening the interface from the resources tree — expand System > Tools > Execute and double-click Call Task in the items list.

Call Task Tool

Using Extended Logging

Enabling this option exposes the XML parsed. The task’s folder is also exposed.

Without extended logging, the Event Log only contains start and end of transaction messages, plus any error messages encountered at runtime.

You can view the extended log in the BPA Platform Event Log (Manage > Event Log).

About the Connection Tab

In the Connection tab, you specify the location of the task folder this connection refers to.

Call Task Tool

In Server, enter the hostname or IP address of the BPA Platform server hosting the required tasks.

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

About the Folder Tab

From the Folder tab, select the relevant task folder that contains the task(s) to be called.

Call Task Tool

Step Configuration

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

  • Click and drag the Call Task icon from the Task Browser to the task Design area.
  • From the task’s Design tab, right-click on empty space and select New > Execute > Call Task.

For a detailed description of how to create new tasks, refer to the product help.

About the General Tab

Use the General tab to name 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 step in the task before the Call Task step, then select this as Task step (see below).

Call Task Tool

Provide a meaningful Name and Description for this step.

Data source 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 or recordset objects’ fields.

    For example, you can extract various bits of information from an email and store them in BPA Platform variables. The variables are mapped to the called task’s operational 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.

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

Call Task Tool

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, specify the BPA Platform variable that contains the XML data at runtime.

About the Connection Tab

All connections created in the Global Configuration are presented here. Alternatively, you can use a BPA Platform variable 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 Configuration connections — this is case-sensitive.

Call Task Tool

About the Mapping Tab

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.

Call Task Tool

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.

Creating Mappings

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.

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

Refreshing the Called Task’s Schema

If new task data, such as variables, are added to the called task after this Call Task 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.

Supported Operations

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

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

About the Options Tab

The Options tab allows you to define how errors in this step are handled at task runtime.

Call Task Tool

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 step for investigation purposes, for example.

White Paper - Call Task Tool

White Paper - Call Task Tool

The Call Task white paper describes how to use the tool.