Some interactions on VTEX IO can generate events and be used as triggers for actions. For instance, an app listening for order placement events can respond by sending a confirmation email. In this course, we'll explore the process of firing events using the events-example app and then demonstrate how the service-course-template app can effectively listen to and handle these events.
Events are workspace and account-bound, meaning they are only visible for the account and workspace where they were fired. Events fired on your personal workspace will only be listened to by apps linked to this same workspace.
Logging into your account
To begin, log in to your VTEX account and create a devolopment workspace using the terminal. Replace {accountName} with your VTEX account name.
_10vtex login {accountName}
Cloning the app responsible for firing events
Now, let's clone the events-example app, responsible for firing the events that the service-course-template will listen to.
_10git clone https://github.com/vtex-apps/events-example
Linking the app to a development workspace
Change to the events-example directory and link the app to your development workspace. After running vtex link on the events-example app, the terminal should prompt a healthcheck route. Access the healthcheck route using your browser. You should see an ok text.
Accessing the healthcheck route creates a cache context needed for the VTEX IO to fire events. Without it, the
events-exampleapp won't be able to fire the events our app is going to listen to.
Handling events
Now, let's return to the service-course-template app to manage events triggered by the events-example app effectively. This involves the following steps:
- Set up the
service-course-templateapp to listen to events emitted by theevents-exampleapp. - Create an event handler function for processing the events received from the
events-exampleapp. - Configure the
service-course-templateapp to use the handler function to handle the listened events.
Listening to events
In order to listen to the events sent by the events-example app, open the service.json file and declare the highlighted code to give the app's service this capability. Note that we declare this by using the events resolver, the reference of the app that fires the event (sender), and the event reference key (keys).
Creating an event handler function
Once we are able to listen to the events sent by the events-example app, let's create a function to handle these events. For now, let's create a log when receiving an event. To do so, open the /node/event directory and update the liveUsersUpdate.ts file with the code presented.
Defining the event handler
Now, we need to specify how the event handler function will be used. Open the service-course-template/node/index.ts file and update the Service declaration with the highlighted lines.
Configuring the event handler behavior
We can now specify how the event handler will behave. In the service-course-template/node/index.ts file, update the Service declaration with the highlighted lines. Going by each configuration, we have the following:
| Field | Type | Description |
|---|---|---|
exponentialTimeoutCoefficient | Integer | Exponential factor by which the timeout will increase in each retry, in seconds. |
exponentialBackoffCoefficient | Integer | Exponential factor by which the backoff delay will increase in each retry, in seconds. |
initialBackoffDelay | Integer | Time, in seconds, that the app will wait until the next retry. |
retries | Integer | Maximum times the app will retry. |
timeout | Integer | Timeout until the attempt is considered a failure, in seconds. |
concurrency | Integer | Amount of simultaneous processes the event is able to perform. |
By adding this code to the Service, we are adding to the Client of this Service, the capability to handle events. At this point, we are not yet using the Client itself when handling the event.
Linking the event handler app
In the service-course-template directory, run vtex link and wait for the event to be fired by the events-example app. Upon successful reception, a log entry should appear in the console.
Logging into your account
To begin, log in to your VTEX account and create a devolopment workspace using the terminal. Replace {accountName} with your VTEX account name.
Cloning the app responsible for firing events
Now, let's clone the events-example app, responsible for firing the events that the service-course-template will listen to.
Linking the app to a development workspace
Change to the events-example directory and link the app to your development workspace. After running vtex link on the events-example app, the terminal should prompt a healthcheck route. Access the healthcheck route using your browser. You should see an ok text.
Accessing the healthcheck route creates a cache context needed for the VTEX IO to fire events. Without it, the
events-exampleapp won't be able to fire the events our app is going to listen to.
Handling events
Now, let's return to the service-course-template app to manage events triggered by the events-example app effectively. This involves the following steps:
- Set up the
service-course-templateapp to listen to events emitted by theevents-exampleapp. - Create an event handler function for processing the events received from the
events-exampleapp. - Configure the
service-course-templateapp to use the handler function to handle the listened events.
Listening to events
In order to listen to the events sent by the events-example app, open the service.json file and declare the highlighted code to give the app's service this capability. Note that we declare this by using the events resolver, the reference of the app that fires the event (sender), and the event reference key (keys).
Creating an event handler function
Once we are able to listen to the events sent by the events-example app, let's create a function to handle these events. For now, let's create a log when receiving an event. To do so, open the /node/event directory and update the liveUsersUpdate.ts file with the code presented.
Defining the event handler
Now, we need to specify how the event handler function will be used. Open the service-course-template/node/index.ts file and update the Service declaration with the highlighted lines.
Configuring the event handler behavior
We can now specify how the event handler will behave. In the service-course-template/node/index.ts file, update the Service declaration with the highlighted lines. Going by each configuration, we have the following:
| Field | Type | Description |
|---|---|---|
exponentialTimeoutCoefficient | Integer | Exponential factor by which the timeout will increase in each retry, in seconds. |
exponentialBackoffCoefficient | Integer | Exponential factor by which the backoff delay will increase in each retry, in seconds. |
initialBackoffDelay | Integer | Time, in seconds, that the app will wait until the next retry. |
retries | Integer | Maximum times the app will retry. |
timeout | Integer | Timeout until the attempt is considered a failure, in seconds. |
concurrency | Integer | Amount of simultaneous processes the event is able to perform. |
By adding this code to the Service, we are adding to the Client of this Service, the capability to handle events. At this point, we are not yet using the Client itself when handling the event.
Linking the event handler app
In the service-course-template directory, run vtex link and wait for the event to be fired by the events-example app. Upon successful reception, a log entry should appear in the console.
_10vtex login {accountName}