Send SMS message to recipients from CSV file upload

This tutorial shows how to create and test a workflow definition that extracts names and phone numbers from a CSV file. Use a third party SMS gateway to send SMS message to those phone numbers.

• Scenario
• Prerequisites
• Step 1: Sign up to an SMS gateway
• Step 2: Setup sandbox destination phone numbers
• Step 3: Create Identity and Access Management (IAM) policy to publish SMS messages
• Step 4: Create IAM user with AmazonSNSPublishSMS policy
• Step 5: Create access key and secret access key for user_to_send_sms user
• Step 6: Create AWS credentials
• Step 7: Create SimWorkflow page
• Step 8: Create SimWorkflow workflow definition
  • Step 8.1: Review CSV file structure
  • Step 8.2: Plan the workflow definition
  • Step 8.3: Design the workflow definition
• Step 9: Define variables
• Step 10: Run the workflow definition
  • Workflow definitions
  • User input form
  • Workflow tasks
• Summary

Scenario

Assume that you're an employee at a travel agent company named Example Corporation. The company uses a CSV file to keep track of clients who are interested in tours. The CSV file gets updated daily. You have been asked to implement an automated process to send SMS to the clients when a new tour is scheduled.

Prerequisites

To perform the steps in this tutorial, you must already have the following:

• An account with a third-party SMS gateway to send SMS messages.
• A SimWorkflow account that you can log in to create pages and workflow definitions.

Step 1: Sign up to an SMS gateway

An SMS gateway is required to send SMS messages.

For this tutorial, we're using Amazon Simple Notification Service (SNS).

If you're a first-time user of AWS, your first step is to sign up for an AWS account.

Step 2: Setup sandbox destination phone numbers

1. Login to AWS.
2. Navigate to AWS Console.
3. Select an AWS region.
4. Click Services and select Simple Notification Service.
5. Under Mobile left menu, click Text messaging (SMS).
6. Click Add phone number button in Sandbox destination phone numbers section.
7. Enter the phone number to receive text SMS messages.
8. Click Add phone number button.

Step 3: Create Identity and Access Management (IAM) policy to publish SMS messages

1. On AWS Console.

2. Click Services and select IAM.

3. Under Access management left menu, click Policies.

4. Click Create policy button in Policies section.

5. Select JSON Policy editor.

6. Define the following policy to allow sns:Publish action:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "sns:Publish"
         ],
         "Resource": "*"
       }
     ]
   }
   

7. Click Next button.

8. Enter the policy name. For this tutorial, we're using AmazonSNSPublishSMS.

9. Click Create policy button.

Step 4: Create IAM user with AmazonSNSPublishSMS policy

1. On AWS Console.
2. Click Services and select IAM.
3. Under Access management left menu, click Users.
4. Click Create user button in Users section.
5. Enter the username. For this tutorial, we're using user_to_send_sms.
6. Click Next button.
7. Select Attach policies directly for Permissions options.
8. Search for AmazonSNSPublishSMS and check its checkbox.
9. Click Next button.
10. Click Create user button.

Step 5: Create access key and secret access key for user_to_send_sms user

1. On AWS Console.
2. Click Services and select IAM.
3. Under Access management left menu, click Users.
4. Select user_to_send_sms from the Users section.
5. Click Create access key for Access key 1 in Summary section.
6. Select Command Line Interface (CLI) for Use case.
7. Check Confirmation checkbox.
8. Click Next button.
9. Enter the description.
10. Click Next button.
11. Copy Access key, we'll paste it later.
12. Copy Secret access key, we'll paste it later.
13. Click Done button.

Step 6: Create AWS credentials

1. Log in to the SimWorkflow.

2. Navigate to Credentials.

3. Click Create credentials button.

4. Select AWS tab.

5. Enter Amazon SNS in the Name field.

6. Paste the Access key in the Access key ID field.

7. Paste the Secret access key in the Secret access key field.

8. Click Create credentials button.

We'll use this credentials in the workflow definition when we integrate with AWS SNS to send SMS messages.

Step 7: Create SimWorkflow page

To support the upload of CSV file, we create a SimWorkflow page with form to allow the user to upload CSV file.

1. Navigate to Pages.
2. Click New page button.
3. Enter Upload CSV to send SMS for the page title.
4. In the page body, press / to open up the menu and select Paragraph text option.
5. Enter uploadFiles in the Field name field.
6. Enter Please attach the CSV file with customer details to send SMS in the Field label field.
7. Check the Required field checkbox.
8. Check the Rich text editing checkbox.
9. Click Save button.
10. Click Close button.

We'll use this page in the work flow definition as a task processor for the user task.

Step 8: Create SimWorkflow workflow definition

Step 8.1: Review CSV file structure

The CSV file to have the following structure:

First_Name,Surname,PrimaryPhone
Ben,Smith,"+61491571491"
Tom,Ford,

For this CSV, we have the following data:

1. First client with first name (First_Name), surname (Surname), and primary phone number (PrimaryPhone)
2. Second client with just first name, surname, and no primary phone number

As the second client doesn't have the primary phone number, we need to skip such records.

Step 8.2: Plan the workflow definition

There are three key steps in the business process:

1. A way to allow the user to upload the CSV file.
2. Read the CSV file and prepare the SMS messages.
3. Use the SMS gateway to send an SMS message to each phone number.

For this, we will define three respective tasks in the main workflow definition:

Within the Send SMS Map task, we'll define a Amazon SNS send SMS HTTP task to integrate with Amazon SNS to send the SMS messages.

Step 8.3: Design the workflow definition

1. Log in to the SimWorkflow.

2. Navigate to Workflow definitions.

3. Click Create workflow definition button.

4. Select General tab of the workflow definition.

5. Enter Read CSV file and send SMS messages to the Name field.

6. Click User Task to add a user task and name it Upload CSV file.

7. Connect the Start task to the Upload CSV file task.

8. Click Upload CSV file task and select Task Processor tab.

9. Select Upload CSV to send SMS page as the task processor.

10. Click JQ Task to add a system task and name it Prepare SMS messages.

11. Connect the Upload CSV file task to the Prepare SMS messages task.

12. Click Prepare SMS messages task and select Input Parameters tab.

13. Enter the following JSON object to the Input parameters field:

    {
      "input": "${swf:file:${['Upload CSV file'].attachments[0].id}}"
    }
    

    The system will read the uploaded CSV file from Upload CSV file task to the "input" field.

14. Click Prepare SMS messages task and select JQ Filter tab.

15. Enter the following JQ filter expression to the Expressions field:

    .input[] | {
        body: "Hi " + .First_Name + ", your schedule has been updated. Please check your travel itinerary.",
        to: .PrimaryPhone
    } | select(.to != "")
    

    The system will convert each element of the input array to a JSON object with the "body" field contains the SMS message, and the "to" field contains the recipient phone number. Ignore the element that does not have the phone number.

    The output of the Prepare SMS messages task will be the JSON object with the "result" field contains the first element of the result list and "resultList" field contains all the elements.

16. Click Map Task to add a system task and name it Send SMS.

17. Connect the Prepare SMS messages task to the Send SMS task.

18. Click Send SMS task and select Configuration tab.

19. Enter ${resultList} to the Map items JSONPath expression field.

20. Click the down arrow icon next to the Send SMS task to enter the map.

21. Click HTTP Task to add a system task and name it Amazon SNS send SMS.

22. Connect the Map Task - Start task to the Amazon SNS send SMS task.

23. Click Amazon SNS send SMS task and select Input Parameters tab.

24. Enter the following JSON object to the Input parameters field:

    {
      "action": "Action=Publish&Message=${jsonata:$encodeUrl(`swf:item`.body)}&PhoneNumber=${jsonata:$encodeUrl(`swf:item`.to)}&MessageAttributes.entry.1.Name=AWS.SNS.SMS.SenderID&MessageAttributes.entry.1.Value.DataType=String&MessageAttributes.entry.1.Value.StringValue=SimWorkflow&Version=2010-03-31&AUTHPARAMS",
      "awsRegion": "${['swf:variables'].awsRegion}"
    }
    

    The system will create the action for the Amazon SNS Publish API to send the SMS message to the "input" field.

25. Click Amazon SNS send SMS task and select Configuration tab.

26. Select Amazon SNS (AWS) to the Credentials field.

27. Enter the following JSON object to the HTTP request field:

    {
      "url": "https://sns.${awsRegion}.amazonaws.com/?${action}",
      "method": "GET"
    }
    

    The HTTP request configuration will call Amazon SNS Publish API to send the SMS message.

28. Click Save button.

29. Toggle the Enable checkbox to enable the workflow definition.

Main workflow definition

Send SMS Map task definition

Use this workflow definition

Step 9: Define variables

1. Navigate to Workflow definitions.
2. Click Variables menu item from the three dots (more options) menu of the Read CSV file and send SMS messages workflow definition.
3. Enter awsRegion to the Variable key field.
4. Enter AWS region to the Variable value field.
5. Click Save variable button.

Step 10: Run the workflow definition

1. Navigate to Workflow definitions.
2. Click Run menu item from the three dots (more options) menu of the Read CSV file and send SMS messages workflow definition.
3. On the form, drag the CSV file from your machine to the text input and click Submit button.
4. The system will send the SMS message to the phone numbers in the CSV and the workflow Completed.

Workflow definitions

User input form

Workflow tasks

Summary

You've now successfully completed all the steps necessary to define a workflow definition to support a business process. You've learned how to create a page with a form to capture user input. Furthermore, you've learned how to integrate with a third party API to send SMS messages. As a result, you are able to have a process in place that allows a user to upload a CSV file and send SMS message to the clients in the CSV.