Using the Manual event to notify people when non-LUSID activity occurs

In this tutorial we'll see how to use LUSID's Notification Service for your own purposes; that is, to notify people or perform actions when activity outside of LUSID or its ecosystem of applications occurs.

Note: To complete this tutorial, you must have suitable access control permissions. This can most easily be achieved by assigning your LUSID user the built-in lusid-administrator role, which should already be the case if you are the domain owner. If you are informed you do not have a license to perform a certain operation, contact support.

For example, imagine we receive a stream of corporate action activity from a news service. For the week beginning Monday 13 February, we might get the following messages:

Announcement date	Company	Corporate action	JSON representation
Monday 13 February	Apple	Cash dividend	`{ "AnnouncementDate": "2023-02-13", "Company": "Apple", "CorporateAction": "Cash dividend" }`
Wednesday 15 February	Microsoft	Stock split	`{ "AnnouncementDate": "2023-02-15", "Company": "Microsoft", "CorporateAction": "Stock split" }`
Friday 17 February	BP	Reverse stock split	`{ "AnnouncementDate": "2023-02-17", "Company": "BP", "CorporateAction": "Reverse stock split" }`

We want to email a group of people each time a message is received. To do this, we can subscribe to the Notification Service's Manual event, and then call the TriggerManualEvent API to trigger it separately on Monday, Wednesday and Friday, giving each created event the subject "New Corporate Action Announced" and a jsonMessage containing the JSON representation above.

Step 1: Subscribing conditionally to the Manual event

The first step is to create a conditional subscription to the Manual event. The subscription must be conditional as we only want to subscribe to the Manual event for corporate action activity. We can do this by mandating that only events triggered with a subject of New Corporate Action Announced invoke our subscription.

We can call the CreateSubscription API, passing in:

An API access token as a Bearer token in the Authorization HTTP header. See how to obtain a token.
ManualEvent as our scope and CorporateAction as our code for the subscription.
A displayName and description for the subscription.
A status of Active.
The eventType to subscribe to. In our case, we want to subscribe to the Manual event conditionally, which we can do by populating the filter parameter using LUSID filtering syntax. Note: You can retrieve the schema for Manual by calling the GetEventType API.

curl -X POST "https://<your-domain>.lusid.com/notification/api/subscriptions" 
-H "Content-Type: application/json-patch+json" 
-H "Authorization: Bearer <your-API-access-token>"
-d '{
  "id": {
    "scope": "ManualEvent",
    "code": "CorporateAction"
  },
  "displayName": "Corporate Action Event",
  "description": "A subscription to new corporate action announcements",
  "status": "Active",
  "matchingPattern": {
    "eventType": "Manual",
    "filter": "Body.subject eq 'New Corporate Action Announced'"
  }
}'

The response is as follows:

{
  "id": {
    "scope": "ManualEvent",
    "code": "CorporateAction"
  },
  "displayName": "Corporate Action Event",
  "description": "A subscription to new corporate action announcements",
  "status": "Active",
  "matchingPattern": {
    "eventType": "Manual",
    "filter": "Body.subject eq 'New Corporate Action Announced'"
  },
  "createdAt": "2023-02-04T10:32:04.2124448+00:00",
  "userIdCreated": "00uji4twb4jDcHGjN2p8",
  "modifiedAt": "2023-02-04T10:32:04.2124448+00:00",
  "userIdModified": "00uji4twb4jDcHGjN2p8",
  "useAsAuth": "00uji4twb4jDcHGjN2p8",
  "href": "https://<your-domain>.lusid.com/notification/api/subscriptions/ManualEvent/CorporateAction"
}

You can sign in to the LUSID web app to view the new subscription on the Subscription Management dashboard, available from the top left menu under Jobs & Scheduling:

Step 2: Attaching a notification template to the event subscription

The next step is to create an email notification and attach it to our conditional subscription. To do so, we call the CreateNotification API, passing in our API access token and:

The scope and code of the subscription to attach the notification to. In our case, ManualEvent and CorporateAction.
A displayName and description for the subscription.
A notification Type of Email with a Subject such as New Corporate Action.
One or more email recipients under EmailAddressTo.
In the PlainTextBody and HtmlBody, we can use mustache templates with the syntax {{Body.jsonMessage.<your-JSON-key>}} as placeholders for contextual values emitted by the Manual event each time we trigger it. For example, if your jsonMessage contains the following key/value pairs...

"AnnouncementDate": "2023-02-13", 
"Company": "Apple", 
"CorporateAction": "Cash dividend"

…you can add the keys to the notification body using mustache templates, as shown:

curl -X POST "https://<your-domain>.lusid.com/notification/api/subscriptions/ManualEvent/CorporateAction/notifications" 
-H "Content-Type: application/json-patch+json" 
-H "Authorization: Bearer <your-API-access-token>"
-d '{
  "notificationId": "CorporateActionNotification",
  "displayName": "New Corporate Action Email",
  "description": "An email notification for new corporate action announcements",
  "notificationType": {
    "Type": "Email",
    "Subject": "New Corporate Action Announced",
    "PlainTextBody": "New corporate action announced for {{Body.jsonMessage.Company}} on {{Body.jsonMessage.AnnouncementDate}}: {{Body.jsonMessage.CorporateAction}}.",
    "HtmlBody": "<p>New corporate action announced for {{Body.jsonMessage.Company}} on {{Body.jsonMessage.AnnouncementDate}}: {{Body.jsonMessage.CorporateAction}}.</p>"
    "EmailAddressTo": [
      "some-user@acme.com"
    ]
  }
}'

Step 3: Triggering the Manual event each time a corporate action occurs

We can now call the TriggerManualEvent API each time we receive news of a corporate action to trigger the Manual event and invoke our subscription, specifying in the body of the request:

A case-sensitive value for the subject field that matches the condition in our subscription, which is New Corporate Action Announced.
An appropriate value for the mandatory message field. Note: You can retrieve the schema for Manual by calling the GetEventType API.
Contextual values in the jsonMessage field for each of the JSON keys in our mustache template.

For example, on Monday 13 February we might call the TriggerManualEvent API as follows:

curl -X POST "https://<your-domain>.lusid.com/notification/api/manualevent" 
-H "Content-Type: application/json-patch+json" 
-H "Authorization: Bearer <your-API-access-token>"
-d '{
  "Body": {
    "message": "A new corporate action has been announced",
    "subject": "New Corporate Action Announced",
    "eventTime": "2022-02-13",
    "jsonMessage": {
      "AnnouncementDate": "2023-02-13",
      "Company": "Apple",
      "CorporateAction": "Cash dividend"
    }
  }
}'

…and receive the following email:

On Wednesday 15 February we might call the TriggerManualEvent API as follows:

curl -X POST "https://<your-domain>.lusid.com/notification/api/manualevent"
-H "Content-Type: application/json-patch+json"
-H "Authorization: Bearer <your-API-access-token>"
-d '{
  "Body": {
    "message": "A new corporate action has been announced",
    "subject": "New Corporate Action Announced",
    "eventTime": "2022-02-15",
    "jsonMessage": {
      "AnnouncementDate": "2023-02-15",
      "Company": "Microsoft",
      "CorporateAction": "Stock split"
    }
  }
}'

On Friday 17 February we might call the TriggerManualEvent API as follows:

curl -X POST "https://<your-domain>.lusid.com/notification/api/manualevent"
-H "Content-Type: application/json-patch+json"
-H "Authorization: Bearer <your-API-access-token>"
-d '{
  "Body": {
    "message": "A new corporate action has been announced",
    "subject": "New Corporate Action Announced",
    "eventTime": "2023-02-17",
    "jsonMessage": {
      "AnnouncementDate": "2023-02-17",
      "Company": "BP",
      "CorporateAction": "Reverse stock split"
    }
  }
}'

Next steps

We can attach more than one notification to our subscription in order to perform several operations each time we trigger the event. For example:

We could create a webhook that calls the UpsertInstrumentEvents API to automatically load the corporate action into LUSID. See how to create a webhook to call a LUSID API when an event occurs.
We could attach an SMS notification to text a group of people when the event is triggered. See how to notify people via SMS when an event occurs.