Appendix B: Billing Payload Definition

This appendix details the standard payload schema and examples.

Billing Payload: JSON Schema for ADD / MOD Subscriber

  {
    "$schema":"http://json-schema.org/V-04/schema#",
    "title":"CRM User Add/Change message v0.12",
    "description":"A JSON definition of a User MACD message for adds and changes as required by the CRM / NORTHBOUND system",
    "type":"object",
    "required":["Order","User"],
    "properties":{
        "Order":{
            "type":"object",
                "required":[
                    "CallbackURL",
                    "MessageID",
                    "Timestamp",
                    "CallingSystem",
                    "UserID",
                    "Operation",
                    "Customer",
                    "Location",
                    "HardwareGroup"
                ],
            "properties":{
                "CallbackURL":{
                    "type":"string",
                    "description":"URL of the callback server"
                },
                "MessageID":{
                    "type":"string",
                    "description":"Unique ID of message from calling system that will be used in responses by the CRM system"
                },
                "Timestamp":{
                    "type":"string",
                    "format":"date-time",
                    "description":"Timestamp set by calling system, typically the system time at message creation"
                },
                "CallingSystem":{
                    "type":"string",
                    "description":"String identifying calling system, could be logical name of system with or without version numbers;
                    used for reports and reconciliation"
                },
                "UserID":{
                    "type":"string",
                    "description":"Login userID of individual making the request on the calling system (or system name if triggered
                    automatically); used for reports and reconciliation and differentiating between internal (Provider) and external
                    (customer) users"
                },
                "CustomerRef":{
                    "type":"string",
                    "description":"Transaction reference optionally provided by customer making the request; used for
                    reports, reconciliation and possibly invoicing"
                },
                "Operation":{
                    "enum":[
                        "Add",
                        "Change"
                    ]
                },
                "Customer":{
                    "type":"string"
                },
                "Location":{
                    "type":"string"
                },
                "HardwareGroup":{
                    "type":"string",
                    "description":"Network Device List in VOSS Automate; Effectively an indicator of which VOSS Automate cluster
                    on which this User is configured. A customer can have multiple NDLs, but a location will only ever
                    be on a single cluster, and have a single NDL."
                },
                "ExternalCustomerID":{
                    "type":"string"
                }
            }
        },
        "User":{
            "type":"array",
            "minItems":1,
            "items":{
                "required":[
                    "Username",
                    "ContactPhone",
                    "ExtensionNumber",
                    "MobilePhone",
                    "FirstName",
                    "LastName",
                    "Email"
                ],
                "properties":{
                    "Username":{
                        "type":"string",
                        "description":"Unique identifier of the user; usually email address, or maybe any other identifier
                        that is meaningful to the Customer"
                    },
                    "ActivationDate":{
                        "type":"string",
                        "format":"date-time"
                    },
                    "ChangeDate":{
                        "type":"string",
                        "format":"date-time"
                    },
                    "DisconnectionDate":{
                        "type":"string",
                        "format":"date-time"
                    },
                    "ContactPhone":{
                        "type":"string"
                    },
                    "ExtensionNumber":{
                        "type":"string"
                    },
                    "MobilePhone":{
                        "type":"string"
                    },
                    "Salutation":{
                        "type":"string"
                    },
                    "FirstName":{
                        "type":"string"
                    },
                    "MiddleName":{
                        "type":"string"
                    },
                    "LastName":{
                        "type":"string"
                    },
                    "Email":{
                        "type":"string"
                    },
                    "Title":{
                        "type":"string"
                    },
                    "EndUserVoicemail":{
                        "type":"boolean"
                    },
                    "Lines":{
                        "type":"array",
                        "minItems":1,
                        "items":{
                            "type":"object",
                            "anyOf":[
                            {
                                "required":[
                                    "ExtensionNumber"
                                ],
                                "properties":{
                                    "ShortNumber":{
                                        "type":"string"
                                    },
                                    "ExtensionNumber":{
                                        "type":"string"
                                    },
                                    "DDI":{
                                        "type":"string"
                                    }
                                }
                            }
                            ]
                        },
                        "uniqueItems":true
                    },
                    "Devices":{
                        "type":[
                            "array",
                            "null"
                        ],
                        "items":{
                            "required":[
                                "Model",
                                "Name"
                            ],
                            "properties":{
                                "Model":{
                                    "type":"string",
                                    "description":"Preconfigured device name within VOSS Automate, e.g. 'Cisco IP Communicator',
                                    '7821 IP Phone', 'One Analogue Gateway port', etc."
                                },
                                "Name":{
                                    "type":"string",
                                    "description":"Unique identifier of the device, e.g. for IP Phone 'SEP'+Mac and for Jabber
                                    Android device 'BOT'+unique string"
                                }
                            }
                        }
                    },
                    "MobilityProfiles":{
                        "type":[
                            "array",
                            "null"
                        ],
                        "items":{
                            "required":[
                                "Model",
                                "Name"
                            ],
                            "properties":{
                                "Model":{
                                    "type":"string",
                                    "description":"Preconfigured device name within VOSS AutomateRed, e.g. 'Cisco IP Communicator',
                                    '7821 IP Phone', 'One Analogue Gateway port', etc."
                                },
                                "Name":{
                                    "type":"string",
                                    "description":"The Device Profile / Mobility Profile name"
                                }
                            }
                        }
                    },
                    "FMC":{
                        "type":[
                            "array",
                            "null"
                        ],
                        "items":{
                            "required":[
                                "MobileNumber",
                                "Extension"
                            ],
                            "properties":{
                                "MobileNumber":{
                                    "type":"string",
                                    "description":"FMC device mobile number"
                                },
                                "Extension":{
                                    "type":"string",
                                    "description":"Extension number linked to FMC Mobile Number"
                                },
                                "MobileBrand":{
                                    "type":"string",
                                    "description":"This is mobile brand – e.g. 'Blackberry' or 'Other Mobile Phone'"
                                },
                                "DataOption":{
                                    "type":"string",
                                    "description":""
                                },
                                "RoamingOption":{
                                    "type":"string",
                                    "description":""
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

Example: JSON Schema for ADD Subscriber

{
 "transactionId": "d8d303e5-781f-445e-a304-71bbfc68ef39",
 "transactionSeqId": "2659147",
 "transactionTimestamp": "2018-08-15T13:10:50.484Z",
 "timestamp": "2018-08-15T13:26:07.540Z",
 "state": "UserProcessed",
 "payload": {
   "MessageID": "5b7429ef90d7eb1e45b49eec",
   "Timestamp": "2018-08-15T13:26:07.542Z",
   "CallingSystem": null,
   "UserID": "rsevenster_csp",
   "Operation": "Create",
   "CustomerRef": null,
   "Customer": "GeoLogic",
   "Location": "GLGC-London",
   "Username": "pfelt",
   "HardwareGroup": "GeoLogic-CL2-NDL",
   "ContactPhone": null,
   "ExtensionNumber": "102108",
   "MobilePhone": null,
   "FirstName": "Peter",
   "MiddleName": null,
   "LastName": "Felt",
   "Title": null,
   "Email": "[email protected]",
   "EndUserVoicemail": true,
   "Devices": [
     {
       "Model": "Cisco 7945",
       "Name": "SEP794500102108"
     }
   ],
   "Lines": [
     {
       "ExtensionNumber": "102108",
       "DDI": "+442074221008"
...NDL",
     "ExternalCustomerID": "GLGC-LO"
   },
   "User": [
     {
       "Username": "pfelt",
       "ActivationDate": "2018-08-15T00:00:00.000Z",
       "ContactPhone": "",
       "ExtensionNumber": "102108",
       "MobilePhone": "",
       "FirstName": "Peter",
       "MiddleName": "",
       "LastName": "Felt",
       "Email": "[email protected]",
       "Title": "",
       "EndUserVoicemail": true,
       "Lines": [
         {
           "ExtensionNumber": "102108",
           "DDI": "+442074221008"
         }
       ],
       "Devices": [
         {
           "Model": "Cisco 7945",
           "Name": "SEP794500102108"
         }
       ],
       "MobilityProfiles": [
         {
           "Model": "Cisco 7945",
           "Name": "pfelt-UDP"
         }
       ]
     }
   ]
 },
 "callback": {
   "MessageID": "5b7429ef90d7eb1e45b49eec",
   "Timestamp": "2018-08-15T13:26:18.499Z",
   "Stage": "ActiveOrder",
   "Status": "Success"
 }

Example: JSON Schema for MOD Subscriber

{
 "transactionId": "85de4176-1d9d-4776-b4bd-d5e592b06088",
 "transactionSeqId": "2680575",
 "transactionTimestamp": "2018-08-16T13:48:39.597Z",
 "timestamp": "2018-08-16T13:49:27.075Z",
 "state": "UserProcessed",
 "payload": {
   "MessageID": "5b7580e790d7eb1e45b49efc",
   "Timestamp": "2018-08-16T13:49:27.077Z",
   "CallingSystem": null,
   "UserID": "hbarton_csp",
   "Operation": "Change",
   "CustomerRef": null,
   "Customer": "GeoLogic",
   "Location": "GLGC-London",
   "Username": "pfelt",
   "HardwareGroup": "GeoLogic-CL2-NDL",
   "ContactPhone": null,
   "ExtensionNumber": "102108",
   "MobilePhone": null,
   "FirstName": "Peter",
   "MiddleName": null,
   "LastName": "Felt",
   "Title": null,
   "Email": null,
   "EndUserVoicemail": true,
   "Devices": [
     {
       "Model": "Cisco 7945",
       "Name": "SEP794500102108"
     }
   ],
   "Lines": [
     {
       "ExtensionNumber": "102108",
       "DDI": "+442074221008"
     }
   ],
   "...Group": "GeoLogic-CL2-NDL",
     "ExternalCustomerID": "GLGC-LO"
   },
   "User": [
     {
       "Username": "pfelt",
       "ChangeDate": "2018-08-16T13:48:39.597Z",
       "ContactPhone": "",
       "ExtensionNumber": "102108",
       "MobilePhone": "",
       "FirstName": "Peter",
       "MiddleName": "",
       "LastName": "Felt",
       "Email": "",
       "Title": "",
       "EndUserVoicemail": true,
       "Lines": [
         {
           "ExtensionNumber": "102108",
           "DDI": "+442074221008"
         }
       ],
       "Devices": [
         {
           "Model": "Cisco 7945",
           "Name": "SEP794500102108"
         }
       ],
       "MobilityProfiles": [
         {
           "Model": "Cisco 7945",
           "Name": "pfelt-UDP"
         }
       ]
     }
   ]
 },
 "callback": {
   "MessageID": "5b7580e790d7eb1e45b49efc",
   "Timestamp": "2018-08-16T13:49:37.661Z",
   "Stage": "ActiveOrder",
   "Status": "Success"
 }

Billing Payload: JSON Schema for DEL Subscriber

 {
   "$schema":"http://json-schema.org/V-04/schema#",
   "title":"CRM User Delete message v0.3",
   "description":"A JSON definition of a MACD message for deletes as required by the CRM / NORTHBOUND system",
   "type":"object",
   "properties":{
      "Order":{
         "type":"object",
         "properties":{
            "CallbackURL":{
                 "type":"string",
                 "description":"URL of the callback server"
             },
            "MessageID":{
               "type":"string",
               "description":"Unique ID of message from calling system that will be used in responses by the CRM system",
               "required":true
            },
            "Timestamp":{
               "type":"string",
               "format":"date-time",
               "description":"Timestamp set by calling system, typically the system time at message creation",
               "required":true
            },
            "CallingSystem":{
               "type":"string",
               "description":"String identifying calling system, could be logical name of system with or without
               version numbers; used for reports and reconciliation",
               "required":true
            },
            "UserID":{
               "type":"string",
               "description":"Login userID of individual making the request on the calling system (or system name
               if triggered automatically); used for reports and reconciliation and differentiating between internal
               (Provider) and external (customer) users",
               "required":true
            },
            "CustomerRef":{
               "type":"string",
               "description":"Transaction reference optionally provided by customer making the request; used for
               reports, reconciliation and possibly invoicing"
            },
            "Operation":{
               "enum":[
                  "Delete"
               ]
            },
            "Customer":{
               "type":"string",
               "required":true
            },
            "Location":{
               "type":"string",
               "required":true
            },
            "HardwareGroup":{
               "type":"string",
               "required":true,
               "description":"Network Device List in VOSS Automate; Effectively an indicator of which VOSS Automate cluster
               on which this User is configured. A customer can have multiple NDLs, but a location will only ever be
               on a single cluster, and have a single NDL."
            },
            "ExternalCustomerID":{
               "type":"string",
               "required":false
            }
         }
      },
      "User":{
         "type":"array",
         "minItems":1,
         "items":[
            {
               "Username":{
                  "type":"string",
                  "description":"Unique identifier of the user; usually email address, or maybe any other identifier
                  that is meaningful to the Customer",
                  "required":true
               },
               "DisconnectionDate":{
                  "type":"string",
                  "format":"date-time"
               }
            }
         ]
      }
   }
}

Example: JSON Schema for DELETE Subscriber

{
 "transactionId": "bee89f13-c772-45c6-b28b-f7be6c570632",
 "transactionSeqId": "2659127",
 "transactionTimestamp": "2018-08-15T13:06:57.596Z",
 "timestamp": "2018-08-15T13:26:03.234Z",
 "state": "UserProcessed",
 "payload": {
   "MessageID": "5b7429eb90d7eb1e45b49ee9",
   "Timestamp": "2018-08-15T13:26:03.234Z",
   "CallingSystem": null,
   "UserID": "hbarton_csp",
   "Operation": "Delete",
   "CustomerRef": null,
   "Customer": "GeoLogic",
   "Location": "GLGC-London",
   "Username": "pfelt",
   "HardwareGroup": "GeoLogic-CL2-NDL",
   "ContactPhone": null,
   "ExtensionNumber": "102108",
   "MobilePhone": null,
   "FirstName": "Peter",
   "MiddleName": null,
   "LastName": "Felt",
   "Title": null,
   "Email": "[email protected]",
   "EndUserVoicemail": true,
   "Devices": [
     {
       "Model": "Cisco 7945",
       "Name": "SEP794500102108"
     }
   ],
   "Lines": [
     {
       "ExtensionNumber": "102108",
       "DDI": "+442074221008"
   ...ate": "2018-08-15T00:00:00.000Z"
 },
 "userId": "5481e2fd46da02148e770b4c",
 "subscriberId": "5b7421072b2c1e0d2c177928",
 "operation": "Delete",
 "activation_state": "Live",
 "GoLiveDate": "2018-08-15T00:00:00.000Z",
 "resubmitPayload": false,
 "order": {
   "Order": {
     "MessageID": "5b7429eb90d7eb1e45b49ee9",
     "CallbackURL": "http://localhost:5009/callback",
     "Timestamp": "2018-08-15T13:26:03.234Z",
     "CallingSystem": "Default",
     "UserID": "hbarton_csp",
     "Operation": "Delete",
     "Customer": "GeoLogic",
     "Location": "GLGC-London",
     "CustomerRef": "GeoLogic-01",
     "HardwareGroup": "GeoLogic-CL2-NDL",
     "ExternalCustomerID": "GLGC-LO"
   },
   "User": [
     {
       "Username": "pfelt",
       "DisconnectionDate": "2018-08-15T13:06:57.596Z"
     }
   ]
 },
 "callback": {
   "MessageID": "5b7429eb90d7eb1e45b49ee9",
   "Timestamp": "2018-08-15T13:26:11.937Z",
   "Stage": "ActiveOrder",
   "Status": "Success"
 }

Billing Call Back: JSON Schema for Response.xml (Callback Payload)

 {
   "$schema": "http://json-schema.org/V-04/schema#",
   "title": "Response message v0.3",
   "description": "A JSON definition of a response",
   "type": "object",
   "properties": {
      "Response": {
         "type": "object",
         "required": [
            "MessageID",
            "Timestamp",
            "Stage",
            "Status"
         ],
         "properties": {
            "MessageID": {
               "type": "string",
               "description": "Unique ID of message from calling system to which this message is a response"
            },
            "OrderID": {
               "type": "string",
               "description": "The Order within which this message was included"
            },
            "Timestamp": {
               "type": "string",
               "format": "date-time"
            },
            "Stage": {
               "enum": [
                  "Parsing",
                  "ActiveOrder",
                  "MobileMigrated",
                  "MobileOrder"
               ]
            },
            "Status": {
               "enum": [
                  "Success",
                  "Warning",
                  "Error"
               ]
            },
            "ResponseText": {
               "type": "string"
            },
            "User": {
               "type": "array",
               "minItems": 0,
               "items":{
                  "type":"object",
                  "title":"User",
                  "required":[
                     "Username",
                     "Status",
                     "ResponseText"
                  ],
                  "properties": {
                     "Username": {
                        "type": "string"
                     },
                     "Status": {
                        "enum": [
                           "Warning",
                           "Error"
                        ]
                     },
                     "ResponseText": {
                        "type": "string"
                     }
                  }
               }
            }
         }
      }
   }
}