Synapse Software

Send SMS Messages from Cherwell

02 Jun 2020

Transcript

Hi. I’m really excited to share with you today our brand new mApp that enables Twilio integration to send SMS messages.

So the first part of this video is going to be a quick demo of how the mApp works; the second part of the video is how to install the mApp: there are a couple different levels and I’ll talk through some of them and then finally I’ll get into some of the details of how the mApp actually works so that you can build on top of it.

So without further ado, let’s get into the demo. One quick note is that the mApp installs these one steps that I’m going to show into the Blueprint scope just as kind of an extra security precaution so that you don’t open up the ability to send SMS messages to everybody in your organization right off the bat If you’re familiar with how to build content in Cherwell it’s very easy to create a one-step that calls another one step and that’s what we intend here.

I’m just going to open up this one step that I’ve created in the Global scope for this demo called “Send SMS message.” Really all it does is runs another One Step and this other One Step is actually in the Blueprint scope. I did create this One Step through a blueprint but exposed it in the Global scope so that I could actually run it for this demo.

I’ll click “Run” – it’ll ask me for a phone number. I’m going to type in my cell number and then it’ll ask me for a message. I’ll just say “hello”, then it’ll show me a preview of the message. I’ll click OK and it sent the message, so in just a minute I’ll receive that on my phone.

That’s basically how the mApp works.

Now, there are additional integrations that we’ve built into the mApp to allow, say, sending a text message from an Incident to the Customer that sent that in. So let’s go ahead and create a new Incident. We’re not going to do anything fancy on this Incident – we’ll just say “call source” is “phone”, for “customer” I’m going to choose myself, we’ll add a description, we’ll pick something for service classification, and a priority. Basically just fill out all the required fields. We’ll save this this Incident and now I’m going to go into my One-Step Manager, Association Incident, and find another One-Step that I have called “Send SMS Message to Customer.”

Again, this is just a very simple One-Step that runs another One-Step that is the one that’s installed by the mApp. I’m going to click “Run” – it’ll ask for a message and I’ll say “your incident is done.” Click OK – the preview pulls my phone number because I’m the customer on this incident and it’s the message that I supplied. I’ll hit “OK.”

Now, there’s also an additional feature of this particular One-Step in that this message will show up on the Journals tab, so you’ll notice here’s the phone number and here’s the details that I sent that I specified in that prompt.

So that’s basically how the mApp works; let’s get into how to install it.

For installation, we have three different kinds of pre-configured ways to install this mApp. We have one that we’ve called “Core”, which is just that first One-Step that I showed: just the ability to send a SMS message through your Twilio account to a recipient phone number that you specify and an SMS message text that you specify. This makes it very extensible so you can build on top of it for whatever you want to do. The second part is that plus the integration with Incident that was the second One Step I showed. Finally, we have a fully customizable installer so you can run this little program, choose your connection (I’ll choose demo two and login), and in just a minute it’ll show me a list of all the major business objects in the system so you can choose whatever business object you want to associate this One-Step with. I’ll choose “Incident”.

If I just choose incident it’s basically like the “Core+Incident” version of the mApp but let’s also choose a “Configuration Item.” We recommend that with Group Business Objects you add this to the Group Leader and not the Group Members. If you run the One-Step from the Group Members it will still do the right thing, but then you don’t have multiple copies of essentially the same One-Step floating around with with different business objects that are all related.

I’ll do Incident and Configuration Item. You do need to specify your Twilio API key and secret and your outbound phone number. These can all be found on your Twilio dashboard – you can see I signed up for just a Twilio trial account and I have the account CID, which is that first box, and the token, which is the second box, and my trial number. If you’ve paid for a Twilio account you can have many numbers – pick the one that you want your Cherwell instance to be sending text messages from.

Basically I’ll copy this this first value into that first box. I’m not actually going to copy my real API secret so I’ll just put some garbage there and then I’ll copy this trial number. The plus at the beginning is okay here but any other punctuation in phone numbers shouldn’t be present for this particular field. There is some logic in place so that if there are dashes or periods in the phone numbers on your customer records those get stripped out before it gets sent to Twilio, just so Twilio properly handles the phone number.

Then we’ll click install. It’ll give me an option to save the blueprint – in this case I don’t really want to, I just want to apply it so I’ll say no.

Do you want to apply the blueprint to the system now? I’ll say “yes.”

In just a second it will have installed and it’ll tell me the installation is completed. Then I can close this window.

Now, if I go into my administrator client and pull up the “Demo 2” database you can see it’s made some changes so I need to refresh the catalog. Thankfully, it’s on my local machine so this won’t take too long. We’ll go ahead and create a new blueprint, pop into managers and the One-Step manager, and now we can see on Incident in the Blueprint scope we have “Send text message to current customer.”

Similarly, if we went to Configuration Item we would also see that “send text message to current customer.” It’s essentially the same One-Step – obviously same name in different scopes so it’s actually a different One-Step – but it’s updated with all the information for Configuration Item versus Incident.

Finally, if we go to “Association: None” we’ll see in the “Synapse Software / Twilio” folder, the “Send text message” One-Step. Both of the Incident and Configuration Item One-Steps actually leverage this one “send text message” One-Step, which makes it really easy to handle all of the configuration that goes into actually communicating with the Twilio API.

That’s basically how to install the mApp. Now let’s get into some details.

One key detail is that if you install the mApp using the “.mAppz” files, you do need to make a few updates in four different places – three different values in four different places:

1. The first one is in Web Services and this is basically how we communicate with Twilio. So let me go ahead and edit that. Under accounts you do need to specify the user ID and password. In Twilio’s case they actually made it pretty easy: for user ID you enter your Twilio account CID and, if you remember the value from before, you might recognize that the password is the Twilio auth token. So that’s two things to to update.
2. Finally the other two things that you’ll need to update are some stored values. They are also in the blueprint scope in the “Synapse Software / Twilio” folder and they are “outbound phone number” and “Twilio account CID.” Twilio account CID is the exact same Twilio account CID as was used for the user ID for the web service account. That’s this value right here.
3. Then the outbound phone number is the phone number that the mApp will use when sending SMS messages. You’ll notice this is the phone number that I pasted into that third box on the install screen. You’ll notice I don’t actually have to update that here on this database because I did use the installer. If you use the installer and enter those three values on the install screen, it automatically populates the two stored values and correctly updates the web service account, so we really recommend you use the custom installer because it does everything for you.

Finally, how you can leverage the mApp and kind of build on top of it:

Let’s dive into One-Steps and I’m going to pull up Incident. I want to go to Blueprint scope, and let’s go to “send text message to current customer.” Let’s go ahead and edit that, see what’s going on here.

Basically what we’re doing is we pull the mobile number from the the customer record and – one note on that: we’ll pull up this Incident that I had and open up my customer record and the secondary phone number is actually stored in the mobile field on the customer business object; however, we don’t assume that’s a mobile number because this label is secondary phone, so if you want this number to be used as the mobile number make sure that this type is set as mobile. If you don’t have a mobile number set for a customer you’ll get a little pop-up that says “No mobile number is set for the customer. Please make sure there’s a mobile number on the customer record before you try this again.” Something along those lines – I forget exactly what what the message is, but it’s something like that.

Jumping back into the One-Step: basically what happens there is it stores the mobile number in a Stored Value. There are a few Stored Values that are leveraged as part of this One-Step that kind of facilitate communication between these BO-specific One-Steps and the more general One-Step that actually does the sending of the text message.

You can see we run that one step here in this “call send text message” action. The first Stored Value to be aware of is “current recipient phone number.” This is where we store the the recipient phone number that we’ve pulled from the the business object record. If a recipient phone number doesn’t exist then you actually get prompted for it as if you’re just running the “send text message” one-step. In this case you can see we have a “decide between multiple cases” and if you don’t have a phone number specified you’ll get this message which is the message I mentioned before: “the customer does not have a mobile number specified. In order to send a text message please set a mobile number on the customer’s record.”

Then the next one to be aware of is “caller cleans up.” Basically this facilitates this “create journal SMS record” step so the “send text message” one step that is unassociated will clean up after itself unless this stored value is set to true. Basically this says “don’t don’t clean up after yourself; I will take care of it because I want to do additional stuff with the information.” So you’ll notice we don’t actually create the journal record until after we’ve sent the text message.

And finally the last one to be aware of isn’t actually used here, but if we pull up Stored Values we’ll see it.

We talked about “caller cleans up”, we talked about “current recipient phone number” (that’s where the the phone number gets stored like if it gets pulled from the mobile number on the business object), we do have a flag to allow editing of the current message before send (this is kind of like the the check mark or the check box in a one-step email step to allow editing of the email before it gets sent) so that’s kind of cool. We talked about those two – those are kind of more background system level ones but then finally “current message text” – basically you saw that prompt where I entered the text message that I wanted to send but there is a stored value where if that stored value is set it will automatically use that text for the text message instead of prompting me for it so it allows a lot of flexibility here and I think a lot of possibilities to build on top of it.

That’s basically it. That’s the meat and potatoes of it.

If you like what you see here, give us a ring or send us an email. You can purchase this mApp from our website and find more information about it in the description below.

Thanks for watching!