Now that we are actively using the data retrieved from Analytics, the next crucial step is to persist and update this data. To achieve this, we'll leverage Master Data, a database-as-a-service product from VTEX.
Master Data is the foundation for creating database architectures within a VTEX store. Initially designed for storing and organizing customer data, it has evolved into a versatile tool widely utilized by VTEX stores for business rule customizations and creating apps. The @vtex/api package provides a native Master Data client, accessible through ctx.clients.masterdata.
In this step, Master Data will be used to fetch data regarding the top N most viewed products, where N is a parameter that will be used to get the desired number of products.
Master Data uses the concept of data entities and JSON Schema to validate and index documents. One data entity can have many schemas, depending on how you need to use the data stored.
Creating a Master Data entity
First, you will use the Master Data API to create an entity and new schema in Master Data to save your product list. Use Postman or any other API client you prefer to send the cURL request presented in the right panel, providing the following information:
accountName: Name of your VTEX account.data_entity_name: Name of the data entity to be created in Master Data. Usecourse_backend_product_listto be consistent with our app.schema_name: Name of the schema to be created in Master Data. Usev1to be consistent with our app (identical to the one used inservice-course-template/node/event/updateLiveUsers.ts).userToken: Value of your user authentication cookie. To get your VTEX local token, runvtex local tokenin your terminal.
Saving data to Master Data
Now, to save the data, we need to check if the productSlug is already saved in Master Data. Use the searchDocuments method of the Master Data client in the node/event/liveUsersUpdate.ts file, as highlighted in the provided code.
Note: The
COURSE_ENTITYglobal constant iscourse_backend_product_list, the name of our Master Data schema.
Handling errors and exceptions
To ensure proper error handling, implement a try-catch structure, as presented in the code to the right.
Updating existing documents
If a product is already saved, we need to update it by incrementing its count. The Master Data client provides the createOrUpdateEntireDocument method for this purpose. Implement the incrementation in the Master Data entity in the liveUsersUpdate.ts file, right after the console.log({savedProduct}) line.
Linking the app
Finally, run vtex link and wait for an event to be fired. Once it does, check your terminal for the logs in the code.
Break the vtex link by typing ctrl + C and use the provided cURL command to inspect the updates on Master Data. Replace {{accountName}} with your VTEX account name.
To run a cURL on Windows, ensure to replace single quotes (
') with double quotes ("). For Windows versions earlier than Windows 10 (version 1803), download and install cURL.
Creating a Master Data entity
First, you will use the Master Data API to create an entity and new schema in Master Data to save your product list. Use Postman or any other API client you prefer to send the cURL request presented in the right panel, providing the following information:
accountName: Name of your VTEX account.data_entity_name: Name of the data entity to be created in Master Data. Usecourse_backend_product_listto be consistent with our app.schema_name: Name of the schema to be created in Master Data. Usev1to be consistent with our app (identical to the one used inservice-course-template/node/event/updateLiveUsers.ts).userToken: Value of your user authentication cookie. To get your VTEX local token, runvtex local tokenin your terminal.
Saving data to Master Data
Now, to save the data, we need to check if the productSlug is already saved in Master Data. Use the searchDocuments method of the Master Data client in the node/event/liveUsersUpdate.ts file, as highlighted in the provided code.
Note: The
COURSE_ENTITYglobal constant iscourse_backend_product_list, the name of our Master Data schema.
Handling errors and exceptions
To ensure proper error handling, implement a try-catch structure, as presented in the code to the right.
Updating existing documents
If a product is already saved, we need to update it by incrementing its count. The Master Data client provides the createOrUpdateEntireDocument method for this purpose. Implement the incrementation in the Master Data entity in the liveUsersUpdate.ts file, right after the console.log({savedProduct}) line.
Linking the app
Finally, run vtex link and wait for an event to be fired. Once it does, check your terminal for the logs in the code.
Break the vtex link by typing ctrl + C and use the provided cURL command to inspect the updates on Master Data. Replace {{accountName}} with your VTEX account name.
To run a cURL on Windows, ensure to replace single quotes (
') with double quotes ("). For Windows versions earlier than Windows 10 (version 1803), download and install cURL.