Product Entitlements Messaging Operations #
General #
The Product Entitlements service interacts with the primary SpheraCloud EventHub via a private Topic channel
(product-entitlements) that is restricted to a select set of registered senders.
The private channel is ONLY for use by Sphera’s primary System of Record (SOR) for cusomer and licensing data - at the current time this is Salesforce.
As changes occur in the SOR system, it is responsible for publishing topic messages to the ProductEntitlements channel to indicate the type of change along with defined change metadata.
Security #
The primary security for the ServiceBus interactions is through the locked down publish to topic capability. Only those applications with an authorized client id or sufficient credentials will be allowed to publish to this topic. Additionaly, the topic publishing capability can be locked down to a specific IP white list if desired although this is not currently enabled.
Message contract #
There are three primary message types supported for processing by the ProductEntitlements subscriber - ProductChange, CompanyChange, and LicenseChange. Messages are filtered to three subscriptions based on the label assigned to the message envalope (company, product, or license).
CompanyChange Message #
The CompanyChange message should be sent by privlieged systems whenever a Company changes within the SOR system. These changes correspond to newly created, modified, and deleted events. The message envalope should have a label with a value of “company.”
The format of a CompanyChange message is in JSON and as follows:
{
"changeType": "new, updated, or deleted",
"id": "SOR system id (uuid)",
"name": "company name",
}
A deleted key may be added, but the Product Entitlements service will ALWAYS add the company in an active status regardless of any value passed.
ProductChange Message #
The ProductChange message should be sent by privlieged systems whenever a Product changes within the SOR system. These changes correspond to newly created, modified, and deleted events. The message envalope should have a label with a value of “product.”
The format of a ProductChange message is in JSON and as follows:
{
"changeType": "new, updated, or deleted",
"id": "SOR system id (uuid)",
"name": "product name",
"description": "produt description...",
"title": "product display title...",
"marketingUrl": "product default marketing page url",
"marketingImage": " product default display image",
}
A deleted key may be added, but the Product Entitlements service will ALWAYS add the product in an active status regardless of any value passed.
LicenseChange Message #
The LicenseChange message should be sent by privlieged systems whenever a License changes within the SOR system. These changes correspond to newly created, modified, and deleted events. The message envalope should have a label with a value of “license.”
The format of a LicenseChange message is in JSON and as follows:
{
"changeType": "new, updated, or deleted",
"id": "SOR system license id (uuid)",
"companyid": "the SOR companyid - uuid",
"productid": "the SOR productid - uuid",
"linkUrl": "company-specific product url",
"linkImage": "company-specific display image",
"startDate": "start datetime of license",
"endDate": "end datetime of license"
}
A deleted key may be added, but the Product Entitlements service will ALWAYS add the license in an active status regardless of any value passed.
UserChange Message #
The UserChange message should be sent by authorized systems whenever a User changes within the SOR system. These changes correspond to newly created, modified, and deleted events. The message envelope should have a label with a value of “user.”
The format of a UserChange message is in JSON and as follows:
{
"changeType": "new, updated, or deleted",
"id": "user id in the PE System (ignored for creates)",
"b2c_id": "the users b2c_id",
"companyId": "the company id of the user as defined in the PE system",
"companyName": "company name",
"fk_companyId": "company foreign key id"
}
UserProductChange Message #
The UserProductChange message should be sent by authorized systems whenever a UserProduct changes within the SOR system. These changes correspond to newly created, modified, and deleted events. The message envelope should have a label with a value of “userproduct.”
The format of a UserProductChange message is in JSON and as follows:
{
"changeType": "new, updated, or deleted",
"id": "id of the userproduct to change (ignored for creates)",
"userId": "user id in the PE System (ignored for creates)",
"productId": "the product id of the product as defined in the PE system",
"productUrl": "link to the product that is valid for this user",
"isDefault": "flag indicating whether this is the default for the user"
}
Operational Flow #
There are three Azure functions configured to be triggered by Azure ServiceBus Subscriptions. Essentially, each subscription on the product-entitlements topic is limited to one of the three main entity change types - company, product, or license.
- Subscriptions act as filters for incoming topic messages sorting each of the entity types into its own queue internally.
- In turn, the Azure functions are configured to dynamically spin up an instance for each incoming message so that it can be processed.
- If more than one message is pending, additional functions are “spun up” as needed up to a limit of approximately 2000 instances. The absolute limits can be configured; but, we are using default values.
- As messages are picked up for processing, they are marked as “locked” until the function completes successfully, at which time they are deleted.
- Failed messages either due to an issue with the function or other internal error, are freed up automatically after a configurable timeout period and can be processed again.
- Messages that fail more than three times are automatically moved to a “dead-letter” queue and are no longer active nor available for processing.
