This docker image allows for a microservice to run within your LAN (Local Area Network) to accept POST and GET requests. The POST needs a JSON (Java Script Object Notation) object in its body to sent the SMS and the GET needs a watermark id to query for logs. The logs confirm the status of the message, example “delivered”. Authentication to Vodacom Messaging is handled by the container.
The image (which builds to a container) is called carlpaton/vodacommessagingxml2sms and is available at https://store.docker.com/community/images/carlpaton/vodacommessagingxml2sms
The code running in the container is written in C# (C-Sharp) and is a Microsoft WEB API project running on .NET Core 2. The Massive value in using .NET Core is it will run on Linux which will appeal to corporates.
What is Vodacom Messaging XML2SMS?
Vodacom Messaging is an online mobile messaging and gateway provider, in a nutshell, their services provide mobile communication tools to send and receive messages in popular formats such as SMS (Short Message Service).
Although the world has moved on with instant messaging clients like WhatsApp and even E-mail (Electronic mail), in South Africa SMS is still hugely popular with corporates needing to communicate with their client base in a ubiquitous manner.
The XML2SMS product is a tool aimed at developers to integrate SMS capabilities into their applications, this can be used for a number of event driven messages such as access tokens or OTP (One Time Pin) for banking applications or real-time notifications of spend or activity. Every SMS Is tracked with status updates available of delivery for auditing purposes.
All my testing was done on Ubuntu Server version 17 running as a virtual machine hosted on my notebook which runs Windows 10. Ubuntu then hosted docker, the images and containers.
If you are un-familiar with Docker & its capabilities I suggest you go through my article “Docker -Containers – The future” before going any further, if you are already using docker and want to either publish your own containers or see a summary of how to use mine see “Building Docker Images”
If you are reading this and are still puzzling how to use my image perhaps this illustration will help clear things up for you.
Steps By Step
You can use docker for windows but for the purpose of this demo I have focused on Ubuntu Server in the configuration described above.
- Setup Docker on Linux, there are detailed steps here to setup your VM Player (Virtual Machine Player), the hosted Linux OS (Operating System)
- Create an [environmental properties file](https://github.com/charleyza/VodacommessagingXml2sms/blob/master/Docker/Hosted on store.docker.com/env_file_name.env), these will be injected into the container when it is created.
I called mine env_file_name.env, below are the environmental properties the container will need. You can also set these in appsettings.json – if you dont use the env file the container will look at appsettings.json instead.
This is the authentication the container will pass to Vodacom Messaging, you will need an account with them to send SMS.
This is the flag to set the response from the container, you can have JSON or XML
During development the container can mock the response from the SMS Gateway, set this flag to 1 for mocking or 0 to send the SMS Request to Vodacom Messaging. The implementation of this in the code is pretty crap, I think it would be better refactored to a factory pattern.
Editing the file on the server with nano
- Create your [shell script to pull the image & spin up the container](https://github.com/charleyza/VodacommessagingXml2sms/blob/master/Docker/Hosted on store.docker.com/xml2sms.cloud.docker.com.sh) (Remember to mark it executable with chmod +x)
Below is the content of my script:
--- This tells the script to run with bash
Execute the shell script above:
- Send a POST request with a JSON object to the container and note the response.
If you set MOCKMODE_ENVIRONMENT=1 then the container will not call Vodacom Messaging but rather mock the response. The below are example POST methods from postman.
Details on the postman configuration can be found here.
This shows the postman’s POST:
Note the key returned was 202, this will be used in the GET below.
- GET a HTTP request to the container with the watermark ID received in the POST above.
You can then query the containers logs with:
sudo docker logs xml2sms
All this code is open source and licenced MIT (Massachusetts Institute of Technology) so I encourage developers to fork the code and adapt to work for their environment. Some ideas I can think of would include
- HTTPS Traffic to the container from your applications
- Persist the requests / responses to a database (look at my ISmsLogger.cs)
- Authentication HASH per application
- Additional send options such as EMS (Extended Messaging Service), this already works on Vodacom Messaging and won’t take much effort to add to the container.