SMS Messaging with K2

Introduction

The SMS Service allows the K2 Server to send SMS messages and to also receive text messages. The service also allows for K2 to act upon the content received in the message from simply storing the message, starting a specific workflow by texting a specific hash tag and lastly being able to action a task by sms message.

See it in Action

What Do You Need

For this service to work correctly you need to have a subscription to Esendex sms service (www.esendex.com) . You can register for a trial account to start off with. They will give you some sms messaging credits and a mobile number. You will need to make a note of the following information.

  1. Account Number
  2. Username
  3. Password
  4. Mobile Number

What is in the Service

The zip file contains the following components

  1. SQL scripts to create the database
  2. GUID for SQL db. Service Object
  3. Package and Deploy file for the K2 Artefacts
  4. SMS Receiver
  5. SMS endpoint assembly
  6. Code Solution for items 4 & 5

Setup

The following steps go through the process of setting up the K2 server with the SMS Service.

  1. Register for an account at Esendex.com
  2. Run the sql scripts. This will create the K2 SMS database
  3. The next step is to register the database with K2. When registering the database with K2 make sure the ‘Authentication Mode’ is set to ‘Service Account’ and the service is called ‘K2 SMS’ and it has this guid ‘1be32a72-9693-4f4a-a143-99adea6e850d’
  4. Once the service object has been created. You will then see all the stored procedures and tables that make up the K2 SMS database. It Should look something like this

k2sms_1

  1. The next service to register is a endpoint assembly that allows the K2 SMS Service to action tasks. In the zip file there is a .dll called ‘K2Core.dll’. Register this as a endpoint assembly with the name ‘K2 Core Tools’ and with the following guid ‘dab558bf-99ca-4a4f-80d7-865032849d5’ This will then create the following service objects for you.

k2sms_2

  1. The last service to install is another endpoint assembly that allows K2 to send sms messaging. Open up the solution ‘K2SMS’ and edit the project ‘K2SMS’ and edit the following files ‘Receive.cs’ and ‘SendTxt.cs’ and replace the following details with your Esendex details

         private static string _Username = “Esendex Username”;

         private static string _Password = “Password”;

         private static string _Account = “Account”;

Once you have done this build the project and then register the created dll as a endpoint   assembly.   Call the endpoint ‘K2 SMS’ and make sure it has the following guid ‘08700ee5-116f-4894-b921-1fd593e93554C’ It will then create the following the service objects

k2sms_3

  1. Now that all the service objects have been created. You can now deploy the K2 package called ‘K2 SMS.kspx’ This will deploy the following K2 Artefacts for you

k2sms_4

  1. Now that the package has been deployed you are now able to test the service by sending an sms message. Use the smartobject tester and execute the ‘Send SMS’ smartobject. Enter in a mobile number and the message. You should then receive the message on your mobile phone and if you execute the ‘GetInbox’ smart object. You will be able to see the message in the list.
  2. The next step is to add the web api handler that Esendex will post it’s responses too. In the zip file copy the folder ‘sms’ on to the c drive
  3. Open up IIS and expand ‘K2’. Right click and select ‘Add Application’
  4. Enter ‘K2SMS’ in the Alias and select ‘K2 Smarforms’ as the application pool and then browse to the ‘sms’ folder you copied over. It should look something like this

k2sms_5

  1. On the newly created application, click on ‘Authentication’ and enable ‘Anonymous Authentication’. Your handler is now ready to receive posts from Esendex. We now just need to tell esendex where to post the messages too.
  2. The url for your service will be the following

http://[domainname]/K2SMS/API/InboundMessages/Post

If you go to that URL now you should get a xml document error, don’t worry that is fine it’s just expecting to get a xml document.

  1. Login into your esendex account and go to ‘Developer tools’ and in the ‘Configure Push  Notifications’ section click on ‘configure’ for ‘SMS received’ and enter in the url of your sms handler.
  2. You are now ready to test the service. Reply back to the message you sent in step 8. If there is an error you will be sent an email to the account that was used to register the service.
  3. Go back to your smartobject tester and execute the ‘Messages’ smartobject. You should see the message you have just sent in the list. If you do the setup has been successful and K2 has picked up the message and saved it into sql and the server is now ready to use the service.

Using The Service

Now that the service has been installed you are now able to able to send and receive text messages. I have split the next section into a number of use cases

Simple Send and Receive

  1. To Send a message you can use the following smart object ‘Send SMS’ this allows you to send messages to any mobile number. It has the following parameters ‘Message’ and ‘Mobile Number’
  2. To be able to get a list of messages received you can use the ‘Messages’ smartobject this will show you a list of messages that K2 has picked up.

Starting a workflow from a SMS

To be able to start a workflow from a sms message. The service uses #hashtags to identify which process to start.

  1. The first thing to do is to register the workflow that wants to be started by a sms. Using the following smartobject ‘SMSHashtagLibrary’ You will need to provide the following information
    1. Hashtag
    2. Full Process Name
    3. App definition Id (App Framework)
    4. The process being called will also need to have some data fields added these are as follows
  2. AppDefinitionId (Integer)
  3. AppId (Integer)
  4. MessageId (Integer)

If the sms message contains more text after the hashtag it will try and connect it to an existing App Instance by matching the ‘App Instance folio’ to the additional text.

For example, if you sent the following message ‘#Help A0011’. The service would start the workflow linked to ‘#Help’ and then try and find the correct record where the folio in the smartobject ‘CM App’ matches ‘A011’

  1. You will also need to give the process that has been setup to start via sms permissions to be started via ‘ K2WebService’ account.
  2. Once you have done steps 1 to 3 you are now able to test the service. You can check to see if this has worked by looking in the ‘K2 workspace reporting’ to see if an instance of your sms enabled process has started.

Using the service to send tasks and actions via SMS

To be able to send a task and action a task via sms there is no special wizards it’s just a couple of smartobjects that need to called.

Send a Task

To send a task via SMS you will need to use the following smart object ‘SMSTasks’

The properties you need to populate are the following

  1. SN
  2. Status
  3. MessageId (If applicable)
  4. Mobile (Should be the mobile number of the destination user)
  5. AppId

Once these details have been created, the SMS service will now monitor the incoming messages for the serial number . Please note you will still need to create your normal client event with the destination user as a ‘K2 Web Service’

k2sms_6

The next smart object to use is the ‘Send SMS’. For the mobile number make sure it’s the same one used to record the task and that the message body contains the serial number and what the actions are.

Action a task via sms

To action a task via SMS, the user who received the text message will need to reply back to the message. The message will need to contain the serial number and the action. For example it would look like this ‘12_1222 Yes’

K2 will then pick up the message, it will first of all check to see if the serial number is valid for sms task actions. If it is it will then check to see if the mobile number the message was sent from is the same number the task was initially sent to. If it is all valid it will then try to execute the task based on the action that was included in the message.

Where can I get the service from

You can download the source code from GitHub https://github.com/SimonAllport/K2-SMS

K2 Artefacts and SQL shttp://1drv.ms/1C9KpUpcripts can be downloaded from here

This project is completely open source and is not supported by K2

8 thoughts on “SMS Messaging with K2

  1. I am developer tasked with implementing this.
    The download link “K2 Artefacts and SQL scripts can be downloaded from here” no longer works?
    Is there an updated URL?
    Thanks and Cheers

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s