2. Handling and receiving events

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.

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-example app 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-template app to listen to events emitted by the events-example app.
  • Create an event handler function for processing the events received from the events-example app.
  • Configure the service-course-template app 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:

FieldTypeDescription
exponentialTimeoutCoefficientIntegerExponential factor by which the timeout will increase in each retry, in seconds.
exponentialBackoffCoefficientIntegerExponential factor by which the backoff delay will increase in each retry, in seconds.
initialBackoffDelayIntegerTime, in seconds, that the app will wait until the next retry.
retriesIntegerMaximum times the app will retry.
timeoutIntegerTimeout until the attempt is considered a failure, in seconds.
concurrencyIntegerAmount 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.


_10
vtex login {accountName}

Contributors
1
Photo of the contributor
Was this helpful?
Yes
No
Suggest Edits (GitHub)