Carrier Service Mappings

Configure how Staqr ServiceTemplates map to carrier-specific Product Plan Codes (PPCs) for provisioning operations.

Overview

What is a Carrier Mapping?

A carrier mapping links a vendor-agnostic ServiceTemplate to a carrier-specific Product Plan Code. This enables Staqr to provision the same service to multiple carriers using their respective provisioning codes.

Use Cases:

• Map new ServiceTemplates to Optus, Telstra, or Vodafone PPCs
• Configure multi-carrier service offerings
• Update PPC mappings when carriers change codes
• Define Optus bundle hierarchy (parent/child PPCs)

Access the Carrier Mappings UI

1. Navigate to Catalog in the main navigation
2. Select Service Templates
3. Click on a ServiceTemplate to open the Service Configurator
4. Select the Carrier Mappings tab (10th tab)

tip

The Carrier Mappings tab is only visible when viewing a ServiceTemplate. You must select a service first.

Understanding the Interface

Mappings Table

The mappings table displays all carrier mappings for the selected ServiceTemplate:

Column	Description
Carrier	Carrier identifier (Optus, Telstra, Vodafone, etc.)
Product Plan Code	Carrier-specific PPC for provisioning
Type	Product type classification (Speech, GPRS, etc.)
Hierarchy	For Optus: Parent, Child, or Shared badge
Parent PPC	For Optus child PPCs: the parent PPC reference
Actions	Edit and Delete buttons

Carrier Filter

Use the carrier dropdown filter to show only mappings for a specific carrier:

• All Carriers - Show all mappings
• Optus - Show only Optus mappings
• Telstra - Show only Telstra mappings
• Vodafone - Show only Vodafone mappings
• Vocus - Show only Vocus mappings
• One.NZ - Show only One.NZ mappings

Create a Carrier Mapping

1. Click the Add Mapping button in the toolbar
2. Fill in the required fields:
   • Code: Unique identifier (e.g., MAP_OPTUS_VRP1_010011)
   • Carrier Code: Select the carrier from dropdown
   • Product Plan Code: Enter the carrier's PPC
   • Product Type: (Optional) Classification like Speech, GPRS
3. For Optus mappings, configure hierarchy:
   • Pass Code: 0=shared, 1=parent, 2=child
   • Is Parent PPC: Check for parent PPCs
   • Parent PPC Code: Required for child PPCs
4. Click Save

Optus Hierarchy Configuration

For Optus bundles (like VRP1), PPCs have a parent/child relationship:

Parent PPC (Speech):

• Pass Code: 1
• Is Parent PPC: Checked
• Parent PPC Code: Leave empty

Child PPC (GPRS, SMS, etc.):

• Pass Code: 2
• Is Parent PPC: Unchecked
• Parent PPC Code: Enter parent's PPC (e.g., 010011)

Shared PPC (no hierarchy):

• Pass Code: 0 (or leave empty)
• Is Parent PPC: Unchecked
• Parent PPC Code: Leave empty

Edit a Carrier Mapping

1. Find the mapping in the table
2. Click the Edit (pencil) icon
3. Modify the fields as needed
4. Click Save

caution

Changing the Product Plan Code may affect existing provisioning operations. Verify with carrier documentation before making changes.

Delete a Carrier Mapping

1. Find the mapping in the table
2. Click the Delete (trash) icon
3. Confirm the deletion in the dialog

warning

Deleting a mapping removes the carrier integration for this service. Ensure no active subscriptions depend on this mapping before deleting.

Field Reference

Field	Description	Required	Example
Code	Unique business identifier	Yes	MAP_OPTUS_VRP1_010011
Description	Human-readable description	No	"Optus VRP1 Speech PPC"
Carrier Code	Carrier identifier	Yes	optus
Product Plan Code	Carrier-specific PPC	Yes	010011
Product Type	Product classification	No	Speech
Usage ID	CDR usage identifier	No	VRP1_SPEECH
Pass Code	Optus hierarchy (0/1/2)	No	1
Is Parent PPC	Parent PPC flag	No	true
Parent PPC Code	Parent reference	Conditional*	010011
Network Config	JSON metadata	No	{"timeout": 30000}

*Required when Pass Code = 2 (child PPC) for Optus

Validation Rules

The system enforces these validation rules:

1. Unique Code: Each mapping must have a unique code across all mappings
2. Unique Carrier + PPC: A carrier can only have one mapping per PPC
3. ServiceTemplate Exists: The ServiceTemplate must exist before creating mappings
4. Optus Hierarchy: Child PPCs (passCode=2) must have a parentPpcCode

Troubleshooting

"Entity already exists" Error

Cause: A mapping with this code or carrier+PPC combination already exists.

Resolution:

1. Search for existing mappings with the same carrier and PPC
2. Edit the existing mapping instead of creating a new one

"Missing parameter: parentPpcCode" Error

Cause: Creating an Optus child PPC (passCode=2) without specifying the parent.

Resolution:

1. Enter the parent PPC code in the Parent PPC Code field
2. Ensure the parent PPC mapping exists first

"ServiceTemplate not found" Error

Cause: The ServiceTemplate code doesn't exist in the catalog.

Resolution:

1. Verify the ServiceTemplate exists in Catalog > Service Templates
2. Create the ServiceTemplate first, then create mappings

Mapping Not Showing in Table

Cause: Filter may be active for a different carrier.

Resolution:

1. Check the carrier filter dropdown
2. Select "All Carriers" to see all mappings

Best Practices

1. Naming Convention: Use consistent code format like MAP_{CARRIER}_{SERVICE}_{PPC}
2. Create Parent First: For Optus bundles, create parent PPC before children
3. Document PPCs: Add descriptions explaining what each PPC is for
4. Test Mappings: After creating mappings, verify provisioning works in test environment
5. Carrier Documentation: Keep carrier PPC documentation updated alongside mappings

Related Topics

• Service Templates - Managing vendor-agnostic services (see Catalog > Service Templates in UI)
• Carrier Bundles - Grouping PPCs into bundles (see Carrier Service Mapping API)
• Provisioning Operations - Using mappings in provisioning workflows