Reporting call detail record events from Voice Gateway

Configuring Voice Gateway to publish call detail record events

1. Set up a Splunk HTTP Event Collector (HEC) or a REST server that can store the events, for example in a noSQL database. See Configuring Voice Gateway to publish CDR events in an IBM Cloudant database, if you use one to store your events.

2. In the Voice Gateway configuration, specify your REST server URL and authorization credentials and enable call detail record events by setting the CDR event index value.

   • Single-tenant environment: Set the following environment variables in your configuration.

   REPORTING_URL=http://myresteventserver.ibm.com/
   REPORTING_USERNAME=myRestAdmin
   REPORTING_PASSWORD=myRestTokenOrPassword
   REPORTING_CDR_EVENT_INDEX=cdr
   REPORTING_CDR_EVENT_SOURCE_TYPE=vgwSessionID
   

   • Multi-tenant JSON configuration: In the multi-tenant JSON configuration file, for each tenant where you want to enable call detail record events, configure a reporting object that contains the following properties. You can configure indexes for other types of events, such as transcription or Watson Assistant turn events, within the same object.

   ...
   "reporting": {
     "url": "http://myresteventserver.ibm.com/",
     "username": "myRestAdmin",
     "password": "myRestTokenOrPassword",
     "cdrEventInd": "cdr",
     "cdrEventSourceType" : "vgwSessionID"
   }
   ...
   

   The CDR event index value is included as the index value in all call detail record events so that the REST server that consumes them can differentiate the type of event. The index field is required for Splunk HEC, but it's also useful for anyone who is building their own REST server to handle these events.

Configuring Voice Gateway to publish CDR events in an IBM Cloudant database

Before configuring Voice Gateway to publish to a database, set up an IBM® Cloudant® for IBM Cloud.

Set the following environment variables in your configuration to publish CDR events in an IBM Cloudant database. You can use both IBM Cloudant and another reporting service simultaneously by adding the IBM Cloudant configuration variables to your configuration. You can configure authentication for IBM Cloudant either with an API key by adding the REPORTING_CDR_CLOUDANT_APIKEY variable or by username and password by adding REPORTING_CDR_CLOUDANT_USERNAME and REPORTING_CDR_CLOUDANT_PASSWORD.

The following examples show the configuration for publishing CDR events to IBM Cloudant.

• Single-tenant environment: Set the following environment variables in your configuration.

  REPORTING_CDR_CLOUDANT_URL =http://mycdrcloudant.ibm.com/
  REPORTING_CDR_CLOUDANT_APIKEY=a1b2c3d3fgh1jk1mn0
  REPORTING_CDR_CLOUDANT_USERNAME=myCloudantUsername
  REPORTING_CDR_CLOUDANT_PASSWORD=myCloudantPassword
  REPORTING_CDR_CLOUDANT_DB_NAME=myCloudantDB
  REPORTING_CDR_CLOUDANT_EVENT_INDEX=cdr
  

  If you use non-default account configurations to IBM Cloudant, you might need to include additional environment variables. See REPORTING_CDR_CLOUDANT_URL and REPORTING_CDR_CLOUDANT_ACCOUNT in Reporting event configuration.

• Using multi-tenant JSON configuration: In the multi-tenant JSON configuration file, for each tenant where you want to enable call detail record events, configure a reporting object that contains the following properties. If you use non-default account configurations to IBM Cloudant, you might need to include additional environment variables. See cdrCloudant in Properties for the reporting object.

  ...
  "reporting": {
  "cdrCloudant": {
    "url": "http://mycdrcloudant.ibm.com/",
    "username": "myCloudantUsername",
    "password": "myCloudantPassword",
    "apiKey": "myApiKey",
    "dbName": "myCloudantDB",
    "eventInd": "cdr"
  }
  }
  ...
  

* **Single-tenant environment:** Set the following environment variables in your [configuration](https://www.ibm.com/docs/en/voice-gateway?topic=reference-configuration-environment-variables).
```yaml

  {:codeblock}

  * **Multi-tenant JSON configuration**: You must configure the `url` and `apikey` configuration variables instead of `username` and `password`.

  ```json
...
"reporting": {
  "cdrCloudant": {
    "url": "http://mycdrcloudant.ibm.com/",
    "apikey": "a1b2c3d3fgh1jk1mn0",
    "dbName": "myCloudantDB",
    "eventInd": "cdr"
  }
}
...

{:codeblock}

Configuring Voice Gateway to publish CDR events in a CouchDB

To set up CouchDB, clone the repository and follow the instructions on GitHub. If you use CouchDB, you can't use an API key to authenticate.

Set the following environment variables in your configuration to publish CDR events in an IBM Cloudant database. You can use both IBM Cloudant and another reporting service simultaneously by adding the IBM Cloudant configuration variables to your configuration.

The following examples show the configuration for publishing CDR events to CouchDB.

• Single-tenant environment: Set the following environment variables in your configuration.

REPORTING_CDR_CLOUDANT_URL="http://<svc-couchdb>:5984/"
REPORTING_CDR_CLOUDANT_USERNAME=myCouchDBUsername
REPORTING_CDR_CLOUDANT_PASSWORD=myCouchDBPassword
REPORTING_CDR_CLOUDANT_DB_NAME=myCouchDB
REPORTING_CDR_CLOUDANT_EVENT_INDEX=cdr

• Using multi-tenant JSON configuration: In the multi-tenant JSON configuration file, for each tenant where you want to enable call detail record events, configure a reporting object that contains the following properties. If you use non-default account configurations to IBM Cloudant, you might need to include additional environment variables. See cdrCloudant in Properties for the reporting object.

...
"reporting": {
  "convCloudant": {
    "url": "http://<svc-couchdb>:5984/",
    "username": "myCouchDBUsername",
    "password": "myCouchDBPassword",
    "dbName": "myCouchDB",
    "eventInd": "cdr"
  }
}
...

Call detail record event format

Call detail record events contain summary information about a single call. The event format is based on the Splunk HTTP Event Controller JSON format.

{
"time": 1434567892,
"host": "vgw123.ibm.com",
"source": "18595552498",
"sourcetype": "e164",
"index": "cdr",
"event": {
  "version": "1.0",
  "sipCallID": "b742193386876548a69fe1420c33998b@0.0.0.0",
  "globalSessionID": "b742193386876548a69fe1420c33998b@0.0.0.0",
  "initTime": 1520877996309,
  "startTime": 1520877998461,
  "stopTime": 1520878020781,
  "setupTime": 2152,
  "callLength": 22320,
  "sipToURI": "sip:+18445555174@169.46.147.46",
  "sipFromURI": "sip:+18595553171@vgwdemo.pstn.twilio.com",
  "maxSTTTransaction": 1212,
  "endReason": "failed",
  "failureDetails": "details on why call failed",
  "failureOccurred": true,
  "echoDetected": false,
  "transferTarget": "sip or tel URI",
  "conversations": [
    {
      "id": "1233",
      ...
    }
  ],
  "warnings": [
    {
      ...
    }
   ],
  "rtpNetworkSummary": {
     ...
  }
}
}

{
"time": 1434567892,
"host": "vgw123.ibm.com",
"source": "18885553333",
"sourcetype": "e164",
"index": "cdr",
"event": {
  "version": "1.0",
  "sipCallID": "b742193386876548a69fe1420c33998b@0.0.0.0",
  "globalSessionID": "b742193386876548a69fe1420c33998b@0.0.0.0",
  "initTime": 1520877996309,
  "startTime": 1520877998461,
  "stopTime": 1520878020781,
  "setupTime": 2152,
  "callLength": 22320,
  "sipToURI": "sip:+18445555174@169.46.147.46",
  "sipFromURI": "sip:+18595553171@vgwdemo.pstn.twilio.com",
  "numberOfBargeins": 0,
  "maxConvTransaction": 1447,
  "maxTTSTransaction": 616,
  "endReason": "failed",
  "failureDetails": "details on why call failed",
  "failureOccurred": true,
  "echoDetected": false,
  "transferTarget": "sip or tel URI",
  "customCDRData" :  {
    "key1": "value1",
    "key2": "value2"
  },
  "conversations": [
    {
      "id": "1233",
      ...
    }
  ],
  "warnings": [
    {
      ...
    }
   ],
  "rtpNetworkSummary": {
     ...
  }
}
}

"warnings": [
 {
   "timestamp": "2018-02-08T13:03:01Z",
   "message": "CWSMR0032W: A Watson Speech to Text final utterance has a confidence score of 0.1, which does not meet the confidence score threshold of 0.2. The utterance will be ignored.",
   "id": "CWSMR0032W"
 },
 {
   "timestamp": "2018-02-08T13:10:01Z",
   "message": "CWSMR0031W: The synthesis stream from the Watson Text To Speech service can't keep up with the playback rate to the caller, so audio might skip. transaction ID=a1b2c3d4e5",
   "id": "CWSMR0031W"
 }
]

"rtpNetworkSummary": {
  "inboundStream": {
      "maxJitter": 5,
      "averageJitter": 1,
      "packetsLost": 0,
      "totalPackets": 1000,
      "canonicalName": "user@example.com",
      "toolName": "User SIP Phone"
   },
  "outboundStream": {
      "maxJitter": 5,
      "averageJitter": 1,
      "packetsLost": 0,
      "totalPackets": 2000,
      "canonicalName": "voice.gateway@127.0.0.1",
      "toolName": "IBM Voice Gateway/1.0.0.5"
   }
}

Injecting custom values into call detail record events

By including the vgwActAddCustomCDRData to your Watson Assistant dialog or SOE, you can add custom data to your Call Detail Records. You can record data related to various activities that are happening during a call. This includes ways to identify completion of specific tasks.

{
  "command": "vgwActAddCustomCDRData",
  "parameters": {
    "key1": "value1",
    "key2": "value2"
  }
}

When generating a CDR report, the custom data is included in the customCDRData field. For example, in the following CDR report, the key1 and key2 are added to the customCDRData field.

{
"time": 1434567892,
"host": "vgw123.ibm.com",
"source": "18881112222",
"sourcetype": "e164",
"index": "cdr",
"event": {
  ...
  "customCDRData" :  {
    "key1": "value1",
    "key2": "value2"
  },
  "conversations": [
    {
      "id": "1234",
      ...
    }
  ]
}
}

{
  "command": "vgwActAddCustomCDRData",
  "parameters": {
    "key1": "value1",
    "key2": "value2"
  }
}

{
  "command": "vgwActAddCustomCDRData",
  "parameters": {
    "key1": "value11",
    "key3": "value3"
  }
}

{
"time": 1434567892,
"host": "vgw123.ibm.com",
"source": "18595552498",
"sourcetype": "e164",
"index": "cdr",
"event": {
  ...
  "customCDRData" :  {
    "key1": "value11",
    "key2": "value2",
    "key3": "value3"
  },
  "conversations": [
    {
      "id": "1233",
      ...
    }
  ]
}
}

{
  "command": "vgwActAddCustomCDRData",
  "parameters": {
    "key1": ""
  }
}