Sending SMS Text Messages in PeopleSoft

In this post I will provide a step-by-step tutorial on how to send SMS text messages in PeopleSoft.  I will be consuming Nexmo’s SMS API to send SMS messages.  There are many SMS API services similar to Nexmo and there is no particular reason that I chose Nexmo over the other providers for this tutorial.  I have some experience with using other providers and the quality of service is comparable across the board. There will be four main steps in this tutorial: creating a Nexmo account, importing Nexmo SSL certificates, importing custom objects, and testing the service.

Creating a Nexmo Account

The first thing that you will need to do is to create a free account with Nexmo.  Navigate to their site and create a new account.

Picture1

Be sure to enter a valid phone number for the setup.  An SMS with a code will be sent to the mobile phone number that you enter.  Input the code that you received on the next screen to get access to your account.

Once you are logged in, navigate to the “Getting Started” tab and make note of your API key, API secret, and test number. Then Click on the “your numbers” link to obtain your sender ID.

Picture3

Make note of the sender ID that is assigned to your account. This will be the number that the SMS messages will come from.

Picture4

Importing Nexmo SSL Certificates

In this step you will need to download Nexmo’s SSL certificates and import them into the PeopleSoft PSKeyManager.  The primary URL that you will need to obtain the SSL certificates from is https://nexmo.com.  You will need to download the root and intermediate certificates from this URL.

Picture5

Then you will need to import the root and intermediate certificates into PSKeyManager.  The whole process of importing third-party SSL certificates into PeopleSoft is already nicely documented here by Niraj Patil, so I suggest following the steps in that post to import the certificates. Alternatively, you can click here to download a Word doc version with pictures.

Importing Custom Objects

I have created an app designer project that contains all of the necessary objects to invoke the SMS API web service via Integration Broker in PeopleSoft. Click here to download the app designer project.  After importing the project into app designer, you can login to the PIA to view the newly imported service operation that will be used for sending SMS messages.  The service operation is located at PeopleTools->Integration Broker->Integration Setup->Service Operations. The service operation is named “SENDSMS_GET”. You can click on the “View Message” link to see the document template that will get populated when invoking the service.

Picture6

The document consists of the elements that correlate to the information that you obtained in the first step of this tutorial.

Picture7

Testing the Service

Before attempting to execute the web service via PeopleCode, it would be a good idea to test the service using the built in Service Opertaion Tester utility in the PIA first.  To do this, you will need to navigate to PeopleTools->Integration Broker->Service Utilities->Service Operation Tester.  Search for the “SENDSMS_GET” service operation. After you select the service operation, you will need to click the “Populate Document Template” link to input your Nexmo account details.

Picture9

Input  your Nexmo account information by clicking on the corresponding element name for each piece of data and typing in the value.  The “text” field is the body of the SMS message, so you can put anything for this value.

Picture10

After clicking the return button, you will be taken back the previous screen.  Now you will need to click the “Invoke Operation” button to fire the Integration Broker message to send an SMS.

Picture11

If the service operation is not working, then you will receive a popup error at this point.  If the service operation is working, then you should receive an SMS message on the number that you inputted in the “to” field.  The JSON response from Nexmo should also appear on the screen at this point.

If you are able to successfully invoke the service operation using the testing utility, then you can now confidently invoke the service operation using PeopleCode.  Here is some code that you can use to send SMS messages from PeopleCode.  I have also attached a copy of this code as a text file in the app designer project linked above.

Picture12

I would recommend extending this sample code to be more robust by reading in the Nexmo account details from a setup table in the database.  It would also be a good idea to parse the response message and implement some sort of error handling.  Putting this code in a function or app class method that accepts phone number and message body parameters will make it easy to integrate anywhere in your application.


Sending SMS text messages from PeopleSoft using Nexmo’s SMS API is really simple after you perform this initial setup.  My main use case for sending SMS messages from PeopleSoft is to send TOTPs to user’s cell phones for two-factor authentication. However, I believe there are many other ways that this functionality can be leveraged in PeopleSoft to enhance the application.

31 thoughts on “Sending SMS Text Messages in PeopleSoft

  1. Ken Kaspersen says:

    Wow, this a nicely organized set of great articles. I’ll be back to check more of them out. Thanks for publishing these!

    Ken

  2. Ganesh Aithandal Muralidhar says:

    How do you integrate this notification framework. ? Notification framework already has templates, we just need to add the integration code and delivered notification SMS will sent.
    Can you let us know the steps to integrate with notification framework.

    • Colton Fischer says:

      I unfortunately do not have any experience with the notifications framework in PeopleSoft. It is on my list to research because it would be nice to have it configured to send SMS text messages. I will be sure to post something here if I determine how to setup the notifications framework for SMS messaging.

  3. Rajesh says:

    Hi Colton,
    I am getting below error while configuring the mobile message for 2 factor authentication. handler tester worked correctly. when i am providing option as cell phone , then code is triggering the service operation with error. “Integration Gateway – External System Contact Error- Integration Gateway was not able to contact the external system. The network location specified may be incorrect, or the site is permanently or temporarily down”

    Can you please help me if you are aware of this issue.any help is appreciated.

    Thanks,
    Rajesh

    • Colton Fischer says:

      I have never come across the issue of the code not working after the service tested successfully with the service operation tester. The error that you are getting is a generic one that could be caused by many different things. I would first like to better understand how you are using this solution.

      In this post, I did not provide any solution/guidance on how to incorporate Nexmo’s SMS API into a two-factor authentication solution. So I am a little unsure when you say “I am providing option as cell phone”. It sounds like you have incorporated the code samples from this post into a two-factor authentication solution that sends TOTPs via SMS. Is this correct? What have been your experiences with firing the code provided in this post in a standalone manner? Meaning, do you get the same error when you place this code behind a push button on a simple (non-2FA) page?

      I am glad that you are making use of this code and would really like to help you get this working. Please provide me some more details by answering the questions above and hopefully we can get this working.

      • Rajesh Reddy Eaga says:

        Hi Colton , yes i am getting this issue in the standalone while implementing in two factor authentication. I have called the method under the button as

        &obj.SendcodetoMobile;

        now in the app package, i have written method as

        method sendcodetomobile()
        /Used the sample code of yours and tweaked it. I have provided the cell phone and code string hardcoded./
        end-method;

        I am bit confused of what i am missing in this?
        Thanks for all your help

        • Colton Fischer says:

          Sorry for the late reply. I am not sure if you have resolved the issue, but would it be possible for you to share the code that the send in failing on? particularly, I would like to see the SendcodetoMobile method. Thanks

  4. sree says:

    Hi Cotton,
    I am using this SMS functiionality for my requirement. I imported the certificates into PS Key manager.
    I am using Nexmo free credit. i imported the certificates u mentioned from nexmo website and intalled into PSkey Manager
    I am getting :”External System contact Error”
    what more is needed for the configuration ?
    Any help on this would be highly appreciated.

    Thanks
    Sree

    • Colton Fischer says:

      Hi Sree,

      In response to your first comment about the IP address:

      It has been a while since I have visited this solution, but if I recall correctly, the App Designer project that I provided has the Integration Broker “plumbing” to be able to communicate with Nexmo. The project should contain the IB service that has the endpoint URL to Nexmo. You should not need Nexmo’s IP address to get this to work.

      In response to this comment about the error you are getting:

      The “External System contact Error” is a generic error that can be caused by a number of things. If you look at the IB logs, you be able to determine the exact error code that is being thrown and this will allow us to go down the correct path to troubleshoot the issue. Let me know what the error code is and I will try to provide guidance to solve the issue.

      • Rajesh says:

        Hi Sree/ Colton
        I had the same issue. Please goto Integration broker configuration and encrypt the key store password. I have same , which is resolved after encrypting the password. this should work.let me know if it works.

  5. sree says:

    Hi Cotton,
    I followed the steps you mentioned.
    I am getting the below error while creating the node.
    Integration Gateway ID Connector ID Connector URL Message Text
    LOCAL
    HTTPTARGET
    https://rest.nexmo.com/sms/json
    Integration Gateway – External System Contact Error (158,10721)

  6. sree says:

    Hi Cotton,
    While testing with Invoke Operation too, I am getting similar error
    PFB

    Event Tester

    Drag to resize
    Message

    Integration Gateway – External System Contact Error (158,10721) IBTREE_WRK.IB_INVOKEOPER.FieldChange PCPC:5155 Statement:110

    Integration Gateway was not able to contact the external system. The network location specified may be incorrect, or the site is permanently or temporarily down.

    Thanks

  7. sree says:

    Hi Cotton/Rajesh,
    How you got the IP address from Nexmo ?
    Have you paid Nexmo or used freecredit
    ?
    Please share
    Thanks
    Sree

  8. sree says:

    Hi Rajesh/cotton,
    Pls share the primary URL u gave in the configuration with Nexmo. while creating nodes.Pls share asap.
    Any help is appreciated.

    Best Regards
    Sree

  9. sree says:

    Hi Rajesh ,
    Can you pls eloborate on the steps u followed to make the communication between PS ans nexmo a success.
    I await your response
    Thanks
    Sree

  10. sree says:

    Hi Cotton
    Any steps on how you created that app designer project?

    firrewall changes are neededto get commnication with nexmo

    i am able to successfully do it.

    Thanks
    Sree

    • Colton Fischer says:

      Hello Sree. Good to know that you solved your Nexmo communication issue. As for how did I create the app designer project, I assume you are referring to how I created the necessary objects needed to consume a REST web service from PeopleSoft? There are some different ways to consume 3rd party web services in PeopleSoft and this example uses document-based messaging with Integration Broker for the communication. To do this, I had to create the following in the PeopleSoft PIA:

      Documents
      Messages
      Service
      Service operation
      PeopleCode Program

      There are some really good examples on creating the necessary objects for REST web services in PeopleSoft. Here is one by Chris Malek and here is another by Jose Ponce. The only thing that you want to do differently is uncheck the “Is Provider” checkbox when you are creating the service since you are consuming a service and not providing one. Here are a couple of PeopleBook references that may be helpful as well:

      Managing Consumer REST Service Operations
      Using PeopleCode to Manage REST Service Operations

      Please let me know if you have any other questions.

  11. sree says:

    Cotton/Rajesh
    Thanks.
    Your blog is so helpful for using HTTPS client.
    I installed certificates in PSkeystore.
    uncommented integrationgateway.properties file
    Encrypted password.
    Firewall changes also done.
    After this able to communicate with nexmo
    Creted an external node an dgave nexmo URL created in our dash board in primary column
    Please contact nexmo support fo r IP address an dcertificates and all.
    They will provide the details.
    Rajesh,
    Please share me about pricing they provided.

    Thanks
    Sree

  12. Anonymous says:

    Hi
    I used your app designer project
    I am getting error like
    An object of class Compound failed to deserialize. (2,693) An error happened while trying to unpack the value of an object of the given class.
    Any suggestions plsshare

    Sree

    • Colton Fischer says:

      This project uses document-based messages, therefore it contains some document objects. The documents module is not available on older Tools releases (pre 8.53, I think). So this project will not work if you are on an older Tools version.

  13. Anonymous says:

    Hi Rajesh,
    Are you getting SMS to all phone numbers which you are mentining?

    after pricing

    Thanks
    Sree

  14. Prasanna says:

    Rajesh & Sree,
    Congrats for making this work…. do you mind sharing the step-step instruction for making this work for PeopleSoft HCM 9.2?
    Thanks for your help
    P{rasanna

Leave a Reply

Your email address will not be published.