How to Add a Retrieve Text Message Task Step

Prerequisites

Before adding a Retrieve Text Message 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. task step, ensure you have met the following:

Connecting to Your ToucanText Account

You must configure the connection to your ToucanText account before adding the Retrieve Text Message tool to a task in the global configuration interface. You open this interface from the resources tree — expand System > Tools > Input and double-click Retrieve Text Message in the items list.

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. In order to complete the registration process, you must have a valid email address and mobile number to hand.

Click Add to create a new connection to ToucanText.

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.

For more information, go to Connecting to ToucanText Accounts.

Adding a New Task Step

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

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

–OR–

3. Use the General tab to choose 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 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 Retrieve Text Message 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 Retrieve Text Message 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 ToucanTextoperational objects and fields to store in the 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 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 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.

   

   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.

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

4. Go to the Connection tab and select the relevant global 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.

5. Go to the Mapping tab and map the required input source to the ToucanText elements.
   How Do I Do This?

   

   Click the image to view full size.

   The Object drop-down shows the available 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.

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

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

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

7. Click  to save the task step.