The Sentinel REM extension provides a RESTful API for invalidating caches and cache entries managed by the Sh Cache Microservice.

It is based on the Sh Cache Microservice’s Invalidation Management API, as detailed in the Sh Cache Microservice documentation.

Tip The basic mechanism for accessing this REST API is the same as for the rest of the Sentinel VoLTE Provisioning REST API.

This page covers

Dropping caches and invalidating cache entries

The Sh Cache Microservice section of the api, within the /rem/sentinel/api/shcache path, is chiefly concerned with dropping whole caches, and invalidating individual cache entries. Both of these are achieved by issuing a DELETE request for the appropriate URL.

For example, DELETE with path /rem/sentinel/api/shcache would drop all caches.

As another example, invalidating a single entry within a cache is also achieved using a DELETE request, but with URL matrix parameters to specify which cache entry should be deleted. E.g.:

/rem/sentinel/api/shcache/cs-user-state
  ;userIdentity=0211111111;userIdentityType=msisdn;requestedNodes=1.

Note that these DELETE operations take effect across the cluster as a whole.

Accessing cache counts and cache entry counts

For each DELETE operation which operates on either whole caches, or individual cache entries, there is an analogous GET operation which can be used to inspect a count related to those caches or cache entries.

Note that these operations only query cache information from the single node which services the request, rather than from the cluster as a whole. This is in contrast to the DELETE requests which operate on the cluster as a whole. These GET requests therefore are useful more for integration testing, and are not appropriate for querying the definitive state of the caches across the whole cluster.

Notes on URL format

Notes on the format of the URL schemes below:

  • {someValue} indicates a position where some value should be supplied.

  • A […​] indicates an optional part of the URL. E.g.: [;privateIdentity={privateIdentity}].

  • An alternative is indicated as (A|B), where either A or B should be specified.

  • The available values for many of the URL parameters are described in available arguments for individual parameters.

Specifying the Rhino Instance Id

For all requests, the ?rhinoInstanceId={rhinoInstanceId} URL query parameter must be specified after the URL path, and after any URL matrix parameters.

An example of a full URL for a DELETE request:

http://thehostname/rem/sentinel/api/shcache/repository-data
  ;serviceIndication=MMTEL-Services
  ;userIdentity=sip:alice@home1.opencloud.co.nz?rhinoInstanceId=Local

After the path (ending with repository-data), we see the URL matrix parameters (each of the form ;key=value), followed by the URL query parameter ?rhinoInstanceId=Local at the end.

The value of the rhinoInstanceId parameter is the ID of the Rhino instance to connect to. This should exactly match the name of a Rhino instance configured in the Rhino Element Manager (REM), such as ?rhinoInstanceId=Local.

For the sake of brevity, the rest of this document assumes that the query parameter ?rhinoInstanceId={rhinoInstanceId} is appended to all DELETE and GET requests related to the this API, and it is not explicitly included in the URLs below.

URLs for querying or dropping whole caches

For these URLs:

  • A GET request returns the number of caches present on the node which services the request.

  • A DELETE request drops the caches across all nodes in the cluster.

A successful GET request will return a 200 OK response, containing a response body such as the following:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cacheInfo><cacheCount>1</cacheCount></cacheInfo>

A successful DELETE request will return a 204 No Content response, containing no response body.

URL for all caches

/rem/sentinel/api/shcache

Acts on all Sh caches.

URL for all caches within a given data reference

/rem/sentinel/api/shcache/{dataReference}

Acts on all Sh caches related to the given data reference.

For queries where the dataReference is repository-data, the query can be optionally narrowed by serviceIndication:

/rem/sentinel/api/shcache/repository-data[;serviceIndication={serviceIndication}]

URLs for querying or dropping cache entries

For these URLs:

  • A GET request returns the number of cache entries on the node which services the request.

  • A DELETE request invalidates the cache entries across all nodes in the cluster.

A successful GET request will return a 200 OK response, containing a response body such as the following:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cacheInfo><entryCount>1</entryCount></cacheInfo>

A successful DELETE request will return a 204 No Content response, containing no response body.

URL for entries within a given data reference

/rem/sentinel/api/shcache/{dataReference}
        ;userIdentity={userIdentity};userIdentityType=impu
        [;privateIdentity={privateIdentity}]

Acts on cache entries within the given data reference, as narrowed by the given parameters.

Rules:

  • dataReference must not be repository-data. For repository-data specific queries, see the URL query format which is specific to repository-data.

  • The privateIdentity parameter may only be included when using one of the following data references: msisdn, sms-registration-info, ue-reachability-for-ip, tads-information, stn-sr, ue-srvcc-capability, extended-priority, csrn, reference-location-information.

URL for entries within the RepositoryData data reference

/rem/sentinel/api/shcache/repository-data
        ;userIdentity={userIdentity}
        [;serviceIndication={serviceIndication}]

Acts on cache entries within the RepositoryData data reference, optionally narrowed by service indication.

Rules:

  • The userIdentity is treated as an IMPU. The userIdentityType parameter does not need to be provided in the URL, but if provided it must be set to impu.

URL for entries within the DSAI data reference

/rem/sentinel/api/shcache/dsai
        ;userIdentity={userIdentity};userIdentityType={userIdentityType}
        ;applicationServerName={applicationServerName};dsaiTags={dsaiTags}

Acts on cache entries within the DSAI data reference, narrowed by the given parameters.

URL for entries within the IMSPublicIdentity data reference

/rem/sentinel/api/shcache/ims-public-identity
        ;userIdentity={userIdentity};userIdentityType={userIdentityType}
        [;identitySets={identitySets}]

Acts on cache entries within the IMSPublicIdentity data reference, narrowed by the given parameters.

URL for entries within the InitialFilterCriteria data reference

/rem/sentinel/api/shcache/initial-filter-criteria
        ;userIdentity={userIdentity};userIdentityType={userIdentityType}
        ;applicationServerName={applicationServerName}

Acts on cache entries within the InitialFilterCriteria data reference, narrowed by the given parameters.

URL for entries within the LocationInformation data reference

/rem/sentinel/api/shcache/(cs-location-information\|ps-location-information)
        ;userIdentity={userIdentity};userIdentityType={userIdentityType}
        [;privateIdentity={privateIdentity}]
        ;currentLocation={currentLocation}
        [;servingNodeIndication={servingNodeIndication}]
        [;requestedNodes={requestedNodes}]
        [;localTimeZoneIndication={localTimeZoneIndication}]

Acts on cache entries within the LocationInformation data reference within either the CS or PS domain, narrowed by the given parameters.

Rules:

  • userIdentityType may specify either impu or msisdn.

URL for entries within the UserState data reference

/rem/sentinel/api/shcache/(cs-user-state\|ps-user-state)
        ;userIdentity={userIdentity};userIdentityType={userIdentityType}
        [;privateIdentity={privateIdentity}]
        [;requestedNodes={requestedNodes}]

Acts on cache entries within the UserState data reference within either the CS or PS domain, narrowed by the given parameters.

Rules:

  • userIdentityType may specify either impu or msisdn.

Available arguments for individual parameters

Available values for the dataReference parameter:

Note: the repository-data data reference has its own specific URLs, as shown above.

  • charging-information

  • cs-location-information

  • csrn

  • cs-user-state

  • dsai

  • extended-priority

  • ims-public-identity

  • ims-user-state (Recognized, but not yet supported in any of the above methods)

  • initial-filter-criteria

  • ip-address-secure-binding-information

  • msisdn

  • psi-activation

  • ps-location-information

  • ps-user-state

  • reference-location-information

  • repository-data

  • scscf-name

  • service-level-trace-info

  • service-priority-level

  • sms-registration-info

  • stn-sr

  • tads-information

  • ue-reachability-for-ip

  • ue-srvcc-capability

Available values for the userIdentityType parameter:

  • impu

  • msisdn

  • psi

When querying the HSS for MSISDN data, VoLTE by default sets the identity type to IMPU. If the FetchCMSISDNFeatureConfigProfileTable profile has UDRIncludedIdentities set to IMPU_IMPI then the IMPI is also included in the query. When using the Sh Cache Rest API to act on the MSISDN caches, set the identity type to IMPU and include both the IMPU and IMPI or just the IMPU, depending on the FetchCMSISDNFeatureConfigProfileTable configuration.

Available values for the servingNodeIndication parameter:

  • only-serving-nodes-required

Available values for the localTimeZoneIndication parameter:

  • local-time-zone-with-location-info-requested

  • only-local-time-zone-requested

Available values for the identitySets parameter:

  • alias-identities

  • all-identities

  • implicit-identities

  • registered-identities

Available values for the currentLocation parameter:

  • do-not-need-initiate-active-location-retrieval

  • initiate-active-location-retrieval

Available values for the serviceIndication parameter:

While there are many potential values for the serviceIndication parameter, the well known values within Sentinel VoLTE include:

  • IMS-ODB-Information

  • MMTEL-Services

  • Metaswitch-TAS-Services

  • opencloud-3rd-party-registrar

  • ParentalControl

Previous page