Article last updated on the 22nd of September, 2023.
Contents
1. Introduction
The WorkPoint Event Bus feature makes it possible to send events in WorkPoint to Azure Event Grid. As alternative, this could be done using system triggers in WorkPoint Automate, but the WorkPoint Event Bus has been designed especially for scalability and performance.
When scaling your solution to thousands of users and millions of documents and items, a large number of events will happen in WorkPoint. If you need to integrate to other systems and handle a high-scale number of events it may cause significant overhead, and result in performance impacts on the WorkPoint solution. Therefore, it is recommend to use the WorkPoint Event Bus feature to ensure the best possible performance of the system.
The Event Bus feature allows events to be published to the Azure event grid for processing. The benefit of the Azure Event Grid is that it can scale to an extreme amount of event and the processing of the event is decoupled from the WorkPoint infrastructure. The Azure Event Grid is a publish/subscriber service, where you can publish events that will be pushed to multiple subscribers. With WorkPoint Event Bus, WorkPoint becomes a publisher to Azure Event Grid.
Example of usage could be to replicate data from WorkPoint to cloud based databases like Dataverse or Cosmos Db and use this data to provide real-time insights to your data through PowerBi.
The WorkPoint Event Bus works by configuring so-called "Event registrations" for which Entity- or Item events are paired with a topic in the Azure event grid. In the future, more options for the target may get implemented.
The Azure Event Grid works with a few different terminologies which are important to understand.
First, let's take a look at an illustration detailing the Azure Event Grid functionality:
A publisher sends an event which goes into something called a "topic". A topic can be thought of as a channel to which events are posted by publishers. One or more subscribers can then get information about the event that has happened from the topic or the channel, and based on the event and information received, the subscribers can perform a wide range of actions.
Subscribers can use filters to allow only specific events types to go through to their endpoints.
Here are some advantages of using the WorkPoint Event Bus to integrate with the Azure Event Grid:
Scalability
Azure Event Grid and Event Bus are highly scalable and can handle a large volume of events. This allows your system to scale seamlessly as your SharePoint Online usage grows. Managing the events in WorkPoint also have a low impact on WorkPoint performance.
Asynchronous Processing
Events can be processed asynchronously, which can improve the performance and responsiveness of your application. Users can continue to interact with SharePoint Online while background processing occurs.
Reliability
Azure Event Grid and Event Bus provide reliability features like retries, dead-lettering, and event delivery guarantees, ensuring that events are reliably processed, even in the face of failures.
Event Filtering
Azure Event Grid allows you to define event subscriptions and filters. This means you can selectively process only the events that are relevant to your backend operations, reducing unnecessary processing overhead.
Integration with Other Azure Services
Azure Event Grid and Event Bus can be integrated with various Azure services, such as Azure Functions, Logic Apps, and Azure Service Bus, enabling you to leverage a wide range of tools and capabilities for event processing and automation.
2. Configuration
2.1. Access the Event Grid service page in the Azure Portal
To get started using the Azure Event Grid, we first need to set up a topic. We do so from the Azure portal, which can be accessed from https://portal.azure.com.
- In the Azure portal you can navigate to the "Event Grid" service either from the front page (if you have used it before), or from the "More services" area.
- In the Event Grid page, under "Custom events" we can select "Topics".
This opens the Topics page:
On the Topics page, we can create new topics which subscribers can subscribe to.
Under normal circumstances, to make the WorkPoint Event Bus integration work, you would create a single topic for WorkPoint events.
2.2. Creating a topic for WorkPoint Events
In this section, we will create an Event Grid topic for WorkPoint events.
We begin in the Topics page of the Event Grid service in the Azure Portal:
- In the Topics page, we click the "Create" button in the command bar to create a new Event Grid topic.
- We begin by selecting an Azure subscription to use for our Event Grid topic.
- Next, we select a resource group for the topic. If you have one you want to place the topic in, you can select it in the drop down menu. Otherwise, you can create a new one and give it a name.
- Click the "OK" button to create the new resource group and select it.
- Next, we can give the topic a name. In this case, since this topic will be used for WorkPoint events, we name it "WorkPointEvents". The name you choose must be unique in the Azure Region selected below, so it's good practice to use prefix of your own making in the name. We can also select a region for the topic.
- To continue, click the "Review + create" button.
- Please wait until the page shows the "Validation succeeded" message. This may take a couple of seconds.
- Once the configuration of the topic has been validated, click the "Create" button to create the topic.
This will initialize the deployment of the topic. You will be redirected to the following page:
Once the deployment has completed, the page will change to the following:
- Click the "Go to resource" button to go to the new topic.
This will open the overview page of the topic:
At this point we have created an Event Grid topic which publishers can send events to.
- In the "Essentials" section of the overview, we can see the "Topic Endpoint". This is the endpoint to which events should be sent to end up in the topic.
- In order to post events to the topic, publishers need to provide authentication using an access key. The topic provides two such keys which can be accessed in the "Access keys" section:
For authentication you can use either access key, but it is recommended that you only use one at a time. If the one in use gets compromised, you can switch to use the other while regenerating it.
2.3. Testing the topic using a Logic App
The steps in this section is not strictly necessary in order to integrate WorkPoint 365 with the Azure Event Grid service. However, it can be useful to test the connection between publisher and subscriber. To go directly to the WorkPoint 365 configuration of the Event Bus, you can go to section 2.4 in this article.
In this section, we will create a quick Logic app to test the topic created in the previous section.
We begin in the front page of the Azure portal:
- We can access the Logic apps service by clicking "Logic apps" on the front page (if it has been used recently), or in the "More services" section, which can also be accessed from the front page.
- We can create a new Logic app by clicking the "Add" button.
- We begin by selecting an Azure subscription to use for the Logic app. We also place the Logic app in a resource group. In this case, we select the same resource group as our WorkPointEvents topic.
- Next we give the Logic app a name and select a region.
- In the "Plan" section, we select "Consumption".
- To review and create the app, we click the "Review + create" button.
- To continue and finish creating the app, we click the "Create" button.
This starts the deployment process of the Logic app, and you are redirected to the following page:
Once the app has finished deployment, the page changes to the following:
- We can now go to the Logic app by clicking the "Go to resource" button.
- In the Logic app designer, we select the Blank Logic App template.
- In the Logic app designer, we start by adding a "When a HTTP request is received" trigger. We keep all the settings as default.
- Next, we search for "Event grid" and select the "Azure Event Grid Publish" group.
- Next, we select the "Publish Event" action.
Before we can publish an event using this action, we need to configure a connection to the topic we want to publish to:
- First, we give the connection a name. The Topic Endpoint can be copied directly from the topic overview page. For the Shared Access Signature, you can use one of the keys from the Access keys section of the topic.
- To create the connection, we click the "Create" button.
Next, we get the following options for our publishing action:
- In the "Data" field, we provide a JSON object simply containing the key "someData" and the value "someValue".
- In the "Event Type" field, we type in a sample event type.
- In the "ID" field, we use the "guid()" function to create a new guid which is then used as the ID of the event.
- In the "Subject" field we type in a sample subject title.
- In the "Event time" field, we use the utcNow()" function to record the current time when the event is published to the topic.
- We can now save the Logic app by clicking the "Save" button.
Next, we need to configure a subscriber for the topic. We do so from the overview of the Event Grid Topic created in the previous section:
- To create a new subscriber, we click the "Create one" on the overview of the Event Grid Topic page. Alternatively, we could navigate to the "Event Subscriptions" page from the left navigation menu and create a new subscription from there.
- In the "Name" field, we give the subscription a name.
- In the "Filter on Event Type" we could potentially click and type in the name of an event type to filter for. In pt. 30 we defined an event type for the event we are going to publish for testing using the Logic app, so we could potentially add that as a filter here. In this case, however, we leave the filter blank.
- In the "Endpoint type" we select "Web hook".
At this point, we need a web hook to test with, to see if events are passed through form the publisher (the Logic app) through the Topic to the subscriber (the web hook we set up).
We can create a test web hook by going to https://webhook.site/.
This web page provides us with a temporary web hook with a Url we can copy and use to send events to.
- On the Webhook.site page, click the "Copy" button for the unique URL.
- With the unique Url copied to the clipboard, we click "Select and endpoint" and paste it into the "Subscriber Endpoint" field.
- We then click the "Confirm Selection" button.
- To save the Event Subscription, we click the "Create" button.
If we return to the Webhook.site page, we can now see a new event in the left side menu:
- To validate the webhook and complete our test setup for the Topic and Subscription, we need to copy the Url (value) of the "ValidationUrl" key and paste it into a browser. Upon navigating to that Url, we should see the following confirmation message:
We can now try and run our Logic app trigger and see if we can send an event from it through the topic to our subscriber (webhook). If successful, we should get another event listed on the Webhook.site:
- On the Logic app designer, we can click the options for "Run Trigger" and select "Run".
After a couple of seconds, we should see the following result:
If we take a look on the Webhook.site, we should see another event in the left side menu:
- In the new event received, we can see in the "Raw Content" section that we have received the data we configured in the Logic app.
Based on this test we can conclude that we can successfully send events from our published (our Logic app) through our Topic to our Subscriber (the web hook).
Next, we can proceed to start sending events from WorkPoint 365 to our subscriber.
2.4. Sending WorkPoint events using Event Bus
2.4.1. Creating Access Token Credential
In this section we will create an Access Token Credential in the WorkPoint 365 HTTP endpoint library to use in the Event Bus.
We begin in the WorkPoint 365 administration:
- In the left side menu of the WorkPoint 365 administration, we click the "Http Endpoint Library" button.
- In the Http Endpoint Library we select "EventGrid Token" and click the "Add" button.
- We provide the new credential with a title, a credential type of "Access Token" and paste the same Topic key as we used for our Logic app connection.
- To add the new credential, we click the "Add" button.
The new credential should now appear in our list of credentials in the Http Endpoint Library:
2.4.2. Configuring the Event Bus
In this section we will configure the Event Bus in WorkPoint. By doing this, WorkPoint will work as a publisher, sending events to the Event Grid topic for the subscriber (web hook) to pick up on.
We begin in the WorkPoint 365 Administration:
- In the left side menu of the WorkPoint 365 administration, we click the "Event Bus" button.
This opens the "Event Bus Settings" page:
We start by configuring the General settings of the Event Bus:
- In the "Target" field, there is currently only one option available, the "AzureEventGrid" option.
- In the "Endpoint Url" field, we paste in the Event Grid Topic Endpoint Url, which can be found on the Topic overview page in the Azure portal.
- In the "Access Token Credential" field, we select the credential we created in the previous section.
We can now start to configure which events to publish to the topic. As an example, we will create a configuration for publishing Entity Updated events:
- In the "Events" section of the Event Bus Settings page, we click "New configuration" and select "EntityTriggerEvent".
We can then further configure the event trigger:
- In the "WorkPoint Event Type" field, we select the type of Entity Event we want to send. In this case, we want to send an event whenever an entity is updated, so we select the "EntityUpdated" option.
- The "Azure Event Type" field is a free text field in which you can type in an event type. It functions like the "Event type" field in pt. 29 when configuring the test Logic app.
- In the "Business Module" field we select which business module we want to send events from. When entities on the selected business module are updated, events are sent to the topic and subscriber(s).
- The "Subject" field is also a free text field on which you can type in a subject for the event. It functions like the "Subject" field in pt. 31 when configuring the test Logic app.
- The "Data Version" field is a field where you can type in a number, which internally in your organization can be used to identify e.g., a schema used for your published events.
Note that if you are configuring an ItemTriggerEvent, an additional field for specifying the list you are targeting will need to be configured. Simply select the list from which you want to publish events.
We can now save the settings and test them out:
- Click the "Save" button to save the settings.
2.4.3. Testing the Event Bus functionality
As previously seen, we configured the Event Bus to send events to our topic and subscription whenever any updates to meta data are made to entities on our Projects business module.
In this instance, we will make an edit to the "Description" field on our project titled "Project Orange":
When this update is saved, we should get a new event on the Webhook.site:
We have now received the event on the web hook, and we can see in the Raw Content that the WorkPoint Event Bus sent along all the meta data of the event, including all of Project Orange's meta data.
Comments
0 comments
Please sign in to leave a comment.