This section of the document provides detailed specifications describing all supported message transmissions that the Resp Org Change (ROC) Notification Subscriber Web Service can receive from the ROC System and all responses it can generate. Using this specification, the Resp Orgs can create a Web Service for receiving such messages.
Definition of ROC Notification Subscriber Web Service
The ROC Notification Subscriber Web Service is an Extensible Markup Language (XML) based application which transports ROC status updates related data between the Resp Org applications and the ROC System. A Resp Org can create the Web Service as per the specifications and publish it. This Web Service will receive update notifications in the form of a SOAP message, via the Internet and will need to send an acknowledgement back of a successful receipt.
Resp Orgs will be able to receive notification updates via their published Web Service only after getting registered with Somos. Upon successful registration, the Resp Orgs will receive a Registration Code, which will be sent in all notification updates received by the Web Service.
Connectivity & Transmission Security
To secure the integrity of the data being transferred between the ROC System and the ROC Notification Subscriber Web Service, the Web Service must be published and configured to use the Secure Socket Layer (SSL) protocol (often referred to as HTTPs) and Transport Layer Security (TLS 1.2 or above). Standard port used by Somos is 443 to encrypt the messages. Please Note: If you request to communicate using a port other than 443, the time it takes to establish the Notification Subscriber for the ROC WSI can take longer. Somos recommends using port 443 for a faster turnaround time.
For more information regarding the ROC System Web Service URLs, please click here.
Simple Object Access Protocol (SOAP) specifications
The XML syntax for expressing a SOAP message is based on the soap-envelope namespace (http://www.w3.org/TR/2000/NOTE-SOAP-20000508/). This XML namespace identifier points to an XML Schema that defines the structure of what a SOAP message looks like.
Extensible Markup Language (XML) specifications
The ROC Web Service currently uses Extensible Markup Language (XML) version 1.1 as defined by the W3C (http://www.w3.org/standards/techs/xmlschema#).
Web Service Security Specifications
Each Resp Org must use validate the Registration Code sent in the messages before processing the notification update received.
Getting registered for using ROC Notification Subscriber Web Service
The Resp Orgs need to submit the following information for requesting authorization to use the ROC Notification Subscriber Web Service:
- URL of the Resp Org published Web Service
- Resp Org ID of the Resp Org
- Contact Email Address
- User Name (if secure published Web Service)
- Password (if Secure published Web Service)
After successful registration, the Resp Orgs will receive a registration code. The registration code will be used as a parameter for all requests. The registration code will be used to verify the request.
ROC Notification Subscriber Web Service - Operations Summary
The ROC Notification Subscriber Web Service must define the following public methods which the ROC System will use to send notification updates:
|
ROC Notification Subscriber Web Service – Methods |
||
|
S.No. |
Method Name |
Description |
|
1 |
NewIncomingChangeRequestNotification |
This operation will be called to notify the subscribed controlling (current) Resp Org when a new incoming ROC request is available.
If Resp Org Web Service Interface is not available, operation will be called again within an hour. No other retries will be made. An email will be sent to the registered email address informing the Resp Org of an issue with the published Web Service. |
|
2 |
ProcessedOutgoingChangeRequestNotification |
This operation will be called to notify the subscribed submitting (new) Resp Org when a change is processed to an outgoing ROC request. This operation can be called multiple times if a ROC request contains more than one Dial number since processing can occur in batches.
If Resp Org Web Service Interface is not available, operation will be called again within an hour. No other retries will be made. An email will be sent to the registered email address informing the Resp Org of an issue with the published Web Service. |
|
3 |
PushedToRespOrgs |
This operation is called to notify the subscribed submitting Resp Org when their submitted ROC request has been sent to all involved controlling Resp Orgs.
If Resp Org Web Service Interface is not available, operation will be called again within an hour. No other retries will be made. An email will be sent to the registered email address informing the Resp Org of an issue with the published Web Service. |
|
4 |
ProcessedIncomingChangeRequestNotification |
This operation will be called to notify the subscribed Resp Org when a change is processed to an incoming ROC request. This operation can be called multiple times if a ROC request contains more than one Dial number since processing can occur in batches.
If Resp Org Web Service Interface is not available, operation will be called again within an hour. No other retries will be made. An email will be sent to the registered email address informing the Resp Org of an issue with the published Web Service. |
|
5 |
ProcessedHelpDeskROCInterventionRequest |
This operation will be called to notify the subscribed Resp Orgs when a change is processed to a Resp Org Change Help Desk Intervention request.
If Resp Org Web Service Interface is not available, operation will be called again within an hour. No other retries will be made. An email will be sent to the registered email address informing the Resp Org of an issue with the published Web Service. |