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 starting
Before you start coding your app, it is a good idea to review some concepts:
- Master Data
- VTEX IO service development
Data structure
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:
_24{_24 "$schema": "http://json-schema.org/schema#",_24 "title": "my_schema",_24 "type": "object",_24 "properties": {_24 "string_field_example": {_24 "type": "string"_24 },_24 "number_field_example": {_24 "type": "number"_24 },_24 "boolean_field_example": {_24 "type": "boolean"_24 }_24 },_24 "required": [_24 "number_field_example",_24 "string_field_example"_24 ],_24 "v-default-fields": [_24 "number_field_example",_24 "string_field_example"_24 ]_24}
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.
App setup
To create a Master Data app, follow these steps:
- Use the VTEX IO CLI command
vtex init
to copy the service-example boilerplate files to your computer. - Add the Master Data builder to your manifest file.
_10 …_10 “masterdata”: “1.x”,_10 …
- Add the following policies to your app’s
manifest.json
file:
_10[{_10 "name": "outbound-access",_10 "attrs": {_10 "host": "api.vtex.com",_10 "path": "/api/*"_10 }_10},_10{_10 "name": "ADMIN_DS"_10 }]
- Create a folder named
masterdata
at the root of your app. This will be your Master Data configuration folder. - Create a folder with the name of your data entity inside the
masterdata
folder. - Create a file named
schema.json
inside of your data entity folder. The result of steps 4 to 6 should look like this:
_10masterdata_10 | --myEntity_10 | --schema.json
- Put the JSON schema corresponding to the data entity in the
schema.json
file. - Run
vtex link
to make sure everything was set up correctly so far. - 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 yournode/node_modules
folder.
If you are using a development environment, use
vtex setup -i
.
- Change directory to the
node
folder of your app. - Run
yarn add @vtex/clients
to install theclients
package. - Open the file
node/clients/index.ts
and add the following imports:
_10import { masterDataFor } from '@vtex/clients'_10import { myEntity } from 'myStore.myApp' // Insert here the names of your data entity, store and app.
- You are importing your data entity typings from the app itself. Identify your app in the format
'{vendor}.{name}'
, according to the information in youmanifest.json
.
- If your app does not recognize the generated typings import, see the solution presented in the Typings section below.
- Still on the
node/clients/index.ts
file, you must create a new property for theClients
class, which declares a new available client. This represents the data entity you are working with. See this code example:
_10public get entity() {_10 return this.getOrSet('entity', masterDataFor<myEntity>('entity'))_10}
Triggers
To configure Master Data triggers in the app you created, follow these steps:
- Create a folder named
triggers
inside yourmasterdata/{dataEntity}
folder. - Create a JSON file inside the triggers folder.
- 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.
Typings
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:
_10import { myEntity } from 'myStore.myApp' // Insert here the names of your data entity, store and app.
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:
- Delete the
node/node_modules
folder. - Run
yarn
to reinstall dependencies. - Run
vtex setup
to regenerate the typings. - Run
vtex link
to check if everything is ok.
Data entities and schemas
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.
Usage
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
ormiddlewares
folder. Master Data functions are available via global context, withctx.clients.{entityName}.{function}()
. Below you can see more details on each function. These functions are equivalent to those performed by Master Data v2 endpoints.
Get
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.
_10ctx.client.Book.get(id: 'sdfg3543df5g4h3d5fh47d')
Getting the name and release date of a given book from the Book
entity.
_10ctx.client.Book.get(id: 'sdfg3543df5g4h3d5fh47d’, fields:['name', 'releaseDate'])
Save
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.
_10ctx.client.Book.save({_10 name: 'Dom Quixote',_10 releaseDate: 1605,_10 author: 'Miguel de Cervantes'_10})
Update
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.
_10ctx.client.Book.udpate(_10 id: 'sdfg3543df5g4h3d5fh47d',_10 {_10 name 'Dom Quixote',_10 rating: 4,5_10 }_10)
Save or update
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.
_10ctx.client.Book.saveOrUpdate(_10 id: ‘sdfg3543df5g4h3d5fh47d’,_10 {_10 name ‘Dom Quixote’,_10 rating: 4,5_10 }_10)
Saving a new document to the Book
data entity.
_10ctx.client.Book.saveOrUpdate({_10 name: 'Dom Quixote',_10 releaseDate: 1605,_10 author: 'Miguel de Cervantes'_10})
Delete
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.
_10ctx.client.Book.delete(id: 'sdfg3543df5g4h3d5fh47d')
Search
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.
_10ctx.client.Book.search(_10 pagination: {_10 page: 1,_10 pageSize: 10_10 },_10 fields: ['name', 'releaseDate'],_10 where: 'name=Miguel de Cervantes'_10)