How to Retrieve an Account Balance Using the Retrieve Text Message Tool

Part 1: Retrieving the Account Balance

This task retrieves the balance for the requested account number.

Required Tools

►

Parse Text The Parse Text tool extracts specific data from variables populated by other steps and then maps the data to other variables for use in further steps. — This step extracts the account number sent in the SMS request.

►

Database Query (ODBC) You typically use the Database Query (ODBC) tool to extract specific records from a relational database, using a valid ODBC driver to make the connection. These are then made available to other task steps as a recordset. — This step uses the account number from the Parse Text tool to extract the account balance from the relevant database table.

►

Run VBScript The Run VBScript tool is used to create a task step that runs a Visual Basic Script using data produced by other steps in the task. — This step uses VBScript to convert the account balance from the Database Query (ODBC) step into a variable, ready to be consumed by another task.

The following exercises only focus on the settings needed to fulfil the task. For a detailed description of how to use each tool, refer to the product help.

Part 1A — Creating Task Variables

Part 1B — Creating the Connection to the Database

Part 1C — Extracting the Account Number from the Received SMS

The SMS message contents are saved to the MessageRequest variable by a different task. This stage extracts the account number from the variable — we use the Parse Text tool for this.

1. Open the Message Processing Task.
2. Add a Parse Text step to the design area.
3. Name your step: Extract Account Number.
4. Go to the Main tab.
5. From the Task Browser, go to the Environment tab.
6. Change Scope to be Task.
7. From the Variables node, drag the MessageRequest variable to Data in the Main tab.
8. Click Add to create a new rule.
9. Name this rule: Remove BAL.
10. Change Type to be: Extract after word [C].
11. In the Parameters table, enter BAL as the Value — the Parse Text step will look for this phrase and extract everything after it.
12. From Variable output, select the AccountNumber variable created previously.
13. Enable Remove leading spaces and Remove trailing spaces.
14. Click OK to save the rule and OK again to save the changes in the Parse Text step.

Part 1D — Extracting the Account Information

We now need to retrieve the account balance according to the account number received. We do this using the Database Query (ODBC) tool.

1. Ensure Part 1B — Creating the Connection to the Database has been completed first.
2. Open the Message Processing Task.
3. Add a Database Query (ODBC) step to the design area.
4. Name the step: Retrieve Balance and Account.
5. From the Connection drop-down, select the global connection created in Part 1B.
6. Go to the Query tab — here, we specify the columns that contain the data we are interested in.

   Tip: The extracted data forms a BPA Platform recordset which can be used by other task steps to "forward the data" on.

7. Expand the SALES_LEDGER table and drag the following columns into the Columns pane:

■

ACCOUNT_REF

■

TELEPHONE_2

■

BALANCE

Click the image to view full size.

8. The query we have created so far extracts all accounts, telephone numbers, and balances; we just want the details for the account number sent in the SMS request. We do this by adding the account number extracted in Part 1C — Extracting the Account Number from the Received SMS
   1. Drag ACCOUNT_REF from the Columns pane to the Criteria pane.
   2. From the Select a criteria drop-down, choose equals [C].
   3. From the Task Browser, go to the Environment tab.
   4. Change Scope to Task.
   5. From the Variables node, drag AccountNumber to the ACCOUNT_REF criteria.

   Your query should now look like:

   

   Click the image to view full size.

9. For extra security, we can also match the mobile number held for this account to the number that sent the SMS. This ensures only valid contacts receive the balance response.
   1. Drag TELEPHONE_2 from the Columns pane to the Criteria pane.
   2. From the Select a criteria drop-down, choose equals [C].
   3. From the Task Browser, go to the Environment tab.
   4. Change Scope to Task.
   5. From the Variables node, drag SenderNumber to the TELEPHONE_2 criteria.

   The AND between the two criteria indicates that both entries must be met to continue.

10. Click OK to save the query.

Part 1E — Saving the Balance to a Variable

The final step of this task makes the retrieved balance available for the second task. You use the Run VBScript tool for this.

1. Open the Message Processing Task.
2. Add a Run VBScript step to the design area.
3. Name the step: Balance.
4. Got to the Main tab.
5. From the Task Browser, go to the Environment tab.
6. Change Scope to Task.
7. From the Variables node, drag Balance to the script area followed by <space>=<space>.
8. From the Task Browser, expand Steps > Retrieve Balance and Account > Recordset and drag BALANCE to complete the current line.

   The script should now look like:

   

9. Click OK to save the step.

Part 1F — Linking the Steps

To ensure BPA Platform runs the steps in the correct order, the individual task steps must be linked. You do this by clicking a step to display the step controls — click and hold and draw the connector to its successor.

If required, you can add a label to the connection. Double-click the connection line and add the label, up to a maximum of 100 characters. Note that this is a pure-text field so variables, formulas, functions, and Task Browser properties cannot be used in this area.

1. Link Extract Account Number to Retrieve Balance and Account.
2. Link Retrieve Balance and Account to Balance.

   Your task should now look like this:

   

3. Click OK to save this task.

That completes part 1 of this scenario. In parts 2 and 3, we're going to create the task that handles the sending of the account balance back to the sender.

Part 2: Processing the Inbound SMS Request

This task retrieves the inbound SMS requesting the balance.

Required Tools

►

Run VBScript — This step ends the task if there are no more SMS requests to process

The following exercises only focus on the settings needed to fulfil the task. For a detailed description of how to use each tool, refer to the product help.

Part 2A — Creating the Connection to ToucanText

You must create a connection to your ToucanText account to retrieve the incoming SMS requests.

1. Launch the BPA Platform client.
2. From the resources tree, go to System > Tools > Input > Retrieve Text Message.
3. Click Add.
4. Enter a meaningful Name for this connection.
5. Enter the API Username and API Password for your ToucanText account.
6. Click Test to ensure the connection can be made.
7. Click OK then OK again to save the connection.

Part 2B — Retrieving the Inbound SMS Requests

For this part of the business process, we will create a new task to handle this part.

1. Create a new task in the same location as the Message Processing Task created in Part 1: Retrieving the Account Balance.
2. Name this task: Picks Up Inbound Messages.
3. Go to the Design tab and add a Retrieve Text Message step.
4. Leave this with its default name and ensure No data source is selected as the Data source.
5. Go to the Connection tab.
6. Select the Connection created in Part 2A — Creating the Connection to ToucanText.
7. Go to the Mapping tab.
8. From the Object drop-down, select Message.
9. From the Operation drop-down, select Retrieve Inbound Message.
10. Now we need to add two new task variables:

Name	Type	Parameter Attributes	Scope	Default Value
ACK	Variant	N/A	Task Instance	true
MaxMsgCount	Variant	N/A	Task Instance	50

11. Drag both variables to the input data source pane (left) in the Mapping tab.
12. Map the ACK variable to the AcknowledgeMessages field — this sends an acknowledgement back to ToucanText that the inbound message has been picked up and processed by the task so must not be included in future message requests.
13. Map the MaxMsgCount to the MaxMessageCount field — this is a required field that must be mapped to and controls the number of messages that are retrieved from ToucanText for this task instance.

Click the image to view full size.

14. Click OK to save and close the step.

Part 2C — Initiating the Message Processing Task

The next stage of the task is to send the details from the Retrieve Text Message step to the Message Processing Task. You do this with the Call Task tool. First, we need to create a global connection to the folder containing the task — even if you have placed your tasks in the top-level Tasks folder, you must still create the connection.

Creating a Dedicated Call Task User

We must create a dedicated user for the Call Task step to use — this prevents clashes with other user accounts that may be logged into the BPA Platform client at the same time:

1. Save and close the Picks Up Inbound Messages task.
2. From the resources tree, right-click on Users and select New User.
3. Enter calltask as the User name.
4. Enable BPA Platform Authentication and enter a password that adheres to your organisation's security policies. Confirm the password.
5. Go to the Server Roles tab and ensure all server roles are cleared.
6. Click OK to save and close the user.

Creating the Global Connection to the Task Folder

Now we can create the global connection to the relevant task folder:

1. From the resources tree, go to System > Tools > Execute > Call Task.
2. Click Add.
3. Enter a Connection Name of Balance Enquiry Tasks.
4. As the tasks are run on the same computer as this BPA Platform client, enter localhost as the Server.
5. Enter the calltask user's details in Username and Password.
6. Go to the Folder tab and select the folder containing these tasks.

7. Click OK to save and close the global connection.

Click the image to view full size.

Adding the Call Task Step

Finally, we add a Call Task step to the task.

1. Open the Picks Up Inbound Messages task.
2. Add a Call Task step to the task design area.
3. Name this step Call Message Processing Task.
4. Enable Task step and ensure Output Data from Retrieve Text Message is selected in the drop-down.
5. Go to the Connection tab and select the connection created previously.
6. Go to the Mapping tab.
7. From the Object drop-down, select Message Processing Task.
8. From the Operation drop-down, select Run Sync — this operation ensures that the Picks Up Inbound Messages task is paused until the Message Processing Task is finished so that the generated task data from the Message Processing Task can be used.
9. Make the following mappings:

■

SourceAddress » SenderNumber

■

MessageContents » MessageRequest

Click the image to view full size.

10. Click OK to save and close the step.

Part 2D — Ensuring the Task Only Runs When There's a Message to Process

In this exercise, we're going to add logic to the task to check whether there are any unprocessed inbound messages. If there are none, the task terminates cleanly. Without this, the task will attempt to initiate each step in the task which results in the Event Log being filled with failed task messages.

1. Add a Decision step to the Picks Up Inbound Messages task — this chooses whether the task should continue based on rules you add.
2. Name this step: Any more messages?.
3. Click Add.
4. Name this branch: Yes.
5. From the To drop-down, select Call Message Processing Task.
6. Go to the Script tab.
7. From the Task Browser, go to the Environment tab.
8. Change Scope to Task.
9. Expand Steps > Retrieve Text Message and drag the MessageCount node to the Expression box.
10. Add >0 to the end of the expression so you have:

    Steps("Retrieve Text Message").MessageCount>0

11. Click OK to save this branch.

Now we need to add the No branch.

1. Click OK to save and close the Decision step so far.
2. Add a Run VBScript step to the task.
3. Name this step: No Messages.
4. No further configuration or scripting is required for this task so click OK to save and close the step.
5. Re-open the Decision step and click Add to add a new branch.
6. Name this branch: No.
7. From the To drop-down, select No Messages.
8. Go to the Script tab and enable Else — this is the catch-all branch that indicates whatever doesn't fulfil the other branch should follow this one.
9. Click OK to save this branch, then OK again to save the step.

   Because you have nominated the steps to take for different scenarios, the Decision step automatically creates the connections:

   

10. At this point, you can link the Retrieve Text Message step to the Decision step.

That's part 2 complete. In part 3, we're going to finish this task to complete the full business process.

Part 3: Sending the Account Balance via SMS

This final part completes the task so the account balance is sent back to the sender.

Required Tools

►

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. — This step converts the task data from the Message Processing Task and makes it available for other task steps to use

►

Format as Text The Format as Text tool creates single or multiple text documents, using information provided by Input tools such as the Database Query (ODBC) tool. It requires no global settings. — This step generates the text to be sent back to the sender

►

Send Text Message The Send Text Message tool is used to create and send data-driven, personalised text messages to customers, employees, prospects, suppliers, and so on. Sending can be automated to guarantee the timing of the text messages. — This step sends the generated message back to the sender

►

Schedule The Schedule tool is used to trigger a task to run based on a date and time schedule. Any number of Schedule steps can be created for a task. — We use this step to automatically trigger the task to run

Part 3A — Creating a Global Connection to ToucanText

For the Send Text Message tool to send the balance, we must create a connection to the same ToucanText account used for the Retrieve Text Message tool (see Part 2A — Creating the Connection to ToucanText).

Installing the Send Text Message Message Gateway Modules

If you haven't already installed the required Message Gateway modules, do the following (these are the modules that sit between the Send Text Message tool and the SMS centre):

1. Launch the Configurator You use the Configurator to install third-party software that may be required by available tools. Connection to required agents are also configured here. Note that you can only launch the Configurator if logged into the machine with Administrator rights..
2. Expand Tool Specific > Send Text Message > Prerequisites.
3. Click Install where prompted for any missing modules.
4. Click Next to move to the Message Gateway Agent > Prerequisites node.
5. Click Install where prompted for any missing modules.
6. Click Next.
7. Register the Message Gateway Agent and click Save.

Creating the ToucanText Connection

Now we can create the connection to your ToucanText account.

1. Launch the BPA Platform client.
2. From the resources tree, go to System > Tools > Output > Send Text Message.
3. Click Add.
4. Enter a meaningful Connection name.
5. Leave Provider as ToucanText Message Gateway.
6. For Server, enable Local Computer.
7. Enter the API Username and API Password for your ToucanText account.
8. Click Test to ensure the connection can be made.
9. Once the test is successful, click OK to save and close this connection.
10. Click Close.

Part 3B — Processing the Task Data from the Call Task Step

The Call Task tool outputs task data in XML form. This cannot be read by the tools required to complete this task so we must convert the data to a BPA Platform recordset first. You use the Convert XML to Recordset tool for this.

1. Re-open the Picks Up Inbound Messages task.
2. Add a Convert XML to Recordset step.
3. We'll leave this with the default name so go straight to the Main tab.
4. Enable Task Step and select Output Data from Call Message Processing Task.
5. From the Output recordset configuration pane, expand all nodes and enable OutputData — this selects all child nodes as well. Each child node then forms a column in the recordset created by this task.
6. Click OK to save and close this step.

Part 3C — Creating the SMS Response

We now need to create the message that is sent; we do this in the Format as Text tool. Although you can create the message directly in the Send Text Message tool, it cannot loop through a recordset and send an SMS for each row found (we previously set the Message Processing Task to retrieve a maximum of 50 messages, with each message becoming a single row (a record) in the recordset). Instead, we leave this "job" up to a Format tool which sends each processed row individually to the Output tool.

1. Add a Format as Text step to the Picks Up Inbound Messages task.
2. Name this step: Create SMS Message.
3. Enable Use a Recordset and select Results from Convert XML to Recordset from the Input Recordset drop-down.
4. Go to the Formatting tab.
5. Enable New document for each row — this forces the Format as Text step to loop through the recordset and create a separate SMS document for each record found.
6. In the free text area, type:

   Your balance is: £

   Note: The training database does not hold the currency symbol as part of the BALANCE column; if using a different database, adjust the currency symbol here for your organisational needs.

7. From the Task Browser, go to the Environment tab.
8. Change Scope to This Step.
9. Expand Format as Text > RecordSource and drag OutputData_Balance and drop it after the currency symbol.

   Your SMS message should now look like: Your balance is: £{=ThisStep.RecordSource("OutputData_Balance")}

   When the task is run, {=ThisStep.RecordSource("OutputData_Balance")} is replaced with the value from the BALANCE column in the database.

10. Click OK to save and close this step.

Part 3D — Sending the SMS Message

This part of the task sends the SMS back to the original sender.

1. Ensure Part 3C — Creating the SMS Response has been completed first.
2. Add a Send Text Message step to the Picks Up Inbound Messages task.
3. Leave Name as the default.
4. Enable Read documents from a source and select Documents from Create SMS Message [Text] from the drop-down.
5. Go to the Connection tab and select the Connection created in part 3c.
6. Go to the Main tab.
7. Click To then Add.
8. From the Task Browser, go to the Environment tab.
9. Change Scope to This Step.
10. Expand Send Text Message > DocumentSource > Recordset and drag OutputData_SenderNumber to Mobile / Pager Number:

    

11. Click OK twice to return to the main Send Text Message interface.
12. Ensure Document Output in the Message Contents pane is selected — this ensures the body of the SMS sent only contains the contents of the Format as Text step.
13. Click OK to save and close the step.

Part 3E — Joining the Steps

To ensure BPA Platform runs the steps in the correct order, the individual task steps must be linked. You do this by clicking a step to display the step controls — click and hold and draw the connector to its successor.

If required, you can add a label to the connection. Double-click the connection line and add the label, up to a maximum of 100 characters. Note that this is a pure-text field so variables, formulas, functions, and Task Browser properties cannot be used in this area.

1. Link Call Message Processing Task to Convert XML to Recordset.
2. Link Convert XML to Recordset to Create SMS Message.
3. Link Create SMS Message to Send Text Message.

   Your task should now look like this:

Part 3F — Scheduling the Task

Currently, the task must be manually queued for it to check for and reply to SMS balance requests. Using an Event tool, we can have the task trigger based on an external event — the most suitable tool for this task is the Schedule tool which triggers tasks to run based on a date schedule.

1. Add a Schedule step to the Picks Up Inbound Messages task.
2. Name this step: Run every minute.
3. Go to the Main tab.
4. From the Schedule pane, enable Minutes.
5. Leave all options with their defaults so this task runs every minute and click OK to save and close the step.
6. Connect this step to the Retrieve Text Message step so it becomes the first step in the task.
7. Click OK to save and close the task.

Part 3G — Testing the Task

We can now test the whole task by sending a balance request SMS to ToucanText.

1. Add a test record to your customer database containing your mobile number, a customer account number, and a balance value.
2. Send an SMS message starting with the word BAL followed by the test account number to the ToucanText inbound number assigned to your account.
3. Watching the BPA Platform client, you can see the task fire in the Active Tasks pane; you should receive an SMS back from ToucanText containing the text added in the Format as Text step.

That completes this task.

Why not see if you can expand this task to send replies to customer satisfaction surveys, order status requests, and so on.