Announce events on the Queue

Introduction

The scope of this document is to describe the logic regarding handling of UserAnnounce and ServiceAnnounce events from the Global Backend queue and how this can be used to support the Customer Journey called “Start in the Service”.

Integration with Global Backend Event Queue

For general information about the Global Backend event queue, see the following documentation:

• Event queue fundamentals
• Event queue API

Note that events must be ack'ed to be removed from the queue.

The following two events must be handled and relevant logic added by the BU:

• UserAnnounce
• ServiceAnnounce

UserAnnounce

The UserAnnounce event is triggered when a new user signs up. This event is only sent to API users where it has been explicitly enabled. An example UserAnnounce event could look like the following:

{
    "link": [
        {
            "href": "ack?receiptId=5c38c304-39f0-4496-9a00-b16602f93907",
            "rel": "ack"
        }
    ],
    "receiptId": "5c38c304-39f0-4496-9a00-b16602f93907",
    "messageId": "5555145209244815360",
    "event": {
        "timestamp":1394064715191,
        "eventId":"5847131211184496640",
        "msisdn":"4700000000",
        "userId":"5000000000000000000",
        "consistencyLevel":"NONE",
        "eventName":"com.comoyo.events.user.UserAnnounce",
        "isoTimestamp":"2014-03-06T00:11:55.191Z"
    }
}

Please note that the event can be triggered either for a phone number or an email address, after the user has verified the phone number or email address in question. The event either includes the msisdn field or the email field, not both. The current registration process for a new CONNECT user only use phone number verification. But in order to be “future proof”, the event should be checked whether it contains MSISDN or email. The BU will normally only be able to use the ones containing MSISDN.

Please also note that the event might trigger more than once for the same number, so there has to be logic to handle duplicates.

The logic for processing a UserAnnounce, should be as follows:

1. Get information about MSISDN and Global ID from event
2. Check if number belongs to BU customer. The UserAnnounce events triggers for all numbers in a country. Once configured in the Global Backend, the BU will receive events for all numbers with a given country code on their event queue.
3. Connect to external company. The BU should then call connect user to external company (https://confluence.skunk-works.no/confluence/display/B2BAPI/Connect+user+to+External+Company) to create an account with their CompanyID. This will make sure that the BU receives other events connected to the user, like the ServiceAnnounce event.
4. The mapping between MSISDN and Global ID should be stored locally. The BU should store the Global ID returned in the event together with the MSISDN in a local database for later reference.
5. Check which service the user has signed up for. To know whether the user has signed up for a service that the BU is bundling benefits for, you will need to call the Global Backend and get a list of all services, see documentation: https://confluence.skunk-works.no/confluence/display/B2BAPI/Check+specific+service+for+user Use the all services call (/id/users/[userid]/services). It will usually at this point (since we are handling a UserAnnounce) contain one service. To be future proof, be sure to be able to handle a list of services. If the list is empty or the service(s) returned that does not include any benefits from the BU, exit processing of the event. This call is also important due to the timing gap between UserAnnounce and connect user to external company call (see sequence diagram in 4.3.3)
6. Check eligibility. Check what package the MSISDN belongs to and get the associated benefit, e.g. 100 GB extra storage for capture. The BU should also keep track of the benefits the user already has received in order to prevent giving away the included benefits more than once.
7. Create a Right or Subscription in the Global Backend [Not described in detail here.] As mentioned in point 6, the BU should also keep track of the benefits that has been assigned to a MSISDN by storing it locally. This is typically done in their Billing System or CRM system.

ServiceAnnounce

This event is triggered when the user starts using a service which has a service name. "Starts using a service" is currently defined as having a right that allows the user to use the service. Note that this event may trigger again even if the user already had access to the service.

{
    "link": [
        {
            "href": "ack?receiptId=5c38c304-39f0-4496-9a00-b16602f93907",
            "rel": "ack"
        }
    ],
    "receiptId": "5c38c304-39f0-4496-9a00-b16602f93907",
    "messageId": "5555145209244815360",
    "event": {
        "timestamp":1394096635508,
        "eventId":"5800000000000000004",
        "buId":"comoyo",
        "userId":"5000000000000000000",
        "consistencyLevel":"NONE",
        "eventName":"com.comoyo.events.user.ServiceAnnounce",
        "serviceName":"capture",
        "isoTimestamp":"2014-03-06T09:03:55.508Z"
    }
}

Please also note that the event might trigger more than once for the same service, so there has to be logic to handle duplicates.

The logic for processing a ServiceAnnounce, should be as follows:

1. Get information about serviceName and Global ID from event
2. Lookup MSISDN based on Global ID. This should be done by querying the local mapping database containing Global ID and MSISDN that the BU keep on their side. If mapping not found, GBE can be queried (id/users/[userid]/phones). Please note that the Phones object potentially can contain more than one phone number.
3. Follow same logic as under UserAnnounce from step 6 Check eligibility

UserAnnounce and ServiceAnnounce sequence diagrams

Note on UserAnnounce and ServiceAnnounce case 1: ServiceAnnounce is not generated after creating the B2C right because "connect user to external company" is called after the B2C right is created. To be sure to catch this, call /id/users/[userid]/services to get the services activated by a user after doing the BU connect.

Note on UserAnnounce and ServiceAnnounce case 2: In this case the "connect user to external company" is called before the B2C right is created. The "List of services activated by the user" will then return an empty list, but the BU can use the ServiceAnnounce generated to catch the signup of a new service to add BU benefits.

Monitoring of the queue

The BU should establish monitoring of the queue to check that the events are actually read and removed. To perform monitoring, use the Event Queue Status Resource

"Non-connected region-users" report

For general information about the “Non-connected region-users” report, see documentation on Telenor Digital Confluence site:

https://confluence.skunk-works.no/confluence/display/B2BAPI/Non-connected+region-users+report

The report contains a list of users with MSISDNs for a specific region, i.e. +66 (Thailand) that has no BU account associated with it.

{
    "reportHeader": {
        "buId": "DTAC",
        "reportType": "NonConnectedRegionUsersReport",
        "runId": "5159245e19400000",
        "startTime": "2014-04-15T08:47:06.398Z",
        "version": 0
    },
    "users": [
        {
            "msisdn": "66946860423",
            "userId": "5159245e19400001"
        },
        {
            "msisdn": "66982461188",
            "userId": "5159245e19400002"
        }
    ]
}

The report should be processed periodically to check if there are any numbers belonging to the BU’s customers and if those customers have any included benefits they should receive.