Sh Interface (Subscriber Data Retrieval)

📖 Back to Main Documentation

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

Related Documentation

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

Related Interfaces

• 💳 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)

Data Retrieved from Sh Interface

The TAS queries for Sh-User-Data which returns an XML document containing:

1. IMS Identities:

• IMPI (Private Identity): username@domain - used for authentication
  • Format: {IMSI}@ims.mnc{MNC}.mcc{MCC}.3gppnetwork.org
  • Example: 505014001234567@ims.mnc001.mcc505.3gppnetwork.org
• IMPU (Public Identity): sip:+number@domain - used for routing
  • Format: sip:+{MSISDN}@ims.mnc{MNC}.mcc{MCC}.3gppnetwork.org
  • Example: sip:+61403123456@ims.mnc001.mcc505.3gppnetwork.org

2. S-CSCF Assignment:

• S-CSCF server name and domain where subscriber is registered
• Used for routing on-net calls back to IMS core

3. MMTel Services (Multimedia Telephony Configuration):

• 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 (includes timer value)
• Call Forward Not Reachable (CFNRc): Forward when subscriber is offline/unregistered

What is MMTel-Config?

MMTel-Config is the subscriber's Multimedia Telephony service configuration stored in the HSS/Repository. It contains:

<MMTelSS>
  <CDIV>
    <SS-ActivationState>active</SS-ActivationState>
    <Ruleset>
      <Rule>
        <RuleCondition>communication-diverted</RuleCondition>
        <ForwardTo>+61403555123</ForwardTo>
        <NotificationType>notify</NotificationType>
      </Rule>
    </Ruleset>
  </CDIV>
</MMTelSS>

Common MMTel Services:

• CDIV (Communication Diversion): Call forwarding rules
• OIP (Originating Identity Presentation): Caller ID presentation rules
• TIP (Terminating Identity Presentation): Called party number rules

Dialplan Variables Set from Sh Data

After a successful Sh lookup, these variables are populated:

Variable	Source	Example Value	Description
ims_private_identity	IMPI	505014001234567@ims.domain	Private user identity for authentication
ims_public_identity	IMPU	sip:+61403123456@ims.domain	Public user identity for routing
msisdn	IMPU (parsed)	61403123456	Subscriber number (+ stripped)
imsi	IMPI (parsed)	505014001234567	IMSI from private identity
ims_domain	IMPI/IMPU	ims.mnc001.mcc505.3gppnetwork.org	IMS domain
scscf_address	S-CSCF name	scscf01.ims.domain or "none"	S-CSCF server address
scscf_domain	S-CSCF domain	ims.domain or "none"	S-CSCF domain
call_forward_all_destination	MMTel CDIV	61403555123 or "none"	CFA destination number
call_forward_not_reachable_destination	MMTel CDIV	2222 or config default	CFNRc destination (voicemail)
no_reply_timer	MMTel CDIV	30 or config default	Timeout before CFNRy activates

Priority: Sh Data vs Configuration Defaults

The TAS uses this priority for call forwarding data:

1. MMTel-Config from Sh (highest priority - subscriber-specific settings)
2. HLR Data from SS7 MAP (overrides Sh for MT calls if roaming/forwarding active)
3. Configuration Defaults (lowest priority - used when no Sh data available)

Example:

# Configuration defaults (used only if Sh returns no MMTel-Config)
config :tas,
  call_forward_not_reachable_destination: "2222",  # Voicemail
  default_no_reply_timer: 30

What Happens When Sh Lookup Fails

Failure Scenarios:

1. Subscriber Not Provisioned in HSS:

   • Sh returns "User Unknown" error
   • hangup_case variable set to "UNALLOCATED_NUMBER"
   • Call rejected with appropriate SIP response

2. HSS Unreachable / Timeout:

   • Sh request times out (default: 5000ms)
   • Error logged and metric recorded
   • Call may be rejected or routed with defaults (deployment-specific)

3. No MMTel-Config in Response:

   • Subscriber exists but has no call forwarding configured
   • Configuration defaults are used for call_forward_not_reachable_destination and no_reply_timer
   • Call proceeds normally with default values

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:

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

Testing Sh Interface

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

1. Navigate to /sh_test in Control Panel
2. Enter subscriber MSISDN (e.g., +61403123456)
3. Click "Query Sh"
4. 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