Sh RepositoryData (Transparent Data)

OmniHSS acts as a transparent repository for service data that Application Servers (AS) store against a subscriber over the Sh interface. Documents such as MMTEL-Services (supplementary services / call diversion, call waiting, OIP/OIR, barring) and IMS-ODB-Information (operator-determined barring) are written by the AS, kept by the HSS, and read back on demand.

"Transparent" has a precise meaning in 3GPP TS 29.328: the HSS understands this data syntactically but not semantically. It is opaque XML owned by the AS. OmniHSS stores and returns the ServiceData payload byte-for-byte — it never re-parses or re-serialises it — so a document an AS etags or checksums (for example XCAP/MMTel) is returned exactly as written.

The same documents can also be managed out-of-band by provisioning/CRM systems through the REST Provisioning API.

Table of Contents

• Concepts
• Data Model
• Sh Message Flows
• SequenceNumber and Concurrency
• REST Provisioning API
• Reference Tables
• Troubleshooting

Concepts

A subscriber may hold any number of independent transparent documents, each identified by a Service-Indication (the "filename"). A document has three parts:

Element	Owner	Meaning
Service-Indication	HSS-managed	Names the document (e.g. MMTEL-Services, IMS-ODB-Information).
SequenceNumber	HSS-managed	Version counter used for optimistic concurrency. See SequenceNumber and Concurrency.
ServiceData	AS-owned (opaque)	The XML payload itself. Stored and returned verbatim.

The HSS only interprets Service-Indication and SequenceNumber. The ServiceData body is treated as opaque bytes.

Data Model

All of a subscriber's transparent documents are held in a single field, subscriber_state.sh_repository_data, as a JSON object keyed by Service-Indication. Each entry stores the version and the verbatim payload:

{
  "MMTEL-Services":      { "sequence_number": "0", "service_data": "<MMTelServices …>…</MMTelServices>" },
  "IMS-ODB-Information": { "sequence_number": "1", "service_data": "<OdbForImsOrientedServices xmlns=\"odb.mmtel.omnitou.ch\"/>" }
}

Field	Description
sequence_number	The current version of this document, as last accepted by the HSS. Returned in every UDA and used to validate updates.
service_data	The opaque XML body, stored exactly as the AS sent it (no namespace, attribute-order or whitespace normalisation). A document with no ServiceData element (the spec's empty repository data) omits this field.

This model means a single subscriber can hold many distinct documents, each versioned independently, with no fixed schema imposed by the HSS.

Sh Message Flows

RepositoryData is carried in the User-Data AVP as a Sh-Data XML document. RepositoryData is selected with Data-Reference value 0. An optional Service-Indication AVP narrows a request to a single document.

User Data Request (UDR/UDA) — Read

The AS reads one or all transparent documents. With a Service-Indication, only the matching document is returned; without one, every stored document is returned, each as its own <RepositoryData> element.

An unknown or non-IMS subscriber is answered with Experimental-Result 5001 (DIAMETER_ERROR_USER_UNKNOWN).

Profile Update Request (PUR/PUA) — Write

The AS creates or updates a single document. The ServiceData payload is stored verbatim. The update is accepted only if its SequenceNumber is valid (see below).

When a PUR resolves to multiple subscribers (a wildcarded Public Identity), the update is applied atomically: if any document is out of sync, none are persisted.

Subscribe Notifications Request (SNR/SNA) — Subscribe

The AS subscribes to a subscriber's data and may request the current value be returned immediately (Send-Data-Indication). OmniHSS answers the SNR and, when requested, includes the current RepositoryData.

SequenceNumber and Concurrency

The SequenceNumber provides optimistic concurrency control so two Application Servers cannot silently overwrite each other, per 3GPP TS 29.328.

• Creating a new document uses SequenceNumber 0 (value 0 is reserved exclusively for newly-added data).
• Updating an existing document must carry the immediate successor of the stored SequenceNumber (stored + 1).
• The counter wraps from 65535 back to 1 (not 0, since 0 is reserved).
• An update whose SequenceNumber is not the expected successor is rejected with Experimental-Result 5105 (DIAMETER_ERROR_TRANSPARENT_DATA_OUT_OF_SYNC) and the stored document is left unchanged.

Example: a document is stored at SequenceNumber 0. A PUR carrying SequenceNumber 5 is rejected with 5105 and nothing changes. A PUR carrying SequenceNumber 1 is accepted and the document advances to version 1.

REST Provisioning API

The same documents can be read and written directly by provisioning/CRM systems. The subscriber is addressed by IMSI in the path; the document is identified by service_indication (in the request body for updates, or the query string for reads/deletes). The opaque service_data is round-tripped byte-for-byte, exactly as over Sh.

All responses use the standard API envelope:

{ "status": "success", "response": { } }

Unlike the Sh path, the REST API is authoritative provisioning access and does not apply the SequenceNumber out-of-sync check — a write sets the document directly.

List All Documents

Returns every stored document for the subscriber.

Endpoint: GET /api/subscriber/repository_data/:imsi

curl -k https://hss.example.com:8443/api/subscriber/repository_data/001001123456789

{
  "status": "success",
  "response": {
    "MMTEL-Services":      { "sequence_number": "0", "service_data": "<MMTelServices …/>" },
    "IMS-ODB-Information": { "sequence_number": "1", "service_data": "<OdbForImsOrientedServices xmlns=\"odb.mmtel.omnitou.ch\"/>" }
  }
}

Get a Single Document

Returns one document by Service-Indication.

Endpoint: GET /api/subscriber/repository_data/:imsi?service_indication=:service_indication

curl -k "https://hss.example.com:8443/api/subscriber/repository_data/001001123456789?service_indication=MMTEL-Services"

{
  "status": "success",
  "response": { "sequence_number": "0", "service_data": "<MMTelServices …/>" }
}

Create or Update a Document

Creates the document if absent, or overwrites it.

Endpoint: PUT /api/subscriber/repository_data/:imsi

curl -k -X PUT https://hss.example.com:8443/api/subscriber/repository_data/001001123456789 \
  -H "Content-Type: application/json" \
  -d '{
        "service_indication": "MMTEL-Services",
        "service_data": "<MMTelServices version=\"1\"/>",
        "sequence_number": "0"
      }'

Field	Type	Required	Default	Description
service_indication	String	Yes	-	The document name to create/update (e.g. MMTEL-Services).
service_data	String	No	-	The opaque XML payload, stored verbatim. Omit to store an empty document (Service-Indication and SequenceNumber only).
sequence_number	String	No	0	The version to record for the document.

The response echoes the stored document:

{
  "status": "success",
  "response": { "sequence_number": "0", "service_data": "<MMTelServices version=\"1\"/>" }
}

Delete a Document

Removes a single document by Service-Indication.

Endpoint: DELETE /api/subscriber/repository_data/:imsi

curl -k -X DELETE https://hss.example.com:8443/api/subscriber/repository_data/001001123456789 \
  -H "Content-Type: application/json" \
  -d '{ "service_indication": "MMTEL-Services" }'

Field	Type	Required	Default	Description
service_indication	String	Yes	-	The document to remove.

The response returns the remaining documents for the subscriber.

Reference Tables

Data-Reference Values (RepositoryData)

Value	Name	Description	Reference
0	RepositoryData	Transparent service data identified by Service-Indication	3GPP TS 29.328 §7.6

Result and Experimental-Result Codes

Code	Name	Meaning	Reference
2001	DIAMETER_SUCCESS	UDR/PUR/SNR processed successfully	RFC 6733 §7.1.1
5001	DIAMETER_ERROR_USER_UNKNOWN	Subscriber not found or not IMS-enabled	3GPP TS 29.329
5105	DIAMETER_ERROR_TRANSPARENT_DATA_OUT_OF_SYNC	Update SequenceNumber is not the successor of the stored value	3GPP TS 29.329

Application ID

ID	Interface	Description	Reference
16777217	Sh	AS ↔ HSS user data	3GPP TS 29.329

Common Service-Indications

Service-Indication	Typical Content
MMTEL-Services	MMTel supplementary services (call diversion, communication waiting/hold/barring, OIP/OIR, conferencing) — simservs XML
IMS-ODB-Information	Operator-determined barring information for IMS-oriented services

Service-Indication values are defined by the Application Server and its corresponding XML schema; the HSS imposes no fixed list.

Troubleshooting

Application Server receives 5105 on update

Symptoms: A PUR is answered with Experimental-Result 5105 and the document is unchanged.

Possible causes:

• The AS sent a SequenceNumber that is not the immediate successor of the value stored at the HSS (its cached copy is stale).
• A concurrent update from another AS advanced the SequenceNumber.

Resolution:

1. Read the current document with a UDR to obtain the up-to-date SequenceNumber.
2. Re-issue the PUR with SequenceNumber = stored + 1.
3. To force a value administratively, set it via the REST API, which does not apply the concurrency check.

Returned ServiceData differs from what was written

Symptoms: The AS believes the payload was altered by the HSS.

Possible causes:

• This should not occur — OmniHSS stores and returns ServiceData byte-for-byte. Apparent differences usually come from the AS's own XML library re-serialising the document (changing namespace prefixes, attribute order or whitespace) before comparison.

Resolution:

1. Compare the raw bytes returned in the UDA/REST response against the raw bytes sent, not a re-parsed representation.
2. Confirm the AS is not normalising the XML on its side before the comparison.

Document not found via REST

Symptoms: GET …/repository_data/:imsi?service_indication=… returns an error.

Possible causes:

• No document with that Service-Indication is stored for the subscriber.
• The IMSI does not correspond to an existing subscriber.

Resolution:

1. List all documents with GET /api/subscriber/repository_data/:imsi to see what is stored.
2. Verify the IMSI with Get Subscriber by IMSI.