The Sentinel REM extension provides a RESTful HTTP provisioning API. It also provides many Configuration APIs for various Sentinel VoLTE application components.

Tip To use the Sentinel VoLTE Provisioning REST Web Interface and Machine API, you will need to configure a Rhino instance using the Rhino Element Manager (REM).
Tip The Sentinel SDK contains a Python script called sentinel-rest-example in the build/bin directory. It implements the examples discussed here and a few more.

This page covers

The API also includes the ability to invalidate cache entries in Sentinel VoLTE’s Sh Cache, as detailed in the Sh Cache REST API.

Accessing the Provisioning REST API

To access the Provisioning REST API:

1

Ensure the Sentinel REM extension is installed in REM.

2

Start REM.

3

Access the Sentinel Provisioning API at [http://localhost:8080/rem/sentinel/api] (replace localhost with some other hostname if REM is not being run locally).
Tip Access is restricted to users configured through REM using HTTP BASIC authorization. If you’re using a web browser, it will prompt you to enter a username and password the first time you access any part of the API.

Listing and browsing resources

You can list and browse resources through the Sentinel Provisioning API.

Listing resources

You can find a listing of all available resources at the top-level URL for the API (for example, [http://localhost:8080/rem/sentinel/api]).

The list can be in either:

  • HTML format (for viewing in a browser)

  • an APP Service Document (application/atomsvc+xml), that can be parsed by a scripted client.

Browsing resources

From the top-level API URL, you can browse into the available resources. Each resource in turn lists its own sub-resources. All of the sub-resources require a rhinoInstanceId query parameter. This should exactly match the name of a Rhino instance configured in REM (such as rhinoInstanceId=Local). Most of the sub-resources also require a selectionKey query parameter in the form of platformOperator:networkOperator:sessionType:planId:subscriptionId - such as selectionKey=OpenCloud::::

Example 1:

http://localhost:8080/rem/sentinel/api/featureexecutionscripts returns a sub-resource listing for feature execution scripts:

<feature>
  <name>FeatureExecutionScripts</name>
  <resources>
    <link title="Feature Execution Scripts" href="http://localhost:8080/rem/sentinel/api/featureexecutionscripts/scripts" rel="entries"/>
    <link title="Feature Execution Script Execution Point Associations" href="http://localhost:8080/rem/sentinel/api/featureexecutionscripts/executionpoints" rel="associations"/>
  </resources>
</feature>

Example 2:

Following the entries relation to the scripts resource, by adding the rhinoInstanceId and selectionKey parameters, http://localhost:8080/rem/sentinel/api/featureexecutionscripts/scripts?rhinoInstanceId=Local&selectionKey=OpenCloud

returns a paged listing of feature execution scripts configured in your local Rhino instance for platform operator OpenCloud:

<featureExecutionScripts next="http://localhost:8080/rem/sentinel/api/featureexecutionscripts/scripts?rhinoInstanceId=Local&selectionKey=OpenCloud::::&page=2">
  <featureExecutionScript>
    <name>default_DiameterAccess_NetworkPreCreditCheck</name>
    <resources>
      <link title="default_DiameterAccess_NetworkPreCreditCheck" href="http://localhost:8080/rem/sentinel/api/featureexecutionscripts/scripts/default_DiameterAccess_NetworkPreCreditCheck?rhinoInstanceId=Local&selectionKey=OpenCloud::::" rel="config"/>
    </resources>
  </featureExecutionScript>
  ...
  <featureExecutionScript>
    <name>default_Mediation_CreditAllocatedPostOcsCC</name>
    <resources>
      <link title="default_Mediation_CreditAllocatedPostOcsCC" href="http://localhost:8080/rem/sentinel/api/featureexecutionscripts/scripts/default_Mediation_CreditAllocatedPostOcsCC?rhinoInstanceId=Local&selectionKey=OpenCloud::::" rel="config"/>
    </resources>
  </featureExecutionScript>
</featureExecutionScripts>

  • The next and prev attributes contain the URLs for the next and previous pages of results.

  • The link entries contain the URLs for accessing the individual feature execution script resource entities.

Specifying content type

By default, the API accepts and returns application/xml, but also supports application/json. To request content in JSON format, simple set the http Accept request header to application/json.

For example:

{{wget --header='Accept: application/json' ...}}
for {{.../featureexecutionscripts/scripts/default_DirectAccess_SessionStart?rhinoInstanceId=Local&selectionKey=OpenCloud::::}}

returns a JSON object representing the requested feature execution script.

{"featureExecutionScript": {
  "name": "default_DirectAccess_SessionStart",
  "src": "featurescript OnSessionStart { if not currentNextStep.refuseDialog and not currentNextStep.relayDialog { run AcceptCamelVoiceV1V2V3 } }"
}}

Result codes and error responses

The Provisioning REST API returns the following Result codes and Error responses

Result codes

The API returns these codes

Result code

Description

200 OK

The request to list or retrieve a record was successful

201 Created

The record posted was successfully created

204 No Content

The update or delete operation was successful

400 Bad Request

Incorrectly configured request. Check the response body for specific error information

401 Unauthorized

The request was not authorized. Check that the username and password are correct in the request

404 Not Found

The requested resource could not be found. Check the response body for specific error information

406 Not Acceptable

The requested media type is not supported

500 Internal Server Error

An internal error occurred while processing the request. Check the response body for specific error information

Error responses

You can find more information for result codes 400, 404, and 500 in an error response entity in the response body, in the requested content type (XML or JSON). For example:

XML

<error>
    <type>...</type>
    <message>...</message>
</error>

JSON

{
    "type": "...",
    "message": "..."
}

Here are the possible responses:

Error type

Associated Result Code

Description

CollectionNotFound

404 Not Found

The collection/table/scope containing the requested entity could not be found

EntityNotFound

404 Not Found

The requested entity could not be found

EntityMissing

400 Bad Request

Post request did not contain an entity in the request body

EntityAlreadyExists

400 Bad Request

Post request attempted to create an entity that already exists

RequiredParameterMissing

400 Bad Request

A required query parameter was not provided

ParameterInvalid

400 Bad Request

One of the query parameters provided was invalid

RequestInconsistent

400 Bad Request

Put request attempted to update an entity with an id/name in the request body that didn’t match the id/name in the URL

ServerError

500 Internal Server Error

An internal error occurred while processing the request

PageNotFound

404 Not Found

The requested page of the paged resource listing could not be found

NotAcceptable

406 Not Acceptable

Requested media type is not supported (XML-only response, since media type could not be determined)

Provisioning MMTel subscriber data using the provisioning API

The HSS Data and Data Configuration REST API provides a RESTFul API allowing a users Supplementary Service data and IMS Operator Determined Barring data to be provisioned. The provisioned data is stored in two documents in the HSS, using Sh Transparent data.

The API defines Create, Read, Update and Delete (C,R,U,D) operations. It maps REST C,R,U,D operations into Diameter Sh operations that manipulate XML documents stored in the HSS. These documents are the:

  • MMTel-Services document, according to section 7 of 3GPP TS 29.364 Rel 12,

  • IMS-ODB-Information document, according to section 10 of 3GPP TS 29.364 Rel 12

The XML schema for both of these documents is available, see MMTel standard schema.

Overview of the API

Specific elements in the MMTel-Services document and IMS-ODB-Information documents (stored in the HSS, accessed via Diameter Sh) are mapped to "fields" in the returned document via this API. There is a default mapping, configured through the use of the volte-sentinel-mappings-config tool described in Populate XCAP server settings and MMTel service data.

The mappings added by this tool are documented:

A visual way to view the result of the mappings is to Load or view transparent data for an IMS public identity.

Users can modify the API server configuration in order to introduce additional XML schemas with their own Service Indication. The volte-sentinel-mappings-config tool uses a REST API to provide the default mappings/configuration. Note: in versions of Sentinel VoLTE prior to the 2.7.0.x series, only the MMTel-Services document was configured by default in the volte-sentinel-mappings-config tool.

The subscriber’s own Data when passed to and from the API is framed according to the form described in HssSubscriberData.

The framing is either JSON or XML. When reading from the API (e.g a Read operation), the framing is selected by use of the Accept header. It is either:

  • Accept: application/json - for JSON framed data, or

  • Accept: application/xml - for XML framed data

When writing to the API (e.g. a Create or Update operation) the framing is indicated to the API by use of the Content-Type header. It is either:

  • Content-Type: application/json - for JSON framed data, or

  • Content-Type: application/xml - for XML framed data

The details of the Create, Read, Update and Delete operations are described in the /hssdata/subscriberdata section.

The operations take several parameters:

  • The imsUserIdentity parameter is the IMS public identity that will be read during SIP Session processing, or accessed via the Ut interface.

  • The rhinoInstanceId parameter is the name/instance of the Rhino cluster that is being connected to (as defined in REM). This cluster stores settings that are used by the Provisioning API.

  • The selectionKey parameter - typically defines the Platform Operator Name used for the install of the form $PLATFORM_OPERATOR_NAME$::::

About Update

The Update operation requires that a whole document is provided by the API client. It is not a "delta" operation, whereby only certain attributes or elements are identified for update - the entire document needs to be included. If a partial document is provided to the Update operation, it is treated by the Server as though any elements not provided to the Update operation are set to:

  • xsi:nil="true" (for XML), or

  • null (for JSON)

A single API Update operation can modify one or more documents in the HSS via Diameter Sh. The HSS document to update is controlled by the serviceIndication in the client provided document.

Create Examples

The Create API takes the user’s IMPU from the provided document. It is the only API call that does not include the user’s IMPU in the query URI. It returns a Location header containing the URI for further accessing the user’s data. This location is the URI for the other operations, such as Read, Update and Delete.

The create operation operates on one IMPU at a time.

Data in a file instead of inline

In the create examples, the curl utility is used. Data is provided inline in these examples, such that they can be copy/pasted to a command-line.

This has the side effect of making the command look more complex, as it is now a "long string" entered as a single command.

The curl utility allows the data to be used for an HTTP operation to be specified in a file, rather than provided inline. So rather than using --data 'data-goes-here' portion of the commands, it’s recommended to use --data-binary "@/path/to/filename". The reason to use --data-binary is because when curl handles data using --data it will strip newlines …​ yet newlines can make documents (more) humanly readable!

Creating a users Transparent Data

In this example:

  • the imsUserIdentity is sip:+6505550201@example.com - it is specified in the request body

  • the HTTP Request Method is POST

  • the user does not have Sh Transparent data

  • the rhinoInstanceId is Local

  • the selectionKey is Metaswitch::::

  • the requested framing format is JSON

  • the username is username

  • the password is password

  • the server is located on localhost running on port 8080

This example creates two documents in the HSS from a single HTTP request. These are MMTel-Services, and IMS-ODB-Information documents.

Request Body with manual formatting for ease of viewing

 
{"identity":"sip:+6505550201@example.com",
 "fieldGroups":[
     {"serviceIndication":"MMTEL-Services",
         "fields":[
             {"name":"OIP Active:","value":"true"},
             {"name":"OIR Active:","value":"true"},
             {"name":"OIR Default Behaviour:","value":"presentation-not-restricted"},
             {"name":"TIR Default Behaviour:","value":"presentation-not-restricted"},
             {"name":"TIP Active:","value":"true"},
             {"name":"TIR Active:","value":"true"},
             {"name":"ICB Active:","value":"false"},
             {"name":"OCB Active:","value":"false"},
             {"name":"CW Active:","value":"false"},
             {"name":"CDIV Active:","value":"false"},
             {"name":"CDIV No Reply Timer:","value":"60"},
             {"name":"CDIV Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},
             {"name":"ICB Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},
             {"name":"OCB Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},
             {"name":"Flexible Alerting Group Type:","value":null},
             {"name":"Flexible Alerting Membership Type:","value":null},
             {"name":"Flexible Alerting Group Members:","value":null},
             {"name":"Flexible Alerting Pilot Number:","value":null},
             {"name":"Flexible Alerting Group Authorized:","value":null},
             {"name":"Flexible Alerting Authorized:","value":null},
             {"name":"Explicit Communication Transfer Authorized:","value":null},
             {"name":"Operator CDIV Authorized:","value":null},
             {"name":"Operator CDIV Rules:","value":null},
             {"name":"Operator CDIV Maximum Diversion Count:","value":null},
             {"name":"Operator CDIV No Reply Timer:","value":null}
         ]
     },
     {"serviceIndication":"IMS-ODB-Information",
         "fields":[
             {"name":"Outgoing barring condition:","value":null},
             {"name":"Incoming barring condition:","value":null},
             {"name":"Barring of roaming condition:","value":null},
             {"name":"Bar premium rate communications information:","value":null},
             {"name":"Bar premium rate calls information when roaming outside Hplmn country:","value":null},
             {"name":"Bar premium rate communications entertainment:","value":null},
             {"name":"Bar premium rate calls entertainment when roaming outside Hplmn country:","value":null},
             {"name":"Evaluate ruleset Type1:","value":null},
             {"name":"Evaluate ruleset Type2:","value":null},
             {"name":"Evaluate ruleset Type3:","value":null},
             {"name":"Evaluate ruleset Type4:","value":null},
             {"name":"Barring of supplementary services management:","value":null},
             {"name":"Diverted to address registration barring:","value":null},
             {"name":"Simple invocation of communication transfer barring:","value":null},
             {"name":"Multiple invocation of communication transfer barring:","value":null},
             {"name":"Invocation of chargeable communication transfer barring:","value":null}
         ]
     }
 ]
}

Request using Curl

 
curl -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -i \
     -X POST \
     -u "username:password" \
     --data '{"identity":"sip:+6505550201@example.com","fieldGroups":[{"serviceIndication":"MMTEL-Services","fields":[{"name":"OIP Active:","value":"true"},{"name":"OIR Active:","value":"true"},{"name":"OIR Default Behaviour:","value":"presentation-not-restricted"},{"name":"TIR Default Behaviour:","value":"presentation-not-restricted"},{"name":"TIP Active:","value":"true"},{"name":"TIR Active:","value":"true"},{"name":"ICB Active:","value":"false"},{"name":"OCB Active:","value":"false"},{"name":"CW Active:","value":"false"},{"name":"CDIV Active:","value":"false"},{"name":"CDIV No Reply Timer:","value":"60"},{"name":"CDIV Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},{"name":"ICB Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},{"name":"OCB Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},{"name":"Flexible Alerting Group Type:","value":null},{"name":"Flexible Alerting Membership Type:","value":null},{"name":"Flexible Alerting Group Members:","value":null},{"name":"Flexible Alerting Pilot Number:","value":null},{"name":"Flexible Alerting Group Authorized:","value":null},{"name":"Flexible Alerting Authorized:","value":null},{"name":"Explicit Communication Transfer Authorized:","value":null},{"name":"Operator CDIV Authorized:","value":null},{"name":"Operator CDIV Rules:","value":null},{"name":"Operator CDIV Maximum Diversion Count:","value":null},{"name":"Operator CDIV No Reply Timer:","value":null}]},{"serviceIndication":"IMS-ODB-Information","fields":[{"name":"Outgoing barring condition:","value":null},{"name":"Incoming barring condition:","value":null},{"name":"Barring of roaming condition:","value":null},{"name":"Bar premium rate communications information:","value":null},{"name":"Bar premium rate calls information when roaming outside Hplmn country:","value":null},{"name":"Bar premium rate communications entertainment:","value":null},{"name":"Bar premium rate calls entertainment when roaming outside Hplmn country:","value":null},{"name":"Evaluate ruleset Type1:","value":null},{"name":"Evaluate ruleset Type2:","value":null},{"name":"Evaluate ruleset Type3:","value":null},{"name":"Evaluate ruleset Type4:","value":null},{"name":"Barring of supplementary services management:","value":null},{"name":"Diverted to address registration barring:","value":null},{"name":"Simple invocation of communication transfer barring:","value":null},{"name":"Multiple invocation of communication transfer barring:","value":null},{"name":"Invocation of chargeable communication transfer barring:","value":null}]}]}' \
     "http://localhost:8080/rem/sentinel/api/hssdata/subscriberdata?rhinoInstanceId=Local&selectionKey=Metaswitch::::"

Response Headers

 
HTTP/1.1 100 Continue

HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=C4B52CB5E642165BDCB44DB8DDF595E6; Path=/rem/; HttpOnly
Location: http://54.206.118.127:8080/rem/sentinel/api/hssdata/subscriberdata/sip:+6505550201@example.com?rhinoInstanceId=Local&selectionKey=Metaswitch::::
Content-Length: 0
Date: Mon, 14 May 2018 02:24:36 GMT

Response Body

There is no response body

Note: when a field value contains an XML element, it is escaped as the value is defined as JSON string. As an example, any quote characters need to be escaped, newline characters are represented as \n.

Attempting to create a user that already has Transparent Data

This is the same as the previous example, but where the user already has Transparent data.

In this case the following response headers and body are observed.

Response headers

 
HTTP/1.1 100 Continue

HTTP/1.1 400 Bad Request
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: Mon, 14 May 2018 02:28:01 GMT
Connection: close

Response body

 
{"type":"EntityAlreadyExists","message":"Subscriber data already exists for IMS user identity \"sip:+6505550201@example.com\" and selection key \"Metaswitch::::\""}

Read examples

The read operation will request transparent data from the HSS for all the APIs configured Service-Indications. By default, these include MMTel-Services and IMS-ODB-Information.

Read example using JSON

In this example:

  • the imsUserIdentity is sip:+6505550201@example.com - it is specified in the URI

  • the HTTP Request Method is GET

  • the rhinoInstanceId is Local

  • the selectionKey is Metaswitch::::

  • the requested framing format is JSON

  • the username is username

  • the password is password

  • the server is located on localhost running on port 8080

Request

 
curl -H 'Accept: application/json' \
     -i \
     -X GET \
     -u "username:password" \
     "http://localhost:8080/rem/sentinel/api/hssdata/subscriberdata/sip:+6505550201@example.com?rhinoInstanceId=Local&selectionKey=Metaswitch::::"

Response Header

 
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: Thu, 10 May 2018 05:13:44 GMT

Response Body

 
{"identity":"sip:+6505550201@example.com","fieldGroups":[{"serviceIndication":"MMTEL-Services","fields":[{"name":"OIP Active:","value":"true"},{"name":"OIR Active:","value":"true"},{"name":"OIR Default Behaviour:","value":"presentation-not-restricted"},{"name":"TIR Default Behaviour:","value":"presentation-not-restricted"},{"name":"TIP Active:","value":"true"},{"name":"TIR Active:","value":"true"},{"name":"ICB Active:","value":"false"},{"name":"OCB Active:","value":"false"},{"name":"CW Active:","value":"false"},{"name":"CDIV Active:","value":"false"},{"name":"CDIV No Reply Timer:","value":"60"},{"name":"CDIV Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},{"name":"ICB Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},{"name":"OCB Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},{"name":"Flexible Alerting Group Type:","value":null},{"name":"Flexible Alerting Membership Type:","value":null},{"name":"Flexible Alerting Group Members:","value":null},{"name":"Flexible Alerting Pilot Number:","value":null},{"name":"Flexible Alerting Group Authorized:","value":null},{"name":"Flexible Alerting Authorized:","value":null},{"name":"Explicit Communication Transfer Authorized:","value":null},{"name":"Operator CDIV Authorized:","value":null},{"name":"Operator CDIV Rules:","value":null},{"name":"Operator CDIV Maximum Diversion Count:","value":null},{"name":"Operator CDIV No Reply Timer:","value":null}]},{"serviceIndication":"IMS-ODB-Information","fields":[{"name":"Outgoing barring condition:","value":null},{"name":"Incoming barring condition:","value":null},{"name":"Barring of roaming condition:","value":null},{"name":"Bar premium rate communications information:","value":null},{"name":"Bar premium rate calls information when roaming outside Hplmn country:","value":null},{"name":"Bar premium rate communications entertainment:","value":null},{"name":"Bar premium rate calls entertainment when roaming outside Hplmn country:","value":null},{"name":"Evaluate ruleset Type1:","value":null},{"name":"Evaluate ruleset Type2:","value":null},{"name":"Evaluate ruleset Type3:","value":null},{"name":"Evaluate ruleset Type4:","value":null},{"name":"Barring of supplementary services management:","value":null},{"name":"Diverted to address registration barring:","value":null},{"name":"Simple invocation of communication transfer barring:","value":null},{"name":"Multiple invocation of communication transfer barring:","value":null},{"name":"Invocation of chargeable communication transfer barring:","value":null}]}]}

Response Body with manual format editing for ease of viewing

 
{"identity":"sip:+6505550201@example.com",
 "fieldGroups":[
     {"serviceIndication":"MMTEL-Services",
         "fields":[
             {"name":"OIP Active:","value":"true"},
             {"name":"OIR Active:","value":"true"},
             {"name":"OIR Default Behaviour:","value":"presentation-not-restricted"},
             {"name":"TIR Default Behaviour:","value":"presentation-not-restricted"},
             {"name":"TIP Active:","value":"true"},
             {"name":"TIR Active:","value":"true"},
             {"name":"ICB Active:","value":"false"},
             {"name":"OCB Active:","value":"false"},
             {"name":"CW Active:","value":"false"},
             {"name":"CDIV Active:","value":"false"},
             {"name":"CDIV No Reply Timer:","value":"60"},
             {"name":"CDIV Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},
             {"name":"ICB Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},
             {"name":"OCB Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},
             {"name":"Flexible Alerting Group Type:","value":null},
             {"name":"Flexible Alerting Membership Type:","value":null},
             {"name":"Flexible Alerting Group Members:","value":null},
             {"name":"Flexible Alerting Pilot Number:","value":null},
             {"name":"Flexible Alerting Group Authorized:","value":null},
             {"name":"Flexible Alerting Authorized:","value":null},
             {"name":"Explicit Communication Transfer Authorized:","value":null},
             {"name":"Operator CDIV Authorized:","value":null},
             {"name":"Operator CDIV Rules:","value":null},
             {"name":"Operator CDIV Maximum Diversion Count:","value":null},
             {"name":"Operator CDIV No Reply Timer:","value":null}
         ]
     },
     {"serviceIndication":"IMS-ODB-Information",
         "fields":[
             {"name":"Outgoing barring condition:","value":null},
             {"name":"Incoming barring condition:","value":null},
             {"name":"Barring of roaming condition:","value":null},
             {"name":"Bar premium rate communications information:","value":null},
             {"name":"Bar premium rate calls information when roaming outside Hplmn country:","value":null},
             {"name":"Bar premium rate communications entertainment:","value":null},
             {"name":"Bar premium rate calls entertainment when roaming outside Hplmn country:","value":null},
             {"name":"Evaluate ruleset Type1:","value":null},
             {"name":"Evaluate ruleset Type2:","value":null},
             {"name":"Evaluate ruleset Type3:","value":null},
             {"name":"Evaluate ruleset Type4:","value":null},
             {"name":"Barring of supplementary services management:","value":null},
             {"name":"Diverted to address registration barring:","value":null},
             {"name":"Simple invocation of communication transfer barring:","value":null},
             {"name":"Multiple invocation of communication transfer barring:","value":null},
             {"name":"Invocation of chargeable communication transfer barring:","value":null}
         ]
     }
 ]
}

Note: when a field value contains an XML element, it is escaped as the value is defined as JSON string. As an example, any quote characters need to be escaped, newline characters are represented as \n.

Read for an IMPU with no Sh Transparent Data

In this example:

  • the imsUserIdentity is sip:+6505550201@example.com - it is specified in the URI

  • the HTTP Request Method is GET

  • the user does not have Sh Transparent data

  • the rhinoInstanceId is Local

  • the selectionKey is Metaswitch::::

  • the requested framing format is JSON

  • the username is username

  • the password is password

  • the server is located on localhost running on port 8080

Request

 
curl -H 'Accept: application/json' \
     -i \
     -X GET \
     -u "username:password" \
     "http://localhost:8080/rem/sentinel/api/hssdata/subscriberdata/sip:+6505550201@example.com?rhinoInstanceId=Local&selectionKey=Metaswitch::::"

Response Header

 
HTTP/1.1 404 Not Found
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: Mon, 14 May 2018 02:09:39 GMT

Response Body

 
{"type":"EntityNotFound","message":"Subscriber data could not be found for IMS user identity \"sip:+6505550201@example.com\" and selection key \"Metaswitch::::\""}

Read example using XML

In this example:

  • the imsUserIdentity is sip:+6505550201@example.com - it is specified in the URI

  • the HTTP Request Method is GET

  • the rhinoInstanceId is Local

  • the selectionKey is Metaswitch::::

  • the requested framing format is XML

  • the username is username

  • the password is password

  • the server is located on localhost running on port 8080

Request

 
curl -H 'Accept: application/xml' \
     -i \
     -X GET \
     -u "username:password" \
     "http://localhost:8080/rem/sentinel/api/hssdata/subscriberdata/sip:+6505550201@example.com?rhinoInstanceId=Local&selectionKey=Metaswitch::::"

Response Header

 
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/xml
Content-Length: 5943
Date: Thu, 10 May 2018 23:46:59 GMT

Response Body

 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><hssSubscriberData><identity>sip:+6505550201@example.com</identity><fieldGroups><fieldGroup><serviceIndication>MMTEL-Services</serviceIndication><fields><field><name>OIP Active:</name><value>true</value></field><field><name>OIR Active:</name><value>true</value></field><field><name>OIR Default Behaviour:</name><value>presentation-not-restricted</value></field><field><name>TIR Default Behaviour:</name><value>presentation-not-restricted</value></field><field><name>TIP Active:</name><value>true</value></field><field><name>TIR Active:</name><value>true</value></field><field><name>ICB Active:</name><value>false</value></field><field><name>OCB Active:</name><value>false</value></field><field><name>CW Active:</name><value>false</value></field><field><name>CDIV Active:</name><value>false</value></field><field><name>CDIV No Reply Timer:</name><value>60</value></field><field><name>CDIV Rules:</name><value>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; standalone=&quot;yes&quot;?&gt;
&lt;cp:ruleset xmlns=&quot;http://uri.etsi.org/ngn/params/xml/simservs/xcap&quot; xmlns:ocp=&quot;urn:oma:xml:xdm:common-policy&quot; xmlns:cp=&quot;urn:ietf:params:xml:ns:common-policy&quot;/&gt;
</value></field><field><name>ICB Rules:</name><value>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; standalone=&quot;yes&quot;?&gt;
&lt;cp:ruleset xmlns=&quot;http://uri.etsi.org/ngn/params/xml/simservs/xcap&quot; xmlns:ocp=&quot;urn:oma:xml:xdm:common-policy&quot; xmlns:cp=&quot;urn:ietf:params:xml:ns:common-policy&quot;/&gt;
</value></field><field><name>OCB Rules:</name><value>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; standalone=&quot;yes&quot;?&gt;
&lt;cp:ruleset xmlns=&quot;http://uri.etsi.org/ngn/params/xml/simservs/xcap&quot; xmlns:ocp=&quot;urn:oma:xml:xdm:common-policy&quot; xmlns:cp=&quot;urn:ietf:params:xml:ns:common-policy&quot;/&gt;
</value></field><field><name>Flexible Alerting Group Type:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Flexible Alerting Membership Type:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Flexible Alerting Group Members:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Flexible Alerting Pilot Number:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Flexible Alerting Group Authorized:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Flexible Alerting Authorized:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Explicit Communication Transfer Authorized:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Operator CDIV Authorized:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Operator CDIV Rules:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Operator CDIV Maximum Diversion Count:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Operator CDIV No Reply Timer:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field></fields></fieldGroup><fieldGroup><serviceIndication>IMS-ODB-Information</serviceIndication><fields><field><name>Outgoing barring condition:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Incoming barring condition:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Barring of roaming condition:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Bar premium rate communications information:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Bar premium rate calls information when roaming outside Hplmn country:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Bar premium rate communications entertainment:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Bar premium rate calls entertainment when roaming outside Hplmn country:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Evaluate ruleset Type1:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Evaluate ruleset Type2:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Evaluate ruleset Type3:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Evaluate ruleset Type4:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Barring of supplementary services management:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Diverted to address registration barring:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Simple invocation of communication transfer barring:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Multiple invocation of communication transfer barring:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field><field><name>Invocation of chargeable communication transfer barring:</name><value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/></field></fields></fieldGroup></fieldGroups></hssSubscriberData>

Response Body with manual format editing for ease of viewing

 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<hssSubscriberData>
    <identity>sip:+6505550201@example.com</identity>
    <fieldGroups>
        <fieldGroup>
        <serviceIndication>MMTEL-Services</serviceIndication>
            <fields>
                <field>
                    <name>OIP Active:</name>
                    <value>true</value>
                </field>
                <field>
                    <name>OIR Active:</name>
                    <value>true</value>
                </field>
                <field>
                    <name>OIR Default Behaviour:</name>
                    <value>presentation-not-restricted</value>
                </field>
                <field>
                    <name>TIR Default Behaviour:</name>
                    <value>presentation-not-restricted</value>
                </field>
                <field>
                    <name>TIP Active:</name>
                    <value>true</value>
                </field>
                <field>
                    <name>TIR Active:</name>
                    <value>true</value>
                </field>
                <field>
                    <name>ICB Active:</name>
                    <value>false</value>
                </field>
                <field>
                    <name>OCB Active:</name>
                    <value>false</value>
                </field>
                <field>
                    <name>CW Active:</name>
                    <value>false</value>
                </field>
                <field>
                    <name>CDIV Active:</name>
                    <value>false</value>
                </field>
                <field>
                    <name>CDIV No Reply Timer:</name>
                    <value>60</value>
                </field>
                <field>
                    <name>CDIV Rules:</name>
                    <value>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; standalone=&quot;yes&quot;?&gt:&lt;cp:ruleset xmlns=&quot;http://uri.etsi.org/ngn/params/xml/simservs/xcap&quot; xmlns:ocp=&quot;urn:oma:xml:xdm:common-policy&quot; xmlns:cp=&quot;urn:ietf:params:xml:ns:common-policy&quot;/&gt;</value>
                </field>
                <field>
                    <name>ICB Rules:</name>
                    <value>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; standalone=&quot;yes&quot;?&gt;&lt;cp:ruleset xmlns=&quot;http://uri.etsi.org/ngn/params/xml/simservs/xcap&quot; xmlns:ocp=&quot;urn:oma:xml:xdm:common-policy&quot; xmlns:cp=&quot;urn:ietf:params:xml:ns:common-policy&quot;/&gt;</value>
                </field>
                <field>
                    <name>OCB Rules:</name>
                    <value>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; standalone=&quot;yes&quot;?&gt;&lt;cp:ruleset xmlns=&quot;http://uri.etsi.org/ngn/params/xml/simservs/xcap&quot; xmlns:ocp=&quot;urn:oma:xml:xdm:common-policy&quot; xmlns:cp=&quot;urn:ietf:params:xml:ns:common-policy&quot;/&gt;</value>
                </field>
                <field>
                     <name>Flexible Alerting Group Type:</name>
                     <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/><
                </field>
                <field>
                    <name>Flexible Alerting Membership Type:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Flexible Alerting Group Members:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Flexible Alerting Pilot Number:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Flexible Alerting Group Authorized:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Flexible Alerting Authorized:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Explicit Communication Transfer Authorized:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Operator CDIV Authorized:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Operator CDIV Rules:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Operator CDIV Maximum Diversion Count:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Operator CDIV No Reply Timer:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
            </fields>
        </fieldGroup>
        <fieldGroup>
        <serviceIndication>IMS-ODB-Information</serviceIndication>
            <fields>
                <field>
                    <name>Outgoing barring condition:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Incoming barring condition:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Barring of roaming condition:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Bar premium rate communications information:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Bar premium rate calls information when roaming outside Hplmn country:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Bar premium rate communications entertainment:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Bar premium rate calls entertainment when roaming outside Hplmn country:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Evaluate ruleset Type1:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Evaluate ruleset Type2:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Evaluate ruleset Type3:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Evaluate ruleset Type4:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                   <name>Barring of supplementary services management:</name>
                   <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Diverted to address registration barring:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Simple invocation of communication transfer barring:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Multiple invocation of communication transfer barring:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
                <field>
                    <name>Invocation of chargeable communication transfer barring:</name>
                    <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                </field>
            </fields>
        </fieldGroup>
    </fieldGroups>
</hssSubscriberData>

Note: When an XML element from the HSS is returned inside a "value" XML element, the API has to encode the HSS’s XML element as type xs:string. This means that elements such as the following occur.

<field>
    <name>OCB Rules:</name>
    <value>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; standalone=&quot;yes&quot;?&gt;&lt;cp:ruleset xmlns=&quot;http://uri.etsi.org/ngn/params/xml/simservs/xcap&quot; xmlns:ocp=&quot;urn:oma:xml:xdm:common-policy&quot; xmlns:cp=&quot;urn:ietf:params:xml:ns:common-policy&quot;/&gt;</value>
</field>

Update examples

Note: the examples here provide data in-line. It may be preferable to have data provided via a file. See Data in a file instead of inline.

Update of IMS ODB Information using JSON

In this example, a users IMS ODB Information is set to bar outgoing calls to international destinations, excluding the home country.

This example sets:

  • the Service Indication to "IMS-ODB-Information" - (serviceIndication in the document)

  • a value of "2" in the OutgoingBarring element in the OdbForImsOrientedServices document - an example of an XML document over the Sh interface is provided Bar all outgoing communications when international ex-hplmnc

  • all other portions of the document are also provided - in this case they are explicitly set to null.

Request Body with manual formatting for ease of viewing

 
{"identity":"sip:+6505550201@example.com",
 "fieldGroups":[
     {"serviceIndication":"IMS-ODB-Information",
     "fields":[
         {"name":"Outgoing barring condition:","value":"2"},
         {"name":"Incoming barring condition:","value":null},
         {"name":"Barring of roaming condition:","value":null},
         {"name":"Bar premium rate communications information:","value":null},
         {"name":"Bar premium rate calls information when roaming outside Hplmn country:","value":null},
         {"name":"Bar premium rate communications entertainment:","value":null},
         {"name":"Bar premium rate calls entertainment when roaming outside Hplmn country:","value":null},
         {"name":"Evaluate ruleset Type1:","value":null},
         {"name":"Evaluate ruleset Type2:","value":null},
         {"name":"Evaluate ruleset Type3:","value":null},
         {"name":"Evaluate ruleset Type4:","value":null},
         {"name":"Barring of supplementary services management:","value":null},
         {"name":"Diverted to address registration barring:","value":null},
         {"name":"Simple invocation of communication transfer barring:","value":null},
         {"name":"Multiple invocation of communication transfer barring:","value":null},
         {"name":"Invocation of chargeable communication transfer barring:","value":null}
     ]
     }
 ]
}

Request using Curl

 
curl -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -i \
     -X PUT \
     -u "username:password" \
     --data '{"identity":"sip:+6505550201@example.com","fieldGroups":[{"serviceIndication":"IMS-ODB-Information","fields":[{"name":"Outgoing barring condition:","value":"2"},{"name":"Incoming barring condition:","value":null},{"name":"Barring of roaming condition:","value":null},{"name":"Bar premium rate communications information:","value":null},{"name":"Bar premium rate calls information when roaming outside Hplmn country:","value":null},{"name":"Bar premium rate communications entertainment:","value":null},{"name":"Bar premium rate calls entertainment when roaming outside Hplmn country:","value":null},{"name":"Evaluate ruleset Type1:","value":null},{"name":"Evaluate ruleset Type2:","value":null},{"name":"Evaluate ruleset Type3:","value":null},{"name":"Evaluate ruleset Type4:","value":null},{"name":"Barring of supplementary services management:","value":null},{"name":"Diverted to address registration barring:","value":null},{"name":"Simple invocation of communication transfer barring:","value":null},{"name":"Multiple invocation of communication transfer barring:","value":null},{"name":"Invocation of chargeable communication transfer barring:","value":null}]}]}' \
     "http://localhost:8080/rem/sentinel/api/hssdata/subscriberdata/sip:+6505550201@example.com?rhinoInstanceId=Local&selectionKey=Metaswitch::::"

Response Header

 
HTTP/1.1 100 Continue

HTTP/1.1 204 No Content
Server: Apache-Coyote/1.1
Date: Sun, 13 May 2018 21:53:43 GMT

Response Body

 
There is no response body

Update of CDIV rules using JSON

In this example, a users CDIV rules are set to the Unconditional rule, to always retarget to a specific number. The users CDIV Active flag is set to true so that diversion can occur.

Note that CDIV Rules are able to be modified by an end user. Therefore a workflow implemented in a provisioning system is expected to:

  • Read the existing document using the Read operation, and parse into an in-memory form

  • modify this in-memory document add the specific rule (into the existing set of rules),

  • Update the document using the Update operation

A read for a user with no CDIV rules set will return a document. A trimmed version of that document is show below, including the two relevant fields:

  1. CDIV Active

  2. CDIV Rules

{"identity":"sip:+6505550201@example.com",
 "fieldGroups":[
     {"serviceIndication":"MMTEL-Services",
         "fields":[

 .. trimmed some output of Read  ..

             {"name":"CDIV Active:","value":"false"},

             {"name":"CDIV Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},

.. trimmed some output of Read  ..
         ]
     },
 .. trimmed some output of Read ..
 ]
}

The existing value of CDIV Active is "false". In order for CDIV to divert the call, the new value shall be "true".

The existing value of CDIV Rules - after removal of JSON escaping is:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:ocp="urn:oma:xml:xdm:common-policy" xmlns:cp="urn:ietf:params:xml:ns:common-policy"/>

The desired value for this element according to the MMTel Services document schema is:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:ruleset xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:ocp="urn:oma:xml:xdm:common-policy" xmlns:cp="urn:ietf:params:xml:ns:common-policy">
    <cp:rule id="unconditional">
        <cp:conditions>
        </cp:conditions>
        <cp:actions>
            <forward-to>
                <target>sip:+6505550202@example.com</target>
                <notify-caller>true</notify-caller>
            </forward-to>
        </cp:actions>
    </cp:rule>
</cp:ruleset>

The JSON string form of the XML document above (preserving whitespace) is:

"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\">\n    <cp:rule id=\"unconditional\">\n        <cp:conditions>\n        </cp:conditions>\n        <cp:actions>\n            <forward-to>\n                <target>sip:6505550202@example.com</target>\n                <notify-caller>true</notify-caller>\n            </forward-to>\n        </cp:actions>\n    </cp:rule>\n</cp:ruleset>\n"

Request Body with manual formatting for ease of viewing

 
{"identity":"sip:+6505550201@example.com",
 "fieldGroups":[
     {"serviceIndication":"MMTEL-Services",
         "fields":[
             {"name":"OIP Active:","value":"true"},
             {"name":"OIR Active:","value":"true"},
             {"name":"OIR Default Behaviour:","value":"presentation-not-restricted"},
             {"name":"TIR Default Behaviour:","value":"presentation-not-restricted"},
             {"name":"TIP Active:","value":"true"},
             {"name":"TIR Active:","value":"true"},
             {"name":"ICB Active:","value":"false"},
             {"name":"OCB Active:","value":"false"},
             {"name":"CW Active:","value":"false"},
             {"name":"CDIV Active:","value":"true"},
             {"name":"CDIV No Reply Timer:","value":"60"},
             {"name":"CDIV Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\">\n    <cp:rule id=\"unconditional\">\n        <cp:conditions>\n        </cp:conditions>\n        <cp:actions>\n            <forward-to>\n                <target>sip:+6505550202@example.com</target>\n                <notify-caller>true</notify-caller>\n            </forward-to>\n        </cp:actions>\n    </cp:rule>\n</cp:ruleset>\n"},
             {"name":"ICB Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},
             {"name":"OCB Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},
             {"name":"Flexible Alerting Group Type:","value":null},
             {"name":"Flexible Alerting Membership Type:","value":null},
             {"name":"Flexible Alerting Group Members:","value":null},
             {"name":"Flexible Alerting Pilot Number:","value":null},
             {"name":"Flexible Alerting Group Authorized:","value":null},
             {"name":"Flexible Alerting Authorized:","value":null},
             {"name":"Explicit Communication Transfer Authorized:","value":null},
             {"name":"Operator CDIV Authorized:","value":null},
             {"name":"Operator CDIV Rules:","value":null},
             {"name":"Operator CDIV Maximum Diversion Count:","value":null},
             {"name":"Operator CDIV No Reply Timer:","value":null}
         ]
     }
 ]
}

Request body without formatting

 
{"identity":"sip:+6505550201@example.com","fieldGroups":[{"serviceIndication":"MMTEL-Services","fields":[{"name":"OIP Active:","value":"true"},{"name":"OIR Active:","value":"true"},{"name":"OIR Default Behaviour:","value":"presentation-not-restricted"},{"name":"TIR Default Behaviour:","value":"presentation-not-restricted"},{"name":"TIP Active:","value":"true"},{"name":"TIR Active:","value":"true"},{"name":"ICB Active:","value":"false"},{"name":"OCB Active:","value":"false"},{"name":"CW Active:","value":"false"},{"name":"CDIV Active:","value":"true"},{"name":"CDIV No Reply Timer:","value":"60"},{"name":"CDIV Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\">\n    <cp:rule id=\"unconditional\">\n        <cp:conditions>\n        </cp:conditions>\n        <cp:actions>\n            <forward-to>\n                <target>sip:6505550202@example.com</target>\n                <notify-caller>true</notify-caller>\n            </forward-to>\n        </cp:actions>\n    </cp:rule>\n</cp:ruleset>\n"},{"name":"ICB Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},{"name":"OCB Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},{"name":"Flexible Alerting Group Type:","value":"single-user"},{"name":"Flexible Alerting Membership Type:","value":"permanent"},{"name":"Flexible Alerting Group Members:","value":null},{"name":"Flexible Alerting Pilot Number:","value":null},{"name":"Flexible Alerting Group Authorized:","value":"false"},{"name":"Flexible Alerting Authorized:","value":"false"},{"name":"Explicit Communication Transfer Authorized:","value":"false"},{"name":"Operator CDIV Authorized:","value":null},{"name":"Operator CDIV Rules:","value":null},{"name":"Operator CDIV Maximum Diversion Count:","value":null},{"name":"Operator CDIV No Reply Timer:","value":null}]}]}

Request using Curl

 
curl -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -i \
     -X PUT \
     -u "username:password" \
     --data '{"identity":"sip:+6505550201@example.com","fieldGroups":[{"serviceIndication":"MMTEL-Services","fields":[{"name":"OIP Active:","value":"true"},{"name":"OIR Active:","value":"true"},{"name":"OIR Default Behaviour:","value":"presentation-not-restricted"},{"name":"TIR Default Behaviour:","value":"presentation-not-restricted"},{"name":"TIP Active:","value":"true"},{"name":"TIR Active:","value":"true"},{"name":"ICB Active:","value":"false"},{"name":"OCB Active:","value":"false"},{"name":"CW Active:","value":"false"},{"name":"CDIV Active:","value":"true"},{"name":"CDIV No Reply Timer:","value":"60"},{"name":"CDIV Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\">\n    <cp:rule id=\"unconditional\">\n        <cp:conditions>\n        </cp:conditions>\n        <cp:actions>\n            <forward-to>\n                <target>sip:6505550202@example.com</target>\n                <notify-caller>true</notify-caller>\n            </forward-to>\n        </cp:actions>\n    </cp:rule>\n</cp:ruleset>\n"},{"name":"ICB Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},{"name":"OCB Rules:","value":"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<cp:ruleset xmlns=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" xmlns:ocp=\"urn:oma:xml:xdm:common-policy\" xmlns:cp=\"urn:ietf:params:xml:ns:common-policy\"/>\n"},{"name":"Flexible Alerting Group Type:","value":"single-user"},{"name":"Flexible Alerting Membership Type:","value":"permanent"},{"name":"Flexible Alerting Group Members:","value":null},{"name":"Flexible Alerting Pilot Number:","value":null},{"name":"Flexible Alerting Group Authorized:","value":"false"},{"name":"Flexible Alerting Authorized:","value":"false"},{"name":"Explicit Communication Transfer Authorized:","value":"false"},{"name":"Operator CDIV Authorized:","value":null},{"name":"Operator CDIV Rules:","value":null},{"name":"Operator CDIV Maximum Diversion Count:","value":null},{"name":"Operator CDIV No Reply Timer:","value":null}]}]}' \
     "http://localhost:8080/rem/sentinel/api/hssdata/subscriberdata/sip:+6505550201@example.com?rhinoInstanceId=Local&selectionKey=Metaswitch::::"

Response Header

 
HTTP/1.1 100 Continue

HTTP/1.1 204 No Content
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=B09687CA5DE7037230D0D8EBF04924E2; Path=/rem/; HttpOnly
Date: Sun, 13 May 2018 23:59:08 GMT

Response Body

 
There is no response body

Delete Examples

The delete operation will remove any Sh Transparent User Data document that the API is configured for, By default this means that both the IMS-ODB-Information and MMTel-Services documents are deleted.

Deleting a subscriber that has Sh Transparent Data

In this example:

  • the imsUserIdentity is sip:+6505550201@example.com - it is specified in the URI

  • the HTTP Request Method is DELETE

  • the rhinoInstanceId is Local

  • the selectionKey is Metaswitch::::

  • the requested framing format is JSON

  • the username is username

  • the password is password

  • the server is located on localhost running on port 8080

Request

 
curl -H 'Accept: application/json' \
     -i \
     -X DELETE \
     -u "username:password"
     "http://localhost:8080/rem/sentinel/api/hssdata/subscriberdata/sip:+6505550201@example.com?rhinoInstanceId=Local&selectionKey=Metaswitch::::"

Response headers

 
HTTP/1.1 204 No Content
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=A0944D87B81D23D8B9246CF994DE7067; Path=/rem/; HttpOnly
Date: Mon, 14 May 2018 01:57:15 GMT

Response body

There is no response body

Deleting a subscriber that has no Sh Transparent Data

In this example:

  • the imsUserIdentity is sip:+6505550201@example.com - it is specified in the URI

  • the HTTP Request Method is DELETE

  • there is no configured transparent data

  • the rhinoInstanceId is Local

  • the selectionKey is Metaswitch::::

  • the requested framing format is JSON

  • the username is username

  • the password is password

  • the server is located on localhost running on port 8080

Request

 
curl -H 'Accept: application/json' \
     -i
     -X DELETE \
     -u "username:password"
     "http://localhost:8080/rem/sentinel/api/hssdata/subscriberdata/sip:+6505550201@example.com?rhinoInstanceId=Local&selectionKey=Metaswitch::::"

Response headers

 
HTTP/1.1 404 Not Found
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: Mon, 14 May 2018 01:57:27 GMT

Response body

 
{"type":"EntityNotFound","message":"Subscriber data could not be found for IMS user identity \"sip:+6505550201@example.com\" and selection key \"Metaswitch::::\""}

Configuring using simple tools and scripts

Many of the APIs available as part of this document allow configuration of the Sentinel VoLTE application and its internal components. Higher-level clients can be used to configure the application using the REST API from Java or other application code, but you really just need to be able to make HTTP requests. See these examples:

Adding a feature execution script with curl (XML)

Request

 
curl -H 'Accept: application/xml' \
     -H 'Content-Type: application/xml' \
     -i -w '\nHTTP STATUS: %{http_code}\nTIME: %{time_total}\n' \
     -X POST \
     -u "username:password" \
     -d "<featureExecutionScript><name>my_new_feature_script</name><src>featurescript newScript { }</src></featureExecutionScript>" \
     "http://localhost:8080/rem/sentinel/api/featureexecutionscripts/scripts?rhinoInstanceId=Local&selectionKey=OpenCloud::::"

Response

 
HTTP/1.1 201 Created
Date: Tue, 13 Sep 2011 20:42:15 GMT
Location: http://localhost:8080/rem/sentinel/api/featureexecutionscripts/scripts/my_new_feature_script?rhinoInstanceId=Local&selectionKey=OpenCloud::::
Content-Length: 0
Server: Jetty(6.1.24)

Turning on HomeZone for a subscriber using Ruby (JSON)

Note: this specific example is not relevant to the Sentinel VoLTE application as the Home Zone feature is not part of Sentinel VoLTE. This example is intended to show how Ruby can be used with the configuration API.

require 'rubygems'
require 'json'
require 'net/http'

Net::HTTP.start('localhost', '8080') {|http|
  req = Net::HTTP::Get.new('/rem/sentinel/api/subscriberdata/records/34600000003?rhinoInstanceId=Local&selectionKey=OpenCloud::::', {'Accept' => 'application/json'})
  req.basic_auth 'username', 'password'
  response = http.request(req)
  subscriber = JSON.parse(response.body)
  subscriber['subscriberData'].each {|item|
    if item['name'] == 'HomeZoneEnabled'
      item['valueBoolean'] = true;
    end
  }

  req = Net::HTTP::Put.new('/rem/sentinel/api/subscriberdata/records/34600000003?rhinoInstanceId=Local&selectionKey=OpenCloud::::', {'Content-Type' => 'application/json'})
  req.basic_auth 'username', 'password'
  response = http.request(req, JSON.generate(subscriber))
}
Next page