Master Data is a powerful data base solution provided by VTEX to your store. You can use it in any VTEX IO app by connecting to the Master Data API, but this can become a repetitive task.

To improve your development experience, you can use the VTEX IO masterdata builder to create apps that use Master Data v2 features, such as saving new data and editing or deleting data, among others.

In this guide, you will learn how to create a Master Data CRUD app in VTEX IO.

Before you start coding your app, it is a good idea to review some concepts:

• Master Data
  • Basic components.
  • Architecture.
  • Starting to work with schemas.
  • Schema lifecycle.
• VTEX IO service development
  • Developing services on VTEX IO.

You will set up a VTEX IO service app according to Master Data basic elements.

Further along this guide, you will create a folder for each data entity that you want your app to interact with. And for each data entity you use in your project, you must create a corresponding JSON schema. See an example schema below:

We recommend you consider your desired data structure in this context before starting to code your app. Make sure you have your data entities planned and schemas written.

To create a Master Data app, follow these steps:

1. Use the VTEX IO CLI command vtex init to copy the service-example boilerplate files to your computer.
2. Add the Master Data builder to your manifest file.

3. Add the following policies to your app’s manifest.json file:

4. Create a folder named masterdata at the root of your app. This will be your Master Data configuration folder.
5. Create a folder with the name of your data entity inside the masterdata folder.
6. Create a file named schema.json inside of your data entity folder. The result of steps 4 to 6 should look like this:

7. Put the JSON schema corresponding to the data entity in the schema.json file.
8. Run vtex link to make sure everything was set up correctly so far.
9. Run vtex setup. This command will generate all typescript typings for your data entity. The typings will be available to be imported from your app. You can find them in your node/node_modules folder.

If you are using a development environment, use vtex setup -i.

10. Change directory to the node folder of your app.
11. Run yarn add @vtex/clients to install the clients package.
12. Open the file node/clients/index.ts and add the following imports:

- You are importing your data entity typings from the app itself. Identify your app in the format '{vendor}.{name}', according to the information in you manifest.json.

• If your app does not recognize the generated typings import, see the solution presented in the Typings section below.

13. Still on the node/clients/index.ts file, you must create a new property for the Clients class, which declares a new available client. This represents the data entity you are working with. See this code example:

To configure Master Data triggers in the app you created, follow these steps:

1. Create a folder named triggers inside your masterdata/{dataEntity} folder.
2. Create a JSON file inside the triggers folder.
3. Declare your triggers in the JSON file. They should be in an array in the same format described for the v-triggers field when setting up Master Data v2 triggers.

Note that whenever you make changes to your data entity schema, you must regenerate the typescript typings.

To generate your data entity typescript typings you must run the command vtex setup at the root of your project. Also, before finish coding and release your app, you must run vtex setup -i so that the typings will not be tied to your development workspace.

If you run into issues with the data entity typings generation or import, try generating the typings again. As described above, your generated data entity typings must be imported from the app itself, like this:

At this point, your app may not recognize the folder created by vtex setup, leading to an error in the code. If this happens to you, try these steps:

1. Delete the node/node_modules folder.
2. Run yarn to reinstall dependencies.
3. Run vtex setup to regenerate the typings.
4. Run vtex link to check if everything is ok.

You can set more than one data entity in you app. To do so, create one folder inside the masterdata folder for each data entity you wish to create. Each must have its own schema.json with a valid JSON schema.

Your app creates regular Master Data entities, which can be accessed via the Master Data v2 endpoints. The name of the entity created follows this pattern: {vendor}_{appName}_{entityName}.

Whenever you install or link a different version of your app, the Master Data builder cerates a new schema with the app’s name and version.

Now that your app is set up, you can code Master Data functions, such as saving, editing, retrieving or deleting data.

You may use Master Data functions in your app’s resolvers or middlewares folder. Master Data functions are available via global context, with ctx.clients.{entityName}.{function}(). Below you can see more details on each function. These functions are equivalent to those performed by Master Data v2 endpoints.

The get() function returns a document by its ID. You may specify what fields you want to be returned. If you do not, all fields in the document will be returned.

Arguments

Argument	Required	Type	Description
id	Yes	String	ID of the document you wish to retrieve.
fields	No	Array of strings	List of the names of the fields you wish to be returned. If not sent, all fields are returned.

Examples

Getting a complete document of the Book entity.

Getting the name and release date of a given book from the Book entity.

The save() function saves a new document to your data entity and returns the generated ID for that new document.

Arguments

This function’s arguments follow the format you described when setting up JSON schemas in your data structure.

Example

Saving a new document to the Book data entity.

The update() function an existing document by ID.

Arguments

Argument	Required	Type	Description
id	Yes	String	ID of the document you wish to update.
{document-data}	Yes	Corresponding to the types declared in the schema	This function’s arguments follow the format you described when setting up JSON schemas in your data structure. Required fields apply even for partial updates.

Example

Updating a document’s rating field in the Book entity.

The saveOrUpdate() function updates an existing document by ID or creates a new document if you do not send an ID.

Arguments

Argument	Required	Type	Description
id	No	String	ID of the document you wish to update. If you send an ID, the document is updated. Otherwise, a new document is created.
{document-data}	Yes	Corresponding to the types declared in the schema	This function’s arguments follow the format you described when setting up JSON schemas in your data structure. Required fields apply even for partial updates.

Examples

Updating a document’s rating field in the Book entity.

Saving a new document to the Book data entity.

The delete() function deletes a document by ID.

Arguments

Argument	Required	Type	Description
id	Yes	String	ID of the document you wish to delete.

Example

Deleting a document of the Book entity.

The search() function returns an array of documents that satisfy the criteria described in the arguments.

Arguments

Argument	Required	Type	Description
page	Yes	Integer	Number of the page you wish to retrieve.
pageSize	Yes	Integer	Number of documents that should be returned in each page.
fields	No	Array of strings	Names of the fields you wish to be returned. If not sent, all fields are returned.
where	No	String	Filtering condition.

Example

Searching names and release dates of all books by the author Miguel de Cervantes.