Set up an MDM project in VS Code

After installing the Semarchy extension, you will start with an empty window. This page describes the steps to set up a dedicated workspace and create essential design files using the Semarchy extension for VS Code.

Create a workspace

A workspace in VS Code is a collection of files and folders that you work on. This is where you store all your MDM project files, including logical models, objects, rules, etc. Here is how to create a workspace:

  1. From the File menu, select Open Folder.
    A file dialog opens.

  2. Navigate to the directory where you want to create your workspace, and click New Folder.

  3. In the New Folder dialog, enter a name for your workspace.

  4. Click Create.

  5. Click Open to open the workspace.

Create design files

When designing an MDM project in VS Code, each object in your project is represented as an individual file.

All design files in the Semarchy xDM extension use the YAML format, identified by a .yml extension.

Add a file to the workspace

To create a new design file:

  1. In the Explorer view, right-click on the folder within your workspace where you want to create the file.

  2. From the context menu, select New File.

  3. Enter a name for the new file, followed by the object type, and press Enter. Make sure to include the file extension (i.e., <ObjectName>.<ObjectType>.yml).

You can repeat this process to create folders and subfolders within your workspace, using the New Folder option instead. This helps to keep your project organized and makes it easier to manage different components, as recommended by best practices.

Define an object

Regardless of a file’s name, each object is defined by the _type property included within the file. You need to define the _type property in every file to specify the corresponding object type.

For example, a model file should include the following basic content:

# Object type
_type: Model
# Object name
name: <ModelName>

For the full list of available object types, see Objects reference.

Declare references

To reference another object within a design file, use the <ObjectType>.<ParentObjectName><ObjectName> syntax.

Specifying the parent object name is optional if the referenced object is at the root of your workspace. This is likely the case when referencing a model.
Example 1. Referencing a model

Within the Customer.Entity.yml file below, the model property specifies a reference to the CustomerB2C model.

# Object type
_type: Entity
# Object name
name: Customer
# Some entity-specific properties
label: Customer
pluralLabel: Customers
description: Entity containing information about customers.
# Reference to the model
model: Model.CustomerB2C
Example 2. Referencing an entity

Within the CommunicationPreferences.Entity.yml file below, the parentEntity property specifies a reference to the Customer entity.

# Object type
_type: Entity
# Object name
name: CommunicationPreferences
# Some entity-specific properties
label: Communication Preferences
description: Entity containing information about customers' communication preferences.
# Reference to the Customer entity within the CustomerB2C model
parentEntity: Entity.CustomerB2C.Customer

Best practices for setting up an MDM project

You have the flexibility to name and organize these files according to your preferences. However, it is strongly recommended to follow a meaningful naming convention and maintain a consistent structure to enhance readability, maintainability, and collaboration.
Here are some guidelines:

  • Use descriptive names: choose file names that clearly describe the content and purpose of the file.
    For example, instead of naming a file Customer.yml, opt for Customer.Entity.yml to specify that the file defines an entity.

  • Include the object type: incorporate the type of design element into the file name.
    For example, Customer.Entity.yml describes an entity named customer and CustomerB2C.Model.yml describes a model for an MDM project named Customer B2C.

  • Maintain a consistent structure across all files: being consistent in the structure of your file names aids in quickly locating files and understanding their relationships within the project.
    For example, use a pattern such as <EntityName>.<ObjectType>.yml where <EntityName> is the name of the entity, and <ObjectType> specifies the type of design element (e.g., entity, model, workflow, etc.).

  • Organize your files in a structured manner: consider creating a directory structure that groups related files together.
    For example, you might have separate directories for entities, reference relationships, dashboards, workflows, etc.

Example of workspace organization
/semarchy-workspace
├── /CustomerB2C.Model.yml
│
├── /entities
│   ├── Person.Entity.yml
│   └── Product.Entity.yml
│   └── PersonProduct.Entity.yml
│
└── /workflows
    ├── ReviewNewProduct.Workflow.yml
    └── CreatePerson.Workflow.yml

Once you are familiar with the fundamentals of setting up a project in VS Code, you can begin creating a model and populating it with entities and other data objects according to your project’s specifications.