CAMEL Request Builder

Overview

The CAMEL Request Builder is a LiveView page that builds and sends CAMEL/CAP requests for testing. It provides an interactive UI for creating InitialDP and follow-up CAMEL operations against a connected gsmSSF, and it logs every message to the event log in JSON.

Page title: CAMEL Request Builder Route: /camel_request Access URL: https://your-server:8087/camel_request (HTTPS)

---

Components

CAMEL Request Builder LiveView

SS7.Web.CAMELRequestLive renders the builder. Capabilities:

• Request type dropdown
• Dynamic form fields per request type
• CAP version selector (v1/v2/v3/v4) that overrides the configured default per request
• Collapsible Advanced SCCP/M3UA options (Global Titles, SSNs, OPC/DPC)
• Request history (last 20 requests) including a CAP Ver column
• Session tracking via OTID
• Success/error feedback and request size

Event Log with CAMEL Support

lib/helpers/eventlog.ex provides CAMEL/CAP logging (paklog_camel/2 and helpers that look up CAP opcode names, extract OTID/DTID, and convert CAP PDUs to JSON). CAP operation names come from the module's internal opcode map, which currently contains 34 entries.

A sample of that map:

0  => "initialDP"
1  => "assistRequestInstructions"
5  => "connect"
6  => "releaseCall"
7  => "requestReportBCSMEvent"
8  => "eventReportBCSM"
10 => "continue"
14 => "applyCharging"
15 => "applyChargingReport"
# ... 34 entries total

Opcode caveat: the event-log opcode map and the outbound request generator (cap_request_generator.ex) do not agree on every opcode (for example, the event-log map labels opcode 14 as applyCharging, while the generator emits ApplyCharging as opcode 35). Treat the event-log map as a display/labelling aid for received messages, and treat cap_request_generator.ex as authoritative for what OmniSS7 actually sends. Operations are best identified by name + endpoint, not by a single opcode.

CapClient Logging

CapClient logs both incoming and outgoing CAP messages. Outgoing messages are logged from the SCCP/M3UA maker (paklog_camel(&1, "outgoing")); incoming messages are logged in the payload handler. This shares the event log with MAP events.

---

Configuration

The Request Builder page is registered in config/config.exs (not runtime.exs):

config :control_panel,
  use_additional_pages: [
    {SS7.Web.CAMELSessionsLive, "/camel_sessions", "CAMEL Sessions"},
    {SS7.Web.CAMELRequestLive, "/camel_request", "CAMEL Request Builder"}
  ],
  page_order: [
    # ...
    "/camel_sessions",
    "/camel_request"
  ]

---

Usage

Accessing the Request Builder

1. Navigate to https://your-server:8087/camel_request
2. Select the request type from the dropdown
3. Optionally choose a CAP version (defaults to the configured cap_version)
4. Fill in the required parameters
5. Optionally expand Advanced SCCP/M3UA Options
6. Click Send [RequestType] Request

Request Flow

InitialDP (new call)

1. Set Service Key (e.g. 100)
2. Set Calling Number (A-party) and Called Number (B-party)
3. Send the request — a new OTID is generated and stored in the session for follow-up requests

Follow-up requests (Connect, ReleaseCall, etc.)

These reuse the stored OTID from InitialDP. If no OTID is active, the UI shows a warning and the request is not sent.

Request Types

The builder form offers six request types:

Request type	Parameters
InitialDP	Service Key (integer), Calling Number, Called Number
Connect	Destination Number
ReleaseCall	Cause Code (16 = Normal, 17 = Busy, 31 = Unspecified)
RequestReportBCSMEvent	BCSM events (e.g. oAnswer, oDisconnect)
ApplyCharging	Duration (seconds, 1–864000), Release on Timeout (boolean)
Continue	None (uses the active OTID)

Beyond the form: two further operations exist in the request generator but are not exposed by the builder form — InitialDPSMS (opcode 60, CapRequestGenerator.initial_dp_sms_request/5) for MO-SMS CAMEL control, and NoteMM-Event (MAP opcode 89, CapRequestGenerator.note_mm_event_request/4) for M-CSI mobility notifications. See Additional Operations.

CAP Version Selection

The form includes a CAP version dropdown:

Option	Application-Context OID
CAP v1	0.4.0.0.1.0.50.0
CAP v2 (default)	0.4.0.0.1.0.50.1
CAP v3	0.4.0.0.1.21.3.4
CAP v4	0.4.0.0.1.23.3.4

Selecting a version temporarily overrides the configured default (CAPVersion.set_default_version/1) for the duration of the request, then restores the original. This controls the application-context OID placed in the TCAP dialogue of the outgoing message. The selection persists across form field changes, and the version used is recorded in the request history's CAP Ver column.

Advanced Options

Field	Default	Notes
Called Party GT	68988415011	Destination Global Title
Calling Party GT	(configurable)	Originating Global Title
Called SSN	146	gsmSSF
Calling SSN	146	gsmSSF
OPC	5013	Originating Point Code
DPC	5011	Destination Point Code

---

JSON Logging

Every CAMEL message is logged to the event log in JSON with direction, TCAP action, CAP operation name, SCCP addressing, OTID/DTID, and the full CAP PDU.

Example Log Entry

{
  "map_event": "CAP:initialDP",
  "direction": "outgoing",
  "tcap_action": "Begin",
  "otid": "A1B2C3D4",
  "sccp_called": {
    "SSN": 146,
    "GlobalTitle": {
      "Digits": "55512341234",
      "NumberingPlan": "isdn_tele",
      "NatureOfAddress_Indicator": "international"
    }
  },
  "event_message": "{ ... full CAP PDU ... }"
}

Because logs are emitted as JSON via OmniLogger.JsonFormatter, you can filter CAMEL traffic on the map_event field (prefix CAP:).

---

Request History & Session Tracking

The UI displays the last 20 requests with: timestamp, request type (color-coded badge), OTID (first 8 hex chars), status (sent/error), message size, and the CAP Ver used.

The current-session panel shows the active OTID and the last request size while a session is active.

---

Testing Workflow

1. Start a call — send InitialDP, get an OTID, the system creates a session.
2. Control the call — send RequestReportBCSMEvent, ApplyCharging, Connect, or ReleaseCall against the active OTID.
3. View results — check the request history, the CAMEL Sessions page, and the event log (filter on CAP:).

---

ApplyCharging — Call Duration Control

Overview

ApplyCharging sets a maximum call duration and optionally releases the call when that duration expires. It is typically used for prepaid charging or enforcing time limits.

Parameters

Duration (maxCallPeriodDuration)

• Integer, 1–864000 seconds (e.g. 60 = 1 minute, 300 = 5 minutes, 3600 = 1 hour)

Release on Timeout (releaseIfDurationExceeded)

• Boolean, default true
• true: release/disconnect the call when the duration expires
• false: notify the gsmSCF but keep the call active (allows the gsmSCF to act)

Message Structure

ApplyCharging is sent as a TCAP Continue carrying opcode 35 (the value emitted by cap_request_generator.ex). The argument (ApplyChargingArg) contains:

• aChBillingChargingCharacteristics → timeDurationCharging with maxCallPeriodDuration and the release flag
• partyToCharge (default: sendingSideID / leg1)

Example Usage

1. Send InitialDP (Service Key 100, calling/called numbers) → OTID A1B2C3D4
2. Send ApplyCharging (Duration 300, Release on Timeout true) → uses OTID A1B2C3D4
3. Send Connect (Destination) → uses OTID A1B2C3D4
4. After 300 seconds the network releases the call and the gsmSCF receives a disconnect notification.

Best Practices

1. Send ApplyCharging before Connect so charging is active when the call connects.
2. Pair with RequestReportBCSMEvent (oAnswer/oDisconnect) to track actual duration.
3. Set reasonable durations — typically 60–300 s for prepaid.
4. Handle timeouts gracefully when release=false.

Monitoring

Track ApplyCharging via the request history, the event log (CAP:applyCharging), the CAMEL Sessions page, and the cap_requests_total{operation="apply_charging"} metric.

---

Additional Operations

These operations are implemented in cap_request_generator.ex but are not part of the builder form.

InitialDPSMS (opcode 60)

CapRequestGenerator.initial_dp_sms_request/5 builds an MO-SMS CAMEL trigger sent by the smsSSF to the gsmSCF when an SMS-CSI / mo-sms-CSI is armed, before the short message is relayed to the SMSC.

• Parameters: service key, calling party MSISDN, SM destination, IMSI, SMSC address (optional fields may be nil)
• The InitialDPSMSArg is encoded with the generated CAP ASN.1 module (cap3 smsSSF-gsmSCF)
• The TCAP Begin carries the id-ac-cap3-sms-AC application context

NoteMM-Event (MAP opcode 89)

CapRequestGenerator.note_mm_event_request/4 builds a CAMEL M-CSI mobility notification sent from the VLR to the gsmSCF when an armed mobility event occurs.

• Parameters: service key, mobility event (:location_update_same_vlr, :location_update_other_vlr, :imsi_attach, :ms_initiated_imsi_detach, :network_initiated_imsi_detach), IMSI, MSISDN
• Encoded with the MAP ASN.1 module via :TCAPMessages.encode(:MapSpecificPDUs, …), carrying the mm-EventReporting-v3 application context

NoteMM-Event is a MAP operation, not a CAP operation — it is the one request here that does not use :GenericTCAP.

---

Implementation Details

State Management

• LiveView assigns hold the form state and the active OTID
• Request history is limited to 20 entries
• No auto-refresh — requests are sent manually

Request Generation

• Uses CapRequestGenerator to build TCAP/CAP structures
• CAP requests are encoded with :GenericTCAP.encode(:GenericPDUs, …) (works for both MAP and CAP transport). NoteMM-Event is the exception and uses :TCAPMessages.
• The result is wrapped in SCCP/M3UA via CapClient.sccp_m3ua_maker/2

Sending Mechanism

• Sent over M3UA to the :camelgw_client_asp ASP using routing context 1
• SCCP/M3UA encapsulation is automatic; SSNs default to 146 (gsmSSF)

Error Handling

• Form validation with user feedback
• Graceful handling of a missing OTID
• Parse and encoding errors surfaced in the UI and logs

---

Integration Notes

• Shares the event log with MAP events (paklog)
• Uses the same SCCP/M3UA infrastructure
• Works alongside the CAMEL Sessions page for monitoring
• Integrates with the existing M3UA routing