Some requests sent to the Verizon ThingSpace Platform might take some time to process. Instead of blocking your application during that time, the ThingSpace Platform sends back an immediate (synchronous) acknowledgement that it has received and accepted the request, and it will send a complete response as a callback message when it has finished processing the request. In order to receive callback messages, you must set up some kind of listening service on your server, and then register it with the ThingSpace Platform so that it knows where to send the responses.
This tutorial provides step-by-step instructions for deploying a callback listening service on SmartBear's SoapUI 4.5.1 and registering the services with the Verizon ThingSpace Platform.
The steps in this procedure assume that you have:
Firewalls are designed to block unwanted traffic coming from the Internet to an inside host. To make use of the callback feature described in this document, you must configure any firewalls between your computer and Verizon's ThingSpace Platform servers to allow the appropriate connections. (This is known as "white-listing.")
You (or someone at your company) should have received the list of IP addresses used by the Verizon M2M servers when your company was approved for API access to the ThingSpace Platform.
In addition to the main corporate firewall at your company, there may be internal firewalls, and your PC may have a firewall. All of these must be set to allow incoming traffic from Verizon for the specific port number on which you choose to set up your callback service.
Security Precaution
The "hole" in your PC firewall may compromise the security of your PC. You should reinstate the firewall when the open port is no longer required.
To replicate the configuration used in this tutorial, make the following settings in the SoapUI application:
Go to File > Preferences > Editor Setting and enable "Defaults the Request editor to the tabbed layout".
From within SoapUI, load the Callback Service wsdl.
Accept all defaults by clicking OK.
Click OK.
Your callback service must acknowledge receiving each callback message, or the ThingSpace Platform will resend the message and eventually mark the callback as failed. An acknowledgement sends the request ID back to the service.
Paste in this script:
// create XmlHolder for request content
def holder = new com.eviware.soapui.support.XmlHolder(mockRequest.requestContent)
// define the namespace used in request elements
holder.namespaces["ns"] = "http://nphase.com/unifiedwebservice/v2"
def reqId = holder.getNodeValue("//ns:RequestId")
requestContext.requestid = reqId
In the CallbackListeningService MockService window, click the green arrow icon to start the service.
You should see a remark at the top of the window stating that the service is running on port 50559 (or whatever port you chose).
To check the service locally:
Verify that you see the XML file.
If the MockService is not running, you will receive an error message.
Before registering the callback listening service that you created using this tutorial, you must first check to ensure that no services are currently registered with the ThingSpace Platform.
Run the GetCallbackRegistrationService API in your SoapUI tool to request all callback registrations currently active for your account from the server.
If a service is registered, unregister it using the Unregister Callback API.
After you have ensured that no other services are registered, you must register your callback listening service. You can register a service without credentials, or you can add another layer of security with one-way authentication. Both methods are explained in this section.
NOTE: The Verizon ThingSpace Platform supports multiple callback services, which require separate registration. Refer to the Callback Registration Service page for a comprehensive list of callback services included in the ThingSpace Platform.
To register a callback listening service without credentials:
Find your IP address and register the callback listening service URL using the following address (replace your_ip:your_port_number with your information):
http://your_ip:your_port_number/mockCallbackService?wsdl
NOTE: Allowed port numbers for new callback registrations are 80, 443, 9001-9006 and 50551-50559.
Leave the username and password fields blank.
Use the GetCallbackRegistrationService API to check that the new URL is listed.
To use one-way authentication, register your callback listening service as explained above, plus supply username and password:
When you register a callback listening service with credentials, every callback carries the credentials in the XML data.
Click the green arrow icon to start the service.
Issue an asynchronous command that will create a callback, such as using UpdateDeviceInformation to change a custom field.
Press Alt-F on your keyboard to format for XML.
When your Callback Listening Service is not responsive, you can use Wireshark® (http://www.wireshark.org) to verify that you are receiving traffic destined for your configured port. Look for the following:
If you are not seeing any traffic, then it is likely that your firewall is not open or you set the incorrect IP or port number during callback registration (Register the Callback Listening Service).
