Skip to main content

Service Hierarchies

Audience: Administrators, Catalog Managers Last Updated: 2026-01-29 Phase: 41-D-01 (Service Hierarchy Documentation)

Overview​

Service hierarchies define parent/child relationships between services, enabling complex service bundles and automatic lifecycle management. When you configure service offerings in Staqr, understanding hierarchies ensures customers receive complete, functional service bundles.

Why Hierarchies Matter:

  • Complete Service Bundles: Mobile plans automatically include SIM + Number + Data
  • Lifecycle Management: Terminate parent service → children terminate automatically
  • Business Logic: Internet service with Static IP requires NBN Access
  • User Experience: Customers can't activate incompatible services

Key Concepts​

Parent and Child Services​

Parent Service (Root): The primary subscription service customers purchase

  • Examples: Mobile Base, NBN Base, VoIP Base
  • Role: PRIMARY
  • Billing: Creates billable subscription

Child Services: Services added to parent service

  • Examples: SIM, MSISDN, Data Allowance, Voicemail
  • Roles: INVENTORY, ADDON, REGISTRY
  • Billing: May be included or charged separately

Rule: Child services CANNOT exist without parent service.

Inclusion Types​

MANDATORY: Child service always included with parent (automatic activation)

  • Example: Mobile service MUST have SIM + MSISDN
  • User Control: None (automatically added)
  • Billing: Typically included in base price

OPTIONAL: Child service user chooses to include (manual activation)

  • Example: Voicemail, Static IP, International Roaming
  • User Control: Full control (customer decides)
  • Billing: Usually additional charge

CONFIGURABLE: Child service added based on business rules (rule-based)

  • Example: Premium MSISDN tiers (Gold, Silver, Standard)
  • User Control: System-determined eligibility
  • Billing: Varies by rule

Service Roles​

PRIMARY: Root subscription service

  • Characteristics: No parent, creates billing account
  • Examples: Mobile Base, NBN Base, VoIP Base

INVENTORY: Allocates physical/logical resource

  • Characteristics: Requires inventory pool (MSN, SIM, Modem)
  • Examples: MSISDN, SIM Card, Modem, Device

ADDON: Adds functionality/capacity

  • Characteristics: No inventory requirement
  • Examples: Data Allowance, Voicemail, Call Features

REGISTRY: Regulatory/compliance tracking

  • Characteristics: Compliance tracking (IPND, TESA)
  • Examples: Number Registry (AU IPND, NZ TESA)

Service Hierarchies by Type​

Mobile Service Hierarchy​

Root Service: Mobile Base Service

MANDATORY Children (Always Included):

  1. MSISDN (Standard) - Phone number (INVENTORY)
  2. SIM Card (Physical) - SIM card for device (INVENTORY)
  3. Data Allowance (25GB) - Base data plan (ADDON)

OPTIONAL Children (User Chooses):

  • Voicemail Service (ADDON)
  • Voice Bundle - Extra minutes (ADDON)
  • Messaging Service - SMS/MMS (ADDON)
  • International Roaming (ADDON)
  • Data Bundle - Additional data (ADDON)
  • Number Registry - IPND/TESA compliance (REGISTRY)
  • Premium MSISDN (Gold/Silver) - Upgrade from Standard (INVENTORY)
  • eSIM - Alternative to Physical SIM (INVENTORY)
  • Device Handset - Mobile phone hardware (INVENTORY)
  • Device Tablet - Tablet hardware (INVENTORY)

Visual Hierarchy:

Mobile Base Service
├── MSISDN (Standard) [MANDATORY]
├── SIM Card (Physical) [MANDATORY]
├── Data Allowance (25GB) [MANDATORY]
├── Voicemail [OPTIONAL]
├── Voice Bundle [OPTIONAL]
├── Messaging [OPTIONAL]
├── International Roaming [OPTIONAL]
├── Data Bundle [OPTIONAL]
├── Number Registry (AU IPND) [OPTIONAL]
├── Number Registry (NZ TESA) [OPTIONAL]
├── MSISDN (Gold) [OPTIONAL - Alternative]
├── MSISDN (Silver) [OPTIONAL - Alternative]
├── SIM Card (eSIM) [OPTIONAL - Alternative]
├── Device Handset [OPTIONAL]
└── Device Tablet [OPTIONAL]

Configuration Notes:

  • Only ONE MSISDN tier active (Standard OR Gold OR Silver)
  • Only ONE SIM type active (Physical OR eSIM, initially)
  • Number Registry requires active MSISDN service

Internet Service Hierarchy​

Root Service: NBN Base Service

MANDATORY Children (Always Included):

  1. NBN Access - Network connectivity (ADDON)
    • NBN AVC - Access Virtual Circuit (ADDON, nested under NBN Access)
  2. Data Allowance (100GB) - Base data plan (ADDON)

OPTIONAL Children (User Chooses):

  • Device Modem - Modem rental (INVENTORY)
  • Static IP - Static IPv4 address (ADDON)
  • Speed Boost - Temporary speed enhancement (ADDON)
  • Priority Support - Premium support tier (ADDON)

Alternative Data Tiers (Choose ONE):

  • Data Allowance (Unlimited) - Alternative to 100GB
  • Data Allowance (50GB) - Lower tier
  • Data Allowance (250GB) - Higher tier

Visual Hierarchy (Nested Structure):

NBN Base Service
├── NBN Access [MANDATORY]
│   └── NBN AVC [MANDATORY - NESTED]
├── Data Allowance (100GB) [MANDATORY]
├── Device Modem [OPTIONAL]
├── Static IP [OPTIONAL]
├── Speed Boost [OPTIONAL]
├── Priority Support [OPTIONAL]
├── Data Allowance (Unlimited) [OPTIONAL - Alternative]
├── Data Allowance (50GB) [OPTIONAL - Alternative]
└── Data Allowance (250GB) [OPTIONAL - Alternative]

Configuration Notes:

  • NBN AVC is child of NBN Access (nested hierarchy, 3 levels deep)
  • Only ONE data tier active (100GB OR Unlimited OR 50GB OR 250GB)
  • Static IP requires NBN Access to be active

KEY DIFFERENCE: Internet hierarchy is NESTED (NBN Access → NBN AVC), while Mobile is flat.

VoIP Service Hierarchy​

Root Service: VoIP Base Service

MANDATORY Children (Always Included):

  1. VoIP Number - VoIP phone number (INVENTORY)
  2. VoIP Data - VoIP calling plan (ADDON)

OPTIONAL Children (User Chooses):

  • Device ATA - Analog Telephone Adapter (INVENTORY)
  • Voicemail - Voicemail service (ADDON)
  • Call Forwarding - Call forwarding feature (ADDON)
  • Call Waiting - Call waiting feature (ADDON)
  • SIP Trunk - SIP trunk for business (ADDON)
  • Auto Attendant - Automated call routing (ADDON)
  • Call Recording - Call recording service (ADDON)

Visual Hierarchy:

VoIP Base Service
├── VoIP Number [MANDATORY]
├── VoIP Data [MANDATORY]
├── Device ATA [OPTIONAL]
├── Voicemail [OPTIONAL]
├── Call Forwarding [OPTIONAL]
├── Call Waiting [OPTIONAL]
├── SIP Trunk [OPTIONAL]
├── Auto Attendant [OPTIONAL]
└── Call Recording [OPTIONAL]

Landline Service Hierarchy​

Root Service: Landline Base Service

MANDATORY Children (Always Included):

  1. Landline Number - Landline phone number (INVENTORY)

OPTIONAL Children (User Chooses):

  • Landline Features - Call features bundle (ADDON)
  • Caller ID - Caller ID display (ADDON)
  • Voicemail - Voicemail service (ADDON)
  • Call Forwarding - Call forwarding feature (ADDON)
  • Call Return - Call return (*69) (ADDON)
  • Three-Way Calling - Three-way calling (ADDON)

Visual Hierarchy:

Landline Base Service
├── Landline Number [MANDATORY]
├── Landline Features [OPTIONAL]
├── Caller ID [OPTIONAL]
├── Voicemail [OPTIONAL]
├── Call Forwarding [OPTIONAL]
├── Call Return [OPTIONAL]
└── Three-Way Calling [OPTIONAL]

Configuring Service Hierarchies​

Step 1: Define Parent Service​

Navigate to Admin Console → Catalog → Service Templates

  1. Create or select parent service (e.g., "Mobile Base Service")
  2. Set Service Role: PRIMARY
  3. Set Parent Service: None (PRIMARY services are always root)
  4. Save service template

Step 2: Define Child Services​

For each child service:

  1. Create or select child service (e.g., "MSISDN Standard")
  2. Set Service Role: INVENTORY, ADDON, or REGISTRY
  3. Set Parent Service: Select parent (e.g., "Mobile Base Service")
  4. Set Inclusion Type: MANDATORY, OPTIONAL, or CONFIGURABLE
  5. Set Sort Order: Number determining display order (lower = first)
  6. Save service template

Step 3: Configure Eligibility Constraints (Optional)​

Navigate to Admin Console → Catalog → Eligibility Constraints

Create REQUIRES constraint (dependency):

  • Service: Child service requiring dependency (e.g., "Static IP")
  • Constraint Type: REQUIRES
  • Target Service: Required service (e.g., "NBN Access")
  • Error Message: "Static IP requires NBN Access service."

Create EXCLUDES constraint (mutual exclusivity):

  • Service: First service (e.g., "MSISDN Gold")
  • Constraint Type: EXCLUDES
  • Target Service: Conflicting service (e.g., "MSISDN Silver")
  • Error Message: "Cannot have multiple MSISDN tiers. Choose Gold OR Silver."

Step 4: Test Service Activation​

  1. Navigate to CRM → Customers
  2. Select test customer
  3. Click Add Service
  4. Select parent service (e.g., "Mobile Base Service")
  5. Verify MANDATORY children auto-populate
  6. Add OPTIONAL children as needed
  7. Verify eligibility constraints enforced (e.g., cannot add conflicting services)
  8. Activate service
  9. Verify children activated correctly

Best Practices​

DO: Configure Complete Hierarchies​

✅ Ensure all MANDATORY children defined for PRIMARY services ✅ Mobile MUST have MSISDN + SIM + Data ✅ Internet MUST have NBN Access + NBN AVC + Data ✅ Test activation flows to verify completeness

DO: Use Consistent Sort Order​

✅ MANDATORY services: Sort order 1-10 ✅ OPTIONAL services: Sort order 11+ ✅ Alternative/configurable services: Sort order 20+ ✅ Maintain consistent patterns across service types

DO: Configure Mutual Exclusivity​

✅ MSISDN tiers: Gold EXCLUDES Silver/Standard ✅ SIM types: Physical EXCLUDES eSIM ✅ Data tiers: 100GB EXCLUDES Unlimited/50GB/250GB ✅ Create symmetric constraints (A EXCLUDES B, B EXCLUDES A)

DO NOT: Create Orphaned Services​

❌ NEVER create INVENTORY/ADDON/REGISTRY services without parent ❌ Users cannot activate services without valid parent ❌ Use Role=PRIMARY for root services ONLY

DO NOT: Break Nested Hierarchies​

❌ NBN AVC MUST be child of NBN Access (not NBN Base) ❌ Respect existing nested structures ❌ Test thoroughly before modifying nested hierarchies

Troubleshooting​

Issue: Child Service Not Activating​

Symptom: MANDATORY child service not automatically activated with parent

Diagnosis:

  1. Check Inclusion Type = MANDATORY
  2. Verify Parent Service Template ID set correctly
  3. Check service activation logs for errors

Solution:

  1. Navigate to Admin Console → Catalog → Service Templates
  2. Edit child service
  3. Verify Parent Service = correct parent
  4. Verify Inclusion Type = MANDATORY
  5. Save and retry activation

Issue: Cannot Add Optional Service​

Symptom: "Service not eligible" error when adding optional service

Diagnosis:

  1. Check eligibility constraints (REQUIRES, EXCLUDES)
  2. Verify parent service type matches requirement
  3. Check for conflicting services already active

Solution:

  1. Navigate to Admin Console → Catalog → Eligibility Constraints
  2. Review constraints for failing service
  3. If REQUIRES constraint: Activate required service first
  4. If EXCLUDES constraint: Terminate conflicting service
  5. Retry activation

Issue: Internet Service Won't Activate (NR_* Fields Required)​

Symptom: Internet activation fails with "NR_MSISDN required" error

Diagnosis: Legacy Number Registry global custom fields still active

Solution:

  1. FIXED in Phase 41-C-01: Number Registry global custom fields removed
  2. If error persists: Contact Staqr support (should not occur after Phase 41)
  3. Verification: Internet services should activate WITHOUT NR_* fields

Decision Tree Guides​

Use these interactive guides when configuring new services:

Reference & Troubleshooting​

For Developers​

For Operations​

Other Resources​

Need Help?

Contact Staqr Support: support@privdr.com