Sh Interface (Subscriber Data Retrieval)

📖 Back to Main Documentation

The Sh interface provides access to subscriber profile data from the HSS/Repository via Diameter.

Core Documentation

📋 Main README - Overview and quick start
🔧 Configuration Guide - Diameter peer configuration
🔧 Operations Guide - Sh interface testing in Control Panel

Call Processing Integration

🔀 Dialplan Configuration - Using Sh data in dialplan variables
⚙️ Supplementary Services - MMTel-Config for call forwarding
📡 SS7 MAP - HLR data vs Sh data priority

💳 Online Charging - Ro interface (also uses Diameter)
🔢 Number Translation - Number normalization before Sh lookup

Monitoring

📊 Metrics Reference - Sh interface metrics and monitoring

Sh Interface (Subscriber Data Retrieval)

The Sh interface is used to retrieve subscriber profile data from the HSS/Repository before processing calls. This data includes subscriber identities, services, and MMTel configuration.

What is the Sh Interface?

The Sh interface is a 3GPP-standardized Diameter interface between the TAS and HSS/Repository (Repo). It provides real-time access to:

IMS subscriber identities (IMPI/IMPU)
Call forwarding settings (MMTel-Config)
Subscriber service authorization
S-CSCF assignment

When Sh Lookups Occur

Sh Lookups Happen On:

MT Calls: Lookup called party (destination subscriber)
MO Calls: Lookup calling party (source subscriber)
Emergency Calls: Lookup calling party (for location/identity)

In every case the TAS issues exactly one UDR per call leg. Both MO and MT use the same multi-Data-Reference UDR shape — only the metric labels differ.

Multi-Data-Reference UDR (Notif-Eff)

Per 3GPP TS 29.328 §6.1.1.1, when both the AS and the HSS support the Notif-Eff feature (negotiated via the Supported-Features AVP), a single UDR may carry multiple Data-Reference AVPs and the HSS responds with one UDA whose User-Data-Sh is a single <Sh-Data> document concatenating the per-reference subtrees as siblings. TAS relies on this — every Sh lookup fetches the full set of references the system knows how to consume in one round-trip.

Data-References requested (TS 29.328 Table 7.6.1)

Ref	Element	Used by TAS to populate
0	RepositoryData (with `Service-Indication = "MMTEL-Services"`)	`call_forward_all_destination`, `call_forward_not_reachable_destination`, `no_reply_timer`
10	IMSPublicIdentity	`ims_public_identity`, `msisdn`
11	IMSUserState	`ims_user_state` (raw enum value from TS 29.328 §7.6.3)
12	SCSCFName	`scscf_address`, `scscf_domain`
13	InitialFilterCriteria	(body returned to TAS but not currently surfaced as a dialplan variable)
14	LocationInformation	`location_rat_type`, `location_mme_name`, `location_vplmn_id`, `location_age_seconds`
15	UserState	`user_state` (raw enum value from TS 29.328 §7.6.7)
17	MSISDN	(cross-checked against IMPU)
32	IMSI	`imsi`
33	IMSPrivateUserIdentity	`ims_private_identity`, `ims_domain` (parsed from suffix)

All of the single-string fields are surfaced to the dialplan as raw string variables — TAS does not interpret their values. See the Dialplan Variables Set from Sh Data table below for the full list.

Example UDA body (sanitised)

A successful merged response in the live trace looks like this — the per-reference subtrees appear under one <Sh-Data> wrapper in the order the references were requested:

[debug] Fetched caller data for +614xxxxxxxx
        (Data-Ref [0, 10, 11, 12, 13, 14, 15, 17, 32, 33],
         SI="MMTEL-Services"): 4453 bytes

<?xml version="1.0" encoding="UTF-8"?>
<Sh-Data>
  <RepositoryData></RepositoryData>
  <PublicIdentifiers>
    <IMSPublicIdentity>sip:+614xxxxxxxx@ims.mnc001.mcc999.3gppnetwork.org</IMSPublicIdentity>
    <IMSPublicIdentity>tel:+614xxxxxxxx</IMSPublicIdentity>
  </PublicIdentifiers>
  <ShIMSData>
    <IMSUserState>1</IMSUserState>
  </ShIMSData>
  <ShIMSData>
    <SCSCFName>sip:scscf01.ims.mnc001.mcc999.3gppnetwork.org:5060</SCSCFName>
  </ShIMSData>
  <IMSSubscription>
    <PrivateID>9999990000xxxxx@ims.mnc001.mcc999.3gppnetwork.org</PrivateID>
    <ServiceProfile>
      ... InitialFilterCriteria entries ...
    </ServiceProfile>
  </IMSSubscription>
  <ShIMSData>
    <LocationInformation>
      <RAT-Type>eutran</RAT-Type>
      <MMEName>mme01.epc.mnc001.mcc999.3gppnetwork.org</MMEName>
      <VPLMNId>999001</VPLMNId>
      <AgeOfLocationInformation>NNNN</AgeOfLocationInformation>
    </LocationInformation>
  </ShIMSData>
  <IMSPrivateUserIdentity>9999990000xxxxx@ims.mnc001.mcc999.3gppnetwork.org</IMSPrivateUserIdentity>
</Sh-Data>

How parsers consume the merged body

The TAS does not walk the XML tree. Each per-reference parser is independent and tag-based: it searches the merged body for a specific element name (e.g. <SCSCFName>, <IMSPublicIdentity>, <CallForwardUnconditional>, <CallForwardNoReplyTimer>, the not-reachable cp:rule block) and pulls out only the value it cares about. Subtrees that the parser does not recognise are silently ignored.

The result of each parser is a partial subscriber-data map; the partials are merged in order over a defaults map. This makes the lookup robust to heterogeneous HSS implementations and partial responses — see the graceful degradation section below.

Data Retrieved from Sh Interface

The TAS issues a single multi-Data-Reference UDR per call leg (see Multi-Data-Reference UDR (Notif-Eff) above for the request shape and the merged response). The fields the TAS extracts from the merged <Sh-Data> body fall into three groups:

1. IMS Identities:

IMPI (Private Identity): parsed from the <IMSPrivateUserIdentity> element. Format: {IMSI}@{IMS-domain}. The TAS splits on @ to recover the IMSI and the IMS domain independently.
IMPU (Public Identity): parsed from the <IMSPublicIdentity> element. Format: sip:+{MSISDN}@{IMS-domain}. The MSISDN is stripped of the leading + and surfaced as the msisdn dialplan variable.

2. S-CSCF Assignment:

S-CSCF server name and domain where the subscriber is currently registered, parsed from the <SCSCFName> element (Data-Reference 12). Used by the MT dialplan to route the INVITE directly to the registered S-CSCF rather than fanning out into the IMS realm.
Note: the canonical XML element name in TS 29.328 Annex D is SCSCFName (no hyphen). The hyphenated form "S-CSCF" only appears in spec prose.

3. MMTel Services (Multimedia Telephony Configuration):

Returned inside <RepositoryData> keyed by Service-Indication = "MMTEL-Services".
Subscriber-specific call forwarding rules:
- Call Forward All (CFA): Unconditional forwarding to another number
- Call Forward Busy (CFB): Forward when subscriber is busy
- Call Forward No Reply (CFNRy): Forward after timeout (timer value extracted from <CallForwardNoReplyTimer>)
- Call Forward Not Reachable (CFNRc): Forward when subscriber is offline/unregistered (extracted from the not-reachable <cp:rule> inside the MMTel-Services repository document)

What is MMTel-Config?

MMTel-Config is the subscriber's Multimedia Telephony service configuration stored as transparent (repository) data in the HSS, keyed by Service-Indication = "MMTEL-Services". It is fetched as part of the same multi-Data-Reference UDR as the identity lookup (Data-Reference 0 plus the service indication AVP). The document follows the OMA / 3GPP simservs XCAP schema and typically contains a complete-communication-diversion block with one or more cp:rule entries (busy, noanswer, unregistered, notreachable), an optional <NoReplyTimer> value, and other MMTel sub-services such as Communication Barring and Identity Presentation.

Common MMTel Services TAS recognises:

CDIV (Communication Diversion): Call forwarding rules — the only block currently parsed end-to-end into dialplan variables. The notreachable rule populates call_forward_not_reachable_destination and <NoReplyTimer> populates no_reply_timer.
OIP (Originating Identity Presentation): Caller ID presentation rules (returned in the body but not currently consumed).
TIP (Terminating Identity Presentation): Called party number rules (returned in the body but not currently consumed).

Dialplan Variables Set from Sh Data

After a successful Sh lookup, these variables are populated:

Variable	Source	Example Value	Description
`ims_private_identity`	IMPI	`9999990000xxxxx@ims.mnc001.mcc999.3gppnetwork.org`	Private user identity for authentication
`ims_public_identity`	IMPU	`sip:+614xxxxxxxx@ims.mnc001.mcc999.3gppnetwork.org`	Public user identity for routing
`msisdn`	IMPU (parsed)	`614xxxxxxxx`	Subscriber number (+ stripped)
`imsi`	IMPI (parsed)	`9999990000xxxxx`	IMSI from private identity
`ims_domain`	IMPI/IMPU	`ims.mnc001.mcc999.3gppnetwork.org`	IMS domain
`scscf_address`	SCSCFName	`sip:scscf01.ims.mnc001.mcc999.3gppnetwork.org:5060` or `"none"`	S-CSCF server address (registered)
`scscf_domain`	SCSCFName (parsed)	`scscf01.ims.mnc001.mcc999.3gppnetwork.org` or `"none"`	S-CSCF host (registered)
`call_forward_all_destination`	MMTel CDIV	numeric or `"none"`	CFA destination number
`call_forward_not_reachable_destination`	MMTel CDIV	numeric or config default	CFNRc destination (voicemail)
`no_reply_timer`	MMTel CDIV	seconds, or config default	Timeout before CFNRy activates
`ims_user_state`	IMSUserState (Data-Ref 11)	`"0"`/`"1"`/`"2"`/`"3"` or `"none"`	IMS registration state enum. `1` = REGISTERED, `0` = NOT_REGISTERED, `2` = AUTHENTICATION_PENDING, `3` = REGISTERED_UNREG_SERVICES (TS 29.328 §7.6.3). Raw string, TAS does not interpret.
`user_state`	UserState (Data-Ref 15)	raw string or `"none"`	CS/PS user state (TS 29.328 §7.6.7). Raw string, TAS does not interpret.
`location_rat_type`	LocationInformation/RAT-Type	`"eutran"`, `"utran"`, `"geran"`, `"wlan"`, ... or `"none"`	Radio access technology of the last known registration.
`location_mme_name`	LocationInformation/MMEName	MME FQDN or `"none"`	MME host serving the subscriber.
`location_vplmn_id`	LocationInformation/VPLMNId	`MCCMNC` digit string or `"none"`	Visited PLMN identifier (useful for roaming detection in the dialplan).
`location_age_seconds`	LocationInformation/AgeOfLocationInformation	numeric string or `"none"`	Seconds since the location information was last reported to the HSS.

Priority: Sh Data vs Configuration Defaults

The TAS uses this priority order for call forwarding data:

MMTel-Config from Sh — highest priority, subscriber-specific settings.
HLR Data from SS7 MAP — overrides Sh for MT calls if roaming or call forwarding is active in the visited network. See SS7 MAP.
Configuration Defaults — lowest priority, used when neither Sh nor HLR provides a value (or when the corresponding subtree was missing from the Sh response — see graceful degradation below). The defaults are configured in runtime.exs under config :tas — call_forward_not_reachable_destination and default_no_reply_timer.

What Happens When Sh Lookup Fails

Whole-request failure scenarios:

Subscriber Not Provisioned in HSS:
- HSS returns Experimental-Result-Code 5001 (DIAMETER_ERROR_USER_UNKNOWN)
- TAS treats the call leg as unresolvable
- hangup_case variable set to "UNALLOCATED_NUMBER"
- Call rejected with appropriate SIP response
HSS Unreachable / Timeout:
- Sh request times out (default: 5000ms, see Diameter request_timeout in runtime.exs)
- Error logged and metric recorded
- Call leg fails the same way as case (1)
HSS does not support multi-Data-Reference UDRs:
- HSS either returns an error or drops the request silently (HSS-dependent)
- From the TAS side this looks like case (1) or (2) — the lookup fails wholesale and the call leg is rejected
- The HSS must implement the Notif-Eff feature for TAS to function. See TS 29.328 §6.1.1.1 for the feature definition.

Graceful per-subtree degradation

When the UDR itself succeeds (Result-Code: 2001) but individual subtrees of the merged <Sh-Data> body are missing, TAS does not fail the call. Each per-reference parser is independent and falls back to a defined default when its tag is absent. Operators only have to worry about whole-request failures (above); partial-data degradation is automatic and observable in the debug logs.

Subtree missing	Result
`<SCSCFName>` (Data-Ref 12)	`scscf_address` and `scscf_domain` set to `"none"`
`<IMSPrivateUserIdentity>` (Data-Ref 33)	`ims_private_identity`, `imsi`, `ims_domain` set to `"none"`
`<CallForwardUnconditional>` inside MMTel RepositoryData	`call_forward_all_destination` set to `"none"`
`not-reachable`/`<cp:rule>` block inside MMTel RepositoryData	`call_forward_not_reachable_destination` falls back to `Tas.Config.call_forward_not_reachable_destination()`
`<CallForwardNoReplyTimer>` inside MMTel RepositoryData	`no_reply_timer` falls back to `Tas.Config.default_no_reply_timer()`
Empty `<RepositoryData></RepositoryData>`	All MMTel-derived fields fall back to config defaults
Empty/absent `<IMSUserState>`, `<LocationInformation>`, `<InitialFilterCriteria>`	Currently no dialplan side-effect (parsed but not yet plumbed)

The only hard requirement is that the response contains an <IMSPublicIdentity> element. If that tag is missing the lookup returns {:error, :sh_parse_failed} and the call leg is treated as unresolvable (same downstream behaviour as case 1 above). Every other field is "ask freely, take what you can get".

This makes TAS resilient to heterogeneous HSS deployments: an HSS that implements Notif-Eff but only populates IMSPublicIdentity, MSISDN and SCSCFName (for example) will still produce a working call; the dialplan just falls back to config defaults for the MMTel-derived variables.

Monitoring Sh Interface

Key Metrics:

# Sh lookup success rate
rate(subscriber_data_lookups_total{result="success"}[5m]) /
rate(subscriber_data_lookups_total[5m]) * 100

# Sh lookup latency (P95)
histogram_quantile(0.95,
  rate(subscriber_data_duration_milliseconds_bucket[5m]))

# Sh error rate
rate(subscriber_data_lookups_total{result="error"}[5m])

Alert Thresholds:

P95 latency > 100ms: Slow HSS responses
Error rate > 5%: HSS connectivity issues
Error rate > 20%: Critical HSS failure

Troubleshooting:

Check Diameter peer status in Web UI (/diameter)
Test Sh lookup in Web UI (/sh_test) with known subscriber
Review logs for "Subscriber Data" errors
Verify HSS/Repository is reachable from TAS
Check subscriber_data_lookups_total metric for patterns

Testing Sh Interface

Use the Web UI Sh Test tool (/sh_test):

Navigate to /sh_test in Control Panel
Enter subscriber MSISDN (e.g., +614xxxxxxxx)
Click "Query Sh"
Review returned data:
- IMPI/IMPU identities
- S-CSCF assignment
- MMTel services
- Call forwarding configuration

Common Test Scenarios:

Verify newly provisioned subscribers are in HSS
Check call forwarding settings for specific subscriber
Validate S-CSCF assignment after IMS registration
Test HSS connectivity and response times

Related Documentation​

Core Documentation​

Call Processing Integration​

Related Interfaces​

Monitoring​

Sh Interface (Subscriber Data Retrieval)​

What is the Sh Interface?​

When Sh Lookups Occur​

Multi-Data-Reference UDR (Notif-Eff)​

Data-References requested (TS 29.328 Table 7.6.1)​

Example UDA body (sanitised)​

How parsers consume the merged body​

Data Retrieved from Sh Interface​

What is MMTel-Config?​

Dialplan Variables Set from Sh Data​

Priority: Sh Data vs Configuration Defaults​

What Happens When Sh Lookup Fails​

Graceful per-subtree degradation​

Monitoring Sh Interface​

Testing Sh Interface​

Related Documentation

Core Documentation

Call Processing Integration

Related Interfaces

Monitoring

Sh Interface (Subscriber Data Retrieval)

What is the Sh Interface?

When Sh Lookups Occur

Multi-Data-Reference UDR (Notif-Eff)

Data-References requested (TS 29.328 Table 7.6.1)

Example UDA body (sanitised)

How parsers consume the merged body

Data Retrieved from Sh Interface

What is MMTel-Config?

Dialplan Variables Set from Sh Data

Priority: Sh Data vs Configuration Defaults

What Happens When Sh Lookup Fails

Graceful per-subtree degradation

Monitoring Sh Interface

Testing Sh Interface