This guide provides step-by-step instructions on how to create a VTEX IO service to interact with Master Data v1. This solution is recommended if you need to update Master Data v1 field values based on a trigger or whenever adding or updating a document.

Discover how to effectively leverage Master Data capabilities through your service in the upcoming sections.

Make sure you meet the technical requirements to complete this project:

• Experience developing in Typescript language.
• Having VTEX IO CLI installed.

To begin setting up your service to interact with Master Data v1 on VTEX IO, follow these steps to initialize your project using the service-example template:

1. Open the terminal.
2. Type the command vtex init.
3. Select the service-example template.
4. Enter a folder name or use the default name, which is the same as the selected template.

Configure permissions for your application to access Master Data by following the steps below:

1. Open the project folder in your preferred code editor.

2. Open the manifest.json file located at the root of the project.

3. Add the following structure to the policies section:

   
   

   _10

   {

   _10

   "name": "outbound-access",

   _10

   "attrs": {

   _10

   "host": "api.vtex.com",

   _10

   "path": "/dataentities/*"

   _10

   }

   _10

   },

   _10

   {

   _10

   "name": "ADMIN_DS"

   _10

   }

   
   

Create a client class in TypeScript to extend the functionality of MasterData from the @vtex/api module:

1. Inside the node folder, create a clients folder if it does not exist.

2. Create a Typescript file in the clients folder. In this example, the file will be named md.ts.

3. Create a class that extends from the MasterData class from the @vtex/api module.

   
   

   _10

   import { MasterData } from '@vtex/api'

   _10

   export default class MD extends MasterData {}

   
   

4. Modify the class to include the constructor and headers:

   In this class, we will call the constructor and, within it, the super method, passing the context and options received in the constructor class.

   
   

   _13

   import { IOContext, InstanceOptions, MasterData } from '@vtex/api'

   _13

   _13

   export default class MD extends MasterData {

   _13

   constructor(context: IOContext, options?: InstanceOptions) {

   _13

   super(context, {

   _13

   ...options,

   _13

   headers: {

   _13

   {{app-key}}

   _13

   {{app-token}}

   _13

   },

   _13

   })

   _13

   }

   _13

   }

   
   

   In this class, we will have access to several methods extended from the Master Data class, including:

   Method name	Description
   getDocument	Retrieves a document by its ID for a given data entity, with specified fields.
   createDocument	Creates a new document in the specified data entity.
   createOrUpdateEntireDocument	Creates or updates an entire document in the specified data entity.
   createOrUpdatePartialDocument	Partially creates or updates a document in the specified data entity.
   updateEntireDocument	Updates an entire document by its ID for a given data entity.
   updatePartialDocument	Partially updates a document by its ID for a given data entity.
   searchDocuments	Searches for documents in the specified data entity, with various search parameters and pagination.
   searchDocumentsWithPaginationInfo	Searches for documents and returns data with pagination information.
   scrollDocuments	Scrolls through documents in the specified data entity with various search parameters.
   deleteDocument	Deletes a document by its ID for a given data entity.

5. Add the desired method. The example below uses the getDocument method:

   
   

   _10

   public getDocumentById(

   _10

   dataEntity: string,

   _10

   id: string,

   _10

   fields: string[]

   _10

   ): Promise<any> {

   _10

   return this.getDocument({ dataEntity, id, fields })

   _10

   }

   
   

After creating our Client class, you need to register it in the index.ts file within the same clients folder:

1. Open the index.ts file in the clients folder.

2. Import the new client (e.g., MD) and add it to the Clients class, as exemplified below:

   
   

   _10

   import { IOClients } from '@vtex/api'

   _10

   import MD from './md'

   _10

   _10

   // Extend the default IOClients implementation with our own custom clients

   _10

   export class Clients extends IOClients {

   _10

   public get MD() {

   _10

   return this.getOrSet('MD', MD)

   _10

   }

   _10

   }

   
   

Implement a middleware function to handle interactions between your service and Master Data, executing the method we created and returning the response based on the context:

1. Inside the node folder, create a middlewares folder if it does not exist.

2. Create a file named masterdataMiddleware.ts in the middlewares folder.

3. Add your TypeScript code to masterdataMiddleware.ts.

   Following the example in the previous sections to illustrate this step, in this middleware, we will return the call to the method created to a variable and then add this variable to the context body. The method expects to receive an entity, a document ID, and an array of fields to be returned in the response.

   
   

   _22

   export async function masterdataMiddleware(

   _22

   ctx: Context,

   _22

   next: () => Promise<any>

   _22

   ) {

   _22

   const {

   _22

   clients: { MD },

   _22

   } = ctx

   _22

   _22

   const response = await MD.getDocumentById(

   _22

   'CL',

   _22

   '0807f150-68bb-11Ec-82ac-12fdbe358f3f',

   _22

   ['id', 'email']

   _22

   )

   _22

   _22

   ctx.status = 200

   _22

   _22

   ctx.body = {

   _22

   response,

   _22

   }

   _22

   _22

   await next()

   _22

   }

   
   

Configure a dedicated route in your service that will be accessed through your store's endpoint:

1. Open the service.json file in the node folder.

2. In the routes section, define the routes object as shown below. In this example, we will define the path as /_v/md/get-document and make this route public.

   
   

   _10

   "routes": {

   _10

   "masterdata": {

   _10

   "path": "/_v/md/get-document",

   _10

   "public": true

   _10

   }

   _10

   }

   
   

3. Open the index.ts file in the node folder.

   In this file, you will see a new instance of service created. You will register your route within the routes object.

4. Register the route within the routes object.

   
   

   _10

   masterdata: method({

   _10

   GET: [masterdataMiddleware],

   _10

   }),

   
   

The masterdata attribute is the route ID created in the service.json file.

The masterdata attribute receives a function containing an object where we can pass various middleware mappings. In this case, we will use the HTTP method GET, which receives an array where we must declare the middleware created in previous sections.

Finalize setup by linking your project to a development workspace and testing the configured service routes:

1. In the terminal, navigate to the root of the project.

2. Run the command vtex link.

   After linking, you should see the following message:

   
   

   _10

   **info:** *Available service routes: https://{{workspace}}--{{accountName}}.myvtex.com/{{path}}

   
   

3. Access the service route from the previous step in your browser.

   Following the example of a service to retrieve a document, you should see a response with the fields defined in the middleware:

   
   

   _10

   {

   _10

   "response": {

   _10

   "id": "0807f150-68bb-11Ec-82ac-12fdbe358f3f",

   _10

   "email": "john@mail.com"

   _10

   }

   _10

   }

   
   

These instructions enable you to configure clients, middleware, and routes to set up a VTEX IO service for interacting with Master Data v1. Note that there are various methods and configurations beyond this guide to further customize and optimize your integration with VTEX IO and Master Data.