Event REST APIs

The event APIs include the messaging and elements to return events and notifications in the Event Repository and the event database for subscriptions, groups, and users.

If recent EDRs are not loaded into the Event Repository yet, the event APIs search for EDRs in the Event database and in-progress aggregated events in the Activity database. The APIs combine the search results to offer a unified, real-time view of all available events. In addition to queries for specific subscriptions and groups, a general Event Repository API queries events in the Event Repository by event type (eventTypes) and event time range (eventTimeLowerBound). This API can be used to query events for information such as all subscriptions that have been suspended in the past week or all catalog item cancelations that occurred today. Query by EventId to search the MATRIXX in-memory database and the Event Repository for primary events and balance impacts recorded in associated secondary events.
Note:

The CurrentBalanceAmount of an updated balance in an event is returned in the API output if the events in the Event Repository were loaded from a Streamed Event File (SEF).

If the source of an event in the query result is from the MATRIXX in-memory database, or if an event fetched from the Event Repository was not originally loaded from SEFs, then the following fields in the event query result are not set.
  • MtxBalanceImpactInfo.CurrentBalanceAmount
  • MtxBalanceUpdate.GrossAmountBefore
  • MtxBalanceUpdate.GrossAmountAfter
Important: The RS Gateway must be configured to connect to the Event Repository. See the related task about connecting to the Event Repository.

Event Query Optional Parameters

You can use the following optional parameters to filter event query results.
Table 1. Event Query Optional Parameters
Parameter Type Description Usage
resultSize Unsigned int32 The maximum number of events to return. Set to 0 to return all the events in the query result. If you do not specify the resultSize, the default number of events (1000) is returned. (To change the default number, edit the defaultResultSize property in the rsgateway.yaml file.)
Note: If the defaultResultSize property in the /opt/mtx/conf/rsgateway.yaml file is not set, all events in the query result are returned.
 Optional
eventTimeLowerBound MtxTimestamp Specifies the lower bound of the delivery time range used to filter the query results. Events whose event time is greater than or equal to the lower bound are returned. The timestamp format is yyyy-MM-ddTHH:mm:ss[+|-|Z][HH:mm].
Note: This is a required field for the GET /eventstore/query API.
Required
eventTimeUpperBound MtxTimestamp Specifies the upper bound of the delivery time range used to filter the query results. Events whose event time is less than the upper bound are returned. The timestamp format is yyyy-MM-ddTHH:mm:ss[+|-|Z][HH:mm]. Optional
eventTypes String Events whose event type prefix matches the specified types are returned. Separate event types with a comma with no space between event types. If not specified, all event types are returned.
The EventTypeArray in the MtxPrimaryEvent MDC defines the event type that was initiated, representing it numerically in the MDC as an array of strings such as "4", "1.2", or "1.3.5". The top-level event types are:
  • ROOT = 0
  • USAGE = 1
  • RECURRING = 2
  • FIRST_USAGE = 3
  • PURCHASE = 4
  • CANCEL = 5
  • BALANCE_ADJUST = 6
  • BALANCE_TOPUP = 7
  • SUSPEND = 9
  • RESUME = 10
  • SESSION_END = 11
  • WRITE_OFF = 12
  • NOTIFICATION_DONE = 13
  • OBJECT_CREATE = 14
  • STATUS_CHANGE = 15
  • USAGE_REFUND = 16
  • OBJECT_DELETE = 18
  • BALANCE_TRANSFER = 19
  • BALANCE_ROLLOVER = 20
  • ROLLOVER_BALANCE_ADJUST = 21
  • SESSION_CONTEXT_END = 22
  • FORFEITURE = 23
  • PAYMENT_AUTHORIZATION = 24
  • PAYMENT_SETTLEMENT = 25
  • AUTO_RENEW = 26
  • PAYMENT = 27
  • POLICY_SESSION_START = 28
  • POLICY_CHANGE = 29
  • RECHARGE = 30
  • TRANSFER_TO_BILLED_AR = 31
  • BILLING_CYCLE_CHANGE = 32
  • PERIOD_TERMINATION = 33
  • SUBSCRIBER_ADD_DEVICE = 34
  • SUBSCRIBER_REMOVE_DEVICE = 35
  • GROUP_ADD_MEMBERSHIP = 36
  • GROUP_REMOVE_MEMBERSHIP = 37
  • REFUND = 38
  • PAYMENT_REFUND = 39
  • PERIOD_WRITE_OFF = 40
  • PURCHASED_ITEM_CYCLE_CHANGE = 41
  • RECHARGE_REQUEST = 42
  • PURCHASED_ITEM_ACTIVATION = 43
  • BALANCE_THRESHOLD = 44
  • PURCHASED_ITEM_TRANSITION_TO_INACTIVE = 45
  • METER_PERIOD_CLOSE = 46
  • CONTRACT_LATE_CHARGE = 47
  • FINANCE_CONTRACT_PRINCIPAL_PAYMENT = 48
  • MISSED_CONTRACT_CHARGE = 49
  • CONTRACT_FINANCE = 50
  • CONTRACT_DEBT_PAYMENT = 51
  • PURCHASED_ITEM_MODIFY = 52
  • COMPONENT_METER_PERIOD_CLOSE = 53
  • SUBSCRIPTION_MODIFY = 54
  • GROUP_MODIFY = 55
  • USER_MODIFY = 56
  • DEVICE_MODIFY = 57
  • SUBSCRIPTION_CREATE = 58
  • GROUP_CREATE = 59
  • DEVICE_CREATE = 60
  • USER_CREATE = 61
  • SUBSCRIPTION_DELETE = 62
  • GROUP_DELETE = 63
  • DEVICE_DELETE = 64
  • USER_DELETE = 65
  • COMPONENT_METER_SUBPERIOD_CLOSE = 66
  • CYCLE_ARREARS_RECURRING = 67
  • DEBT_PAYMENT = 71
  • PURCHASED_ITEM_STATUS_CHANGE = 72
  • FEE_CHARGE = 73
  • EXTERNAL_PAYMENT_REQUEST = 74
  • EXTERNAL_PAYMENT = 75
  • PERIOD_END_TIME_CHANGE = 76
  • SESSION_MONITOR = 77
  • EXTERNAL_PAYMENT_FAILURE = 78
  • PURCHASE_FAILURE = 79
  • PURCHASED_ITEM_ACTIVATION_FAILURE = 80
  • RECURRING_FAILURE = 81
  • USAGE_FAILURE = 82
  • BALANCE_TRANSFER_FAILURE = 83
  • PURCHASE_PACKAGE_MODIFY = 84
  • BALANCE_THRESHOLD_MODIFY = 85
  • POLICY_SESSION_END = 86
  • ROAMING_POLICY_SESSION_START = 87
  • ROAMING_POLICY_CHANGE = 88
  • ROAMING_POLICY_SESSION_END = 89
  • PURCHASED_ITEM_PERIOD_CLOSING = 90
  • PURCHASED_ITEM_CLOSE = 91
  • DYNAMIC_BALANCE_INSTANCE_CREATE = 92
  • RECURRING_RECHARGE_RETRY_FAILURE = 93
  • IMPORT_WAKE = 94
Note: This is an optional field. However, for the GET /eventstore/query API only, this is a required field.
Required
EventTypeArray Array of String Events whose event type prefix matches one of the specified types will be returned. Event types are like "4", "1.2", or "1.3.5". Optional
searchInMemoryDatabase Boolean Specifies whether to search the in memory database. Default is true. Optional
tenantId String This is an optional parameter for Event Repository queries in multi-tenant environments. The tenantId parameter specifies which tenant Event Repository to search for events. If a tenantId is not specified, the base Event Repository is used to search for events. The following APIs accept this parameter:
  • /eventstore/notification/EventId/{EventId:.*}
  • /eventstore/query/EventId/{EventId:.*}tenantId
  • /eventstore/query

For example: /eventstore/query/EventId/ID1,ID2?tenantId=tenant1

 Optional
TrafficRouteData String Optional routing data used by the TRA to route this call to the correct engine. MATRIXX Support recommends that you use this parameter in multi-tenant queries. Optional

Notification Query Optional Parameters

You can use the following optional parameters to filter notification query results.
Table 2. Notification Query Optional Parameters
Parameter Type Description Usage
resultSize Unsigned int32 The maximum number of events to return. Set to 0 to return all the events in the query result. If you do not specify the resultSize, the default number of events (1000) is returned. (To change the default number, edit the defaultResultSize property in the rsgateway.yaml file.)
Note: If the defaultResultSize property in the rsgateway.yaml file is not set, all events in the query result are returned.
 Optional
eventTimeLowerBound MtxTimestamp Specifies the lower bound of the delivery time range used to filter the query results. Notifications whose delivery time is greater than or equal to the lower bound are returned. The timestamp format is yyyy-MM-ddTHH:mm:ss[+|-|Z][HH:mm]. Required
eventTimeUpperBound MtxTimestamp Specifies the upper bound of the delivery time range used to filter the query results. Notifications whose delivery time is less than the upper bound are returned. The timestamp format is yyyy-MM-ddTHH:mm:ss[+|-|Z][HH:mm]. Optional
notificationTypes String Types of notification to return. Separate notification types with a comma with no space between notification types. If not specified, all notification types are returned. For a list of all notification types, see the discussion about notification types and MDCs in My MATRIXX Help. Required
searchInMemoryDatabase Boolean Specifies whether to search the in memory database. Default is true.
Note: If you include the searchInMemoryDatabase=false parameter, only events in the Event Repository are returned; recent events and aggregated events in progress are not returned.
 Optional
TrafficRouteData String Optional routing data used by the TRA to route this call to the correct engine Optional
This section includes the following examples:

Get Events by EventId

Get a list of events by EventId. Note that multiple event IDs are separated by a comma. 

GET http://host:port/rsgateway/data/json/eventstore/query/EventId/ABC0:1:52:18,ABC0:1:52:19

Get Purchases

Get the last five purchases made by a subscription with ExternalId "xyz" since February 1, 2017.

Note: Line breaks in this example are for legibility only. The URL has no line breaks. 
GET http://host:port/rsgateway/data/json/eventstore/subscription/
ExternalId+xyz?eventTypes=4&resultSize=5&
eventTimeLowerBound=2017-02-01T00%3A00%3A00-08%3A00

Get Voice Usage

Get the voice usage by a subscription with AccessNumber "16505551000" last week. 

GET http://host:port/rsgateway/data/json/eventstore/subscription/
AccessNumber+16505551000?eventTypes=1.2&eventTimeLowerBound=
2017-02-06T00%3A00%3A00-08%3A00&eventTimeUpperBound=2017-02-13T00%3A00%3A00-08%3A00
Note: Line breaks in this example are for legibility only. The URL has no line breaks.

Get Suspended Events

Get all the Suspend events in the month of January 2017 in the Event Repository only. 

GET http://host:port/rsgateway/data/json/eventstore/query?eventTypes=
9&searchInMemoryDatabase=false&eventTimeLowerBound=
2017-01-01T00%3A00%3A00-08%3A00&eventTimeUpperBound=2017-02-01T00%3A00%3A00-08%3A00
Note: Line breaks in this example are for legibility only. The URL has no line breaks.

Get Notifications

Get the last 10 notifications delivered for a subscription with ObjectId 0-1-2-3 last month in the Event Repository only. 

GET http://host:port/rsgateway/data/json/eventstore/notification/subscription
/0-1-2-3?resultSize=10&searchInMemoryDatabase=false&eventTimeLowerBound=
2017-02-01T00%3A00%3A00-08%3A00&eventTimeUpperBound=2017-03-01T00%3A00%3A00-08%3A00
Note: Line breaks in this example are for legibility only. The URL has no line breaks.

Notification Query Response

The following example shows the JSON response for a notification query for a subscription with ObjectId 0-1-5-1. 

{
    "$": "NotificationQueryResponse",
    "NotificationList": [
        {
            "$": "NotificationQueryEventInfo",
            "EventDetails": {
                "$": "MtxNotificationDoneEvent",
                "ContactSubscriberId": "0-1-5-1",
                "EventId": "GDJQA_0:1:52:4",
                "EventTime": "2017-02-09T16:57:03.199555Z",
                "EventTypeArray": [13],
                "Flags": 0,
                "InitiatorDeviceId": "0-1-5-3",
                "InitiatorExternalId": "23426",
                "InitiatorId": "0-1-5-1",
                "NotificationContentType": "text/plain",
                "NotificationId": "QA_0:1:31:1",
                "NotificationStatus": "succeeded",
                "NotificationType": "subscriber_auto_renew",
                "WalletId": "0-1-5-2",
                "WalletOwnerExternalId": "23426",
                "WalletOwnerId": "0-1-5-1"
            },
            "NotificationContent": "\nHi,\n\nThis is an auto renew charge.\n\nBalance impact list is:\n\n   1 Balance details are:\n    Balance name is postpaid , 50 US  CL, expired in 3 months\n    Start time is Wednesday, July 01, 2015, 02:00 PM (CEST)\n    End time is Thursday, October 01, 2015, 02:00 PM (CEST)\n    Impact Amount is USD10\n    Current Balance Amount is USD10\n    Offer impact list for postpaid , 50 US  CL, expired in 3 months is:\n\n        1 Offer name is mtx_autorenew_SMS_003\n        Impact Amount is USD10\n\n   2 Balance details are:\n    Balance name is Pre-Paid NonPeriodic SMS Asset\n    Start time is Wednesday, July 01, 2015, 02:00 PM (CEST)\n    End time is Thursday, October 01, 2015, 02:00 PM (CEST)\n    Impact Amount is -100\n    Current Balance Amount is -99\n    Offer impact list for Pre-Paid NonPeriodic SMS Asset is:\n\n        1 Offer name is mtx_autorenew_SMS_003\n        Impact Amount is -100\n\n\n\nThanks,\nCustomer Service\n\n\n"
        }
    ],
    "Result": 0,
    "ResultText": "OK",
    "_resultCode": 0,
    "_resultText": "OK",
    "_resultType": "get"
}

Event Query Response

The following example shows the JSON response for an event query for a subscription with ObjectId 0-1-5-6. 

{
    "$": "EventQueryResponseEvents", 
    "EventList": [
        {
            "$": "EventQueryEventInfo", 
            "EventDetails": {
                "$": "CustomSessionEndEvent", 
                "EventId": "FBG0:1:52:11", 
                "EventTime": "2014-02-14T12:45:00.000000-08:00", 
                "EventTypeArray": [
                    11, 
                    1
                ], 
                "ExternalSource": true, 
                "Flags": 0, 
                "InitiatorDeviceId": "0-1-5-9", 
                "InitiatorExternalId": "SubscriberAggrEventTest", 
                "InitiatorId": "0-1-5-6", 
                "SessionId": "session_3", 
                "WalletId": "0-1-5-7", 
                "WalletOwnerExternalId": "SubscriberAggrEventTest", 
                "WalletOwnerId": "0-1-5-6"
            }
        }, 
        {
            "$": "EventQueryEventInfo", 
            "BalanceImpactList": [
                {
                    "$": "MtxBalanceImpactInfo", 
                    "BalanceClassId": 840, 
                    "BalanceEndTime": "65535-12-31T23:59:59.999999Z", 
                    "BalanceImpactOfferList": [
                        {
                            "$": "MtxBalanceImpactOfferInfo", 
                            "BalanceImpactUpdateList": [
                                {
                                    "$": "MtxBalanceImpactUpdateInfo", 
                                    "Amount": "2.0000", 
                                    "UpdateType": 1
                                }
                            ], 
                            "CatalogItemId": 501402, 
                            "Flags": 1, 
                            "OfferId": 501402, 
                            "OfferResourceId": 1, 
                            "OfferVersion": 0
                        }
                    ], 
                    "BalanceOwnerExternalId": "Corporate", 
                    "BalanceOwnerId": "0-1-5-4", 
                    "BalanceResourceId": 1, 
                    "BalanceStartTime": "0001-01-01T00:00:00.000000Z", 
                    "BalanceTemplateId": 840170, 
                    "Flags": 2, 
                    "ImpactAmount": "2.0000", 
                    "IsCost": false, 
                    "IsMainBalance": false
                }
            ], 
            "EventDetails": {
                "$": "CustomEvent", 
                "AggregationId": "0-1-19-8", 
                "DevNick": "12.0.0.1", 
                "Duration": 1800000000, 
                "EventId": "0:1:19:8_0", 
                "EventTime": "2014-02-14T12:00:00.000000-08:00", 
                "EventTypeArray": [
                    1, 
                    1777
                ], 
                "Flags": 0, 
                "InitiatorDeviceId": "0-1-5-8", 
                "InitiatorExternalId": "SubscriberAggrEventTest", 
                "InitiatorId": "0-1-5-6", 
                "MobileCountryCode": 32, 
                "SubNick": "14085552202", 
                "WalletId": "0-1-5-7", 
                "WalletOwnerExternalId": "SubscriberAggrEventTest", 
                "WalletOwnerId": "0-1-5-6"
            }, 
            "UsageQuantity": "100.0000", 
            "UsageQuantityUnit": "kbytes"
        }, 
        {
            "$": "EventQueryEventInfo", 
            "EventDetails": {
                "$": "CustomPurchaseEvent", 
                "EventId": "DQW0:1:52:8", 
                "EventTime": "2009-11-15T09:01:00.000000-08:00", 
                "EventTypeArray": [
                    4, 
                    1
                ], 
                "Flags": 0, 
                "InitiatorExternalId": "SubscriberAggrEventTest", 
                "InitiatorId": "0-1-5-6", 
                "OfferInfoArray": [
                    {
                        "$": "MtxPurchaseEventOfferInfo", 
                        "EndTime": "65535-12-31T23:59:59.999999Z", 
                        "OfferId": 501402, 
                        "OfferVersion": 0, 
                        "ResourceId": 1, 
                        "StartTime": "0001-01-01T00:00:00.000000Z"
                    }
                ], 
                "WalletId": "0-1-5-7", 
                "WalletOwnerExternalId": "SubscriberAggrEventTest", 
                "WalletOwnerId": "0-1-5-6"
            }
        }
    ], 
    "Result": 0, 
    "ResultText": "OK", 
    "_resultCode": 0, 
    "_resultText": "OK", 
    "_resultType": "get"
}