Retrieve Text Message Tool

What is the Retrieve Text Message Tool?

Inbound messages to ToucanText can be processed using the Retrieve Text Message tool. Delivery receipts for messages sent by the Retrieve Text Message tool can also be processed.

Retrieve Text Message Tool Features

• Uses XML
• Map inbound text message data to BPA Platform data, including task variables
• Map inbound delivery message data to BPA Platform data, including task variables
• Ability to reply to inbound messages
• Drag-and-drop mapping interface; only map what is required to be sent to and retrieved from ToucanText
• Visual links to easily identify the mappings between the XML source data and the outgoing XML sent to the ToucanText API

White Paper - Retrieve Text Message

The Retrieve Text Message white paper introduces the tool.

Download White Paper

Retrieve Text Message Tool Architecture

The diagram below provides a high-level system architectural overview of the Retrieve Text Message tool with BPA Platform and the ToucanText API:

The Retrieve Text Message tool must be installed on the same machine hosting the BPA Platform client that runs the Retrieve Text Message tasks, as well as the main BPA Platform server.

The Retrieve Text Message tool communicates with the ToucanText API. It is through this that messages inbound to ToucanText can be retrieved.

Retrieve Text Message Tool Technical Summary

The following tools can interact with the Retrieve Text Message tool:

Consuming From Other Tools

The following tools produce output which the Retrieve Text Message tool can use to map to ToucanText objects:

Icon	Tool Name	Tool Category
	Import XML Document	Input
	Retrieve Text Message	Input
	Convert Recordset to XML	Format
	Transform Data	Format
	Call Task Tool	Execute
	Applications Platform Connector	Data Connectors

Objects Consumed

The Retrieve Text Message tool consumes the following objects from other tools:

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

Exposing to Other Tools

The following tools can use the XML outputted by the Retrieve Text Message tool:

Icon	Tool Name	Tool Category
	Retrieve Text Message	Input
	Convert XML to Recordset	Format
	Run Microsoft Reporting Services	Format
	Transform Data	Format
	Save File	Output
	Call Task	Execute
	Applications Platform Connector	Data Connectors
	Web Service Connector	Data Connectors

Objects Exposed

The Retrieve Text Message tool outputs the following objects which can be consumed by other tools:

• OutputData
  The OutputData object contains two sub-objects:
  • XmlString — This is the XML document produced by the tool, containing data returned from the ToucanText API 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 ToucanText API
    <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 ToucanText API
    <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.
• MessageCount — When exposed by a “send” operation (see About the Mapping Tab), this property returns the number of messages sent to the ToucanText API. When exposed by a “retrieve” operation, this property returns whether the operation was successful (1) or not (0) — this is because inbound messages are retrieved in a single batched call , with the number of messages returned determined by the mapped MaxMessageCount element.
• Step Properties
  Standard step properties are also available allowing you to use statistical data of the Retrieve Text Message 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.

Supported Objects

At the time of writing, the only object that can be mapped to is Message.
Three operations are available for the Message object:

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.

Connecting to ToucanText Accounts

You must configure the connection to your ToucanText account before adding the Retrieve Text Message tool to a task.

You open the Retrieve Text Message dialog by:

Opening this window from the resources tree — expand System > Tools > Input and double-click Retrieve Text Message in the items list.

When a connection is created, the available objects and fields are retrieved from the ToucanText API.

If you do not have a ToucanText account click Sign-Up. This redirects you to the ToucanText website where you can create the account to retrieve messages from.

Click Add to create a new connection to ToucanText.

Using Extended Logging

Enabling this option exposes the XML parsed between the Retrieve Text Message tool and the ToucanText API.

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

Connecting to the ToucanText Account

You must provide the ToucanText API username and password assigned to the account you want to retrieve
messages for.

Enter a unique Connection Name.

Provide the Username and Password for the Retrieve Text Message tool to use when connecting to ToucanText.

Use Test to ensure the Retrieve Text Message tool can reach the ToucanText API.

Update Objects and Operations

Enabling Update Objects and Operations allows the ToucanText schema in BPA Platform to be refreshed every time an update is made in the API itself.

Should you also upgrade ToucanText to a newer, compatible version, all related schemas within BPA Platform will be refreshed.

The schemas are refreshed when this selection and change has been saved. You must repeat this for each existing connection you have defined.

Step Configuration

To add a new Retrieve Text Message step to an existing task, you either:

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

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 ToucanText API 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 Retrieve Text Message step, then select this as Task step (see below).

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. These can then be mapped to operational fields.
  For example, you can extract various bits of information from an email and store them in BPA Platform variables. Then, having mapped them to ToucanText objects and operations, these can be stored in the ToucanText database for later use.
• 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 Retrieve Text Message 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 will be used as the input data source for this step. The Retrieve Text Message 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.

  

  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

You must specify the Retrieve Text Message Connection this step must use.

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.

About the Mapping Tab

Here you define links between the data source XML (see About the General Tab) and that required by ToucanText. This defines how, at runtime, the incoming XML is to be translated into the XML required for the relevant object and operation.

The Object drop-down shows the ToucanText objects. 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 Retrieve Text Message 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 Retrieve Text Message 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.

About the Options Tab

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