Transitioning from v2 to v4

A guide for transitioning from using v2 of our message queuing to v4.

Coordinated Launch of API and Messaging Updates

In coordination with the messaging updates, we are launching v4 of our API. Since the changes to the object structures in our messages are consistent with the changes made to response objects on the API side, we opted to skip a version 3 release of the messaging infrastructure and instead keep the version numbers in lock step between the features.

Customer-owned subscriptions

Rightsline messaging v4 enables customers to manage their own subscriptions to our SNS topics. You will need to provide us with your AWS account ID as well as the char types that you would like to receive messages for (e.g. Deals, Catalog Items, etc.), and we will provide your personalized SNS topic ARNs. Using your AWS account, you can create subscriptions to these topics to trigger custom logic using AWS Lambda, populate a queue using AWS SQS, or call an external HTTP endpoint for some downstream system.

Creating an SNS subscription

1. In order to create a subscription to your SNS topics, access the AWS SNS Dashboard.

2. Select Subscriptions, and click Create Subscription.

3. Under Topic ARN, input the provided SNS topic ARN. Select the protocol where you would like the message delivered.

4. Under Subscription filter policy, add any filters that you would like to your subscription. You can filter on any message attribute value. See Message Attributes.

Assume AWS role to interact with SNS topic

Rightsline will provide an AWS IAM role ARN that you will need to assume in order to interact with the messages on the SNS topic. Using this role, you will be able to retrieve credentials that will give you access to receive messages from your SNS topics. For more information, see Switching to an IAM role.

New Message Attributes

We have added additional message attributes to all of our messages to allow more precise filtering of messages. For all message attributes, see here.

New Message Structure

We have redesigned the structure of our messages to provide more information about the event. For complete examples, see here. Some of the specific changes are:

• Removed entityUrl, rootEntityUrl, parentUrl, childUrl properties. These properties have been replaced with entity objects, with the names entity, rootEntity, parentEntity, childEntity. The entityId, charTypeId, template, and status have all been moved inside the entity object. The workflow processId and processName have been added to the template object.

v2

{
    "entityId": 3300,
    "entityUrl": "https://api.rightsline.com/v2/catalog-item/3300"
}

v4

{
    "entity" : {
        "entityId": 3300, 
        "charTypeId": 1, 
        "status": {
            "statusId": 1, 
            "statusName": "Development"
        }, 
        "template": {
            "templateId": 1, 
            "templateName":"Series",
            "processId": 4,
            "processName": "Catalog Workflow"
        }
    }
}

• statusUpdatedById, statusUpdatedDate have been added to all entity messages.

{
    "statusUpdatedById": 12345,
    "statusUpdatedDate": "2019-02-21T19:58:46.777Z"
}

• relationshipType object has been added to relationship messages.

{
    "relationshipType": {
        "relationshipTypeId": 0,
        "relationshipTypeName": "Default"
    }
}

Workflow actions published to relevant char type topic

We have removed the action-executed SNS topics. Workflow action event messages will now be sent to the relevant char type SNS topic, with an action value of action-executed. For instance, if a workflow action is taken on a deal, you will receive a message to the deal (ct4) SNS topic. An example action-executed message can be found here.