Friday, 28 August 2015

Integrating Telstra Public SMS API into Bluemix

In the post below I will show how I integrated Telstra public SMS Api into my Bluemix catalog to be consumed as a service. This was all done from Public Bluemix using the Cloud Integration Service.

Step 1 - Create a T.DEV account

In order to get started you need to create an account on http://dev.telstra.com in order to be granted access to the SMS API. Once access is granted you need to create an application which enables you to add/manage Telstra API keys as shown below.

1.1 Create an account an http://dev.telstra.com

1.2. Once done you should have something as follows which can take up to 24 hours to get approved as shown by the "approved" icon


Step 2 - Test the SMS Telstra API

At this point we want to test the Telstra SMS API using a script, this ensures it's working before we proceed to Integrating it onto Bluemix.

2.1. Create a script called setup.sh as follows

#Obtain these keys from the Telstra Developer Portal
APP_KEY="yyyy-key"
APP_SECRET="yyyy-secret"

curl "https://api.telstra.com/v1/oauth/token?client_id=$APP_KEY&client_secret=$APP_SECRET&grant_type=client_credentials&scope=SMS"

2.2. Edit the script above to use your APP_KEY and APP_SECRET values from the Telstra Developer Portal

2.3. Run as shown below


pas@Pass-MBP:~/ibm/customers/telstra/telstra-apis/test$ ./setup.sh
{ "access_token": "xadMkPqSAE0VG6pSGEi6rHA5vqYi", "expires_in": "3599" }

2.4. Make a note of the token key returned, you will need this to send an SMS message
2.5. Create a script called "sendsms.sh" as shown below.


# * Recipient number should be in the format of "04xxxxxxxx" where x is a digit
# * Authorization header value should be in the format of "Bearer xxx" where xxx is access token returned
# from a previous GET https://api.telstra.com/v1/oauth/token request.
RECIPIENT_NUMBER=0411151350
TOKEN=token-key

curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "{\"to\":\"$RECIPIENT_NUMBER\", \"body\":\"Hello, pas sent this message from telstra SMS api!\"}" \
"https://api.telstra.com/v1/sms/messages"

2.6. Replace the token key with what was returned at step 2.4 above
2.7. Replace the RECIPIENT_NUMBER with your own mobile number to test the SMS API.
2.8. Run as shown below.


pas@Pass-MBP:~/ibm/customers/telstra/telstra-apis/test$ ./sendsms.sh
{"messageId":"1370CAB677B59C226705337B95945CD6"}

Step 3 - Creating a REST based service to Call Telstra SMS API

At this point we can now Integrate the Telstra SMS API into Bluemix. To do that I created a simple Spring Boot Application which exposes a RESTful method to call Telstra SMS API using Spring's RestTemplate class. I do this as it's two calls you need to make to call the Telstra SMS API. A REST based call to get a ACCESS_TOKEN , then followed by a call to actually send an SMS message. Creating a Spring Boot application to achieve this allows me to wrap that into one single call making it easy to consume and add to the Bluemix Catalog as a Service.

More Information on The Cloud Integration service can be found here. Cloud Integration allows us to expose RESTful methods from Bluemix applications onto the catalog via one simple screen. We could alos use Bluemix API management service as well.

https://www.ng.bluemix.net/docs/services/CloudIntegration/index.html

Below shows the application being pushed into Bluemix which will then be used to add Telstra SMS API service into the Bluemix catalog.



pas@192-168-1-4:~/ibm/DemoProjects/spring-starter/jazzhub/TelstraSMSAPIDemo$ cf push
Using manifest file /Users/pas/ibm/DemoProjects/spring-starter/jazzhub/TelstraSMSAPIDemo/manifest.yml

Creating app pas-telstrasmsapi in org pasapi@au1.ibm.com / space apple as pasapi@au1.ibm.com...
OK

Using route pas-telstrasmsapi.mybluemix.net
Binding pas-telstrasmsapi.mybluemix.net to pas-telstrasmsapi...
OK

Uploading pas-telstrasmsapi...
Uploading app files from: /Users/pas/ibm/DemoProjects/spring-starter/jazzhub/TelstraSMSAPIDemo/target/TelstraSMSAPI-1.0-SNAPSHOT.jar
Uploading 752.3K, 98 files
Done uploading
OK

Starting app pas-telstrasmsapi in org pasapi@au1.ibm.com / space apple as pasapi@au1.ibm.com...
-----> Downloaded app package (15M)
-----> Liberty Buildpack Version: v1.19.1-20150622-1509
-----> Retrieving IBM 1.8.0_20150617 JRE (ibm-java-jre-8.0-1.0-pxa6480sr1ifx-20150617_03-cloud.tgz) ... (0.0s)
         Expanding JRE to .java ... (1.4s)
-----> Retrieving App Management 1.5.0_20150608-1243 (app-mgmt_v1.5-20150608-1243.zip) ... (0.0s)
         Expanding App Management to .app-management (0.9s)
-----> Downloading Auto Reconfiguration 1.7.0_RELEASE from https://download.run.pivotal.io/auto-reconfiguration/auto-reconfiguration-1.7.0_RELEASE.jar (0.1s)
-----> Liberty buildpack is done creating the droplet

-----> Uploading droplet (90M)

0 of 1 instances running, 1 starting
0 of 1 instances running, 1 starting
0 of 1 instances running, 1 starting
0 of 1 instances running, 1 starting
1 of 1 instances running

App started


OK

App pas-telstrasmsapi was started using this command `$PWD/.java/jre/bin/java -Xtune:virtualized -Xmx384M -Xdump:none -Xdump:heap:defaults:file=./../dumps/heapdump.%Y%m%d.%H%M%S.%pid.%seq.phd -Xdump:java:defaults:file=./../dumps/javacore.%Y%m%d.%H%M%S.%pid.%seq.txt -Xdump:snap:defaults:file=./../dumps/Snap.%Y%m%d.%H%M%S.%pid.%seq.trc -Xdump:heap+java+snap:events=user -Xdump:tool:events=systhrow,filter=java/lang/OutOfMemoryError,request=serial+exclusive,exec=./.buildpack-diagnostics/killjava.sh $JVM_ARGS org.springframework.boot.loader.JarLauncher --server.port=$PORT`

Showing health and status for app pas-telstrasmsapi in org pasapi@au1.ibm.com / space apple as pasapi@au1.ibm.com...
OK

requested state: started
instances: 1/1
usage: 512M x 1 instances
urls: pas-telstrasmsapi.mybluemix.net
last uploaded: Fri Jul 17 11:26:58 UTC 2015

     state     since                    cpu    memory           disk           details
#0   running   2015-07-17 09:28:28 PM   1.0%   150.6M of 512M   148.9M of 1G

Step 4 - Add the RESTful method to IBM Bluemix catalog to invoke the Telstra SMS API

4.1 To expose our RESTful method we simply define the end point using the Cloud Integration service as shown below.


The image showing the Cloud Integration service with the Telstra API exposed and available to be consumed as a Service on Bluemix.





This was created using the Bluemix Dashboard but can also be done using the Cloud Foundry command line "cf create-service ..."

Step 5 - Create a Application client which will invoke the Telstra SMS service

At this point we are going to push a client application onto Bluemix which consumes the Telstra SMS API service and then uses it within the application. WE do this to verify the service works creating a simple HTML based application which invokes the service which has a manifest.yml file indicating it wants to consume the service which is now exposed on the catalog within Bluemix as per above.

5.1. The manifest.yml consumes the service created from the API in the catalog


applications:
- name: pas-telstrasmsapi-client
  memory: 512M
  instances: 1
  host: pas-telstrasmsapi-client
  domain: mybluemix.net
  path: ./target/TelstraSMSApiClient-0.0.1-SNAPSHOT.jar
  env:
   JBP_CONFIG_IBMJDK: "version: 1.8.+"
  services:
    - TelstraSMS-service

5.2. Push the application as shown below.


pas@Pass-MacBook-Pro:~/ibm/DemoProjects/spring-starter/jazzhub/TelstraSMSApiClient$ cf push
Using manifest file /Users/pas/ibm/DemoProjects/spring-starter/jazzhub/TelstraSMSApiClient/manifest.yml

Updating app pas-telstrasmsapi-client in org pasapi@au1.ibm.com / space apple as pasapi@au1.ibm.com...
OK

Using route pas-telstrasmsapi-client.mybluemix.net
Uploading pas-telstrasmsapi-client...
Uploading app files from: /Users/pas/ibm/DemoProjects/spring-starter/jazzhub/TelstraSMSApiClient/target/TelstraSMSApiClient-0.0.1-SNAPSHOT.jar
Uploading 806.8K, 121 files
Done uploading
OK
Binding service TelstraSMS-service to app pas-telstrasmsapi-client in org pasapi@au1.ibm.com / space apple as pasapi@au1.ibm.com...
OK

Stopping app pas-telstrasmsapi-client in org pasapi@au1.ibm.com / space apple as pasapi@au1.ibm.com...
OK

Starting app pas-telstrasmsapi-client in org pasapi@au1.ibm.com / space apple as pasapi@au1.ibm.com...
-----> Downloaded app package (16M)
-----> Downloaded app buildpack cache (1.2M)
-----> Liberty Buildpack Version: v1.19.1-20150622-1509
-----> Retrieving IBM 1.8.0_20150617 JRE (ibm-java-jre-8.0-1.0-pxa6480sr1ifx-20150617_03-cloud.tgz) ... (0.0s)
         Expanding JRE to .java ... (1.5s)
-----> Retrieving App Management 1.5.0_20150608-1243 (app-mgmt_v1.5-20150608-1243.zip) ... (0.0s)
         Expanding App Management to .app-management (0.9s)
-----> Downloading Auto Reconfiguration 1.7.0_RELEASE from https://download.run.pivotal.io/auto-reconfiguration/auto-reconfiguration-1.7.0_RELEASE.jar (0.0s)
-----> Liberty buildpack is done creating the droplet

-----> Uploading droplet (90M)

0 of 1 instances running, 1 starting
0 of 1 instances running, 1 starting
0 of 1 instances running, 1 starting
1 of 1 instances running

App started


OK

App pas-telstrasmsapi-client was started using this command `$PWD/.java/jre/bin/java -Xtune:virtualized -Xmx384M -Xdump:none -Xdump:heap:defaults:file=./../dumps/heapdump.%Y%m%d.%H%M%S.%pid.%seq.phd -Xdump:java:defaults:file=./../dumps/javacore.%Y%m%d.%H%M%S.%pid.%seq.txt -Xdump:snap:defaults:file=./../dumps/Snap.%Y%m%d.%H%M%S.%pid.%seq.trc -Xdump:heap+java+snap:events=user -Xdump:tool:events=systhrow,filter=java/lang/OutOfMemoryError,request=serial+exclusive,exec=./.buildpack-diagnostics/killjava.sh $JVM_ARGS org.springframework.boot.loader.JarLauncher --server.port=$PORT`

Showing health and status for app pas-telstrasmsapi-client in org pasapi@au1.ibm.com / space apple as pasapi@au1.ibm.com...
OK

requested state: started
instances: 1/1
usage: 512M x 1 instances
urls: pas-telstrasmsapi-client.mybluemix.net
last uploaded: Sun Jul 19 15:22:26 UTC 2015

     state     since                    cpu    memory           disk           details
#0   running   2015-07-19 11:23:57 PM   0.8%   144.9M of 512M   149.8M of 1G


Step 6 - Send SMS using Telstra SMS Api from Bluemix Application using the Service

6.1. Navigate to the URL below and send an SMS using the form below.

http://pas-telstrasmsapi-client.mybluemix.net/


6.2. Verify it has sent a message to the phone number entered in the text field as shown below.



More Information 

Getting started with Bluemix is easy, navigate to http://bluemix.net to sign up and get going.

1 comment:

Jeroen said...

Great tutorial Pas, thanks for writing this up !