# Transitioning from v2 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](https://console.aws.amazon.com/sns).
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](https://queue-docs.rightsline.com/sns/message-attributes).

![](https://1230650179-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MGAeYsGmflcmJcE_7Ap%2F-MS9iMz8ZlMMaIoXRj4I%2F-MSEAjuC-v9421bAHQ3m%2Fsub_filter_policy.PNG?alt=media\&token=b82a7bfa-4fbf-4cdc-895f-308d596ef902)

### Assume AWS role to interact with SNS topic

Rightsline will provide an [AWS IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-api.html).

## 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](https://queue-docs.rightsline.com/sns/message-attributes).

## New Message Structure

We have redesigned the structure of our messages to provide more information about the event.  For complete examples, see [here](https://queue-docs.rightsline.com/sqs/overview).  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**

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

#### v4

```javascript
{
    "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.

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

* `relationshipType` object has been added to relationship messages.

```javascript
{
    "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](https://queue-docs.rightsline.com/message-structure/entity-messages/examples#action-executed).