Getting Started: Data Model configuration

What this article is about

• What is a Data Model 
• What information does it store
• Where the file is located and what actions you can do with it
• 2 main sections: domainModelTypes, relationships
• Constraints 
• Connecting the Data Model and a Sheet configuration

TABLE OF CONTENTS

• What this article is about
• What is a Data Model, and what information does it store
• Where Data Models are stored
  • Available actions for the Model file
  • Create a new model
  • Edit the model 
  • Duplicate and Delete model configurations
  • Download the configuration
• Domain Model Types configuration
• Relationships
• Configuration of constraints in the Model
  • Constraints examples
  • 1. Constraints on the domainModelTypes
  • 2. Constraints on the relationships
• Connecting the Data Model to the Sheet Configuration

What is a Data Model, and what information does it store

Data Model configuration is a YAML format configuration file that holds information about all entities and their relations between them.

This is the primary source for the sheet configuration to know what slice of the Polarion data model is visible and editable within Powersheet.

The Data Model Configuration file consists of 2 main sections:

• domainModelTypes
• relationships

Additionally, there are constraints that can be applied to both domainModelTypes and relationships

Where Data Models are stored

Data Models are stored in the YAML format under Polarion Administration - Nextedy POWERSHEET - Data Models

There are 2 types of Data Models:

• Global
• Project-specific

where some of them can be applied on a global or project level, accordingly.

Available actions for the Model file

From the Data Models menu, apart from having the overview of all configured models, it is possible to perform the following actions:

• Create a new model

When creating a new Data Model, it is possible to choose what configuration to use as a 'base' for it.

Select "System Default" if you have none, or if unsure which one to use from already existing model configurations.

• Edit the model 

You can edit the Model from the Administration section as well as from the Powersheet menu. 

In this case, go to Menu - Configuration - Edit Data Model

• Duplicate and Delete model configurations

Duplicate functionality is especially nice in case you want to perform some slight adjustments to one of the already existing Models.

In this case, instead of creating a new one, it is possible just to duplicate and modify the already existing configuration.

• Download the configuration

When opening a configuration file itself, it is also possible to download it in a YAML format. 

Domain Model Types configuration

The Domain Model types section defines the entities that are shown on the Powersheet, as well as all their properties. 

It uses the nested logic typical of YAML, where the properties are always one level deeper than the parameter they relate to.

domainModelTypes:
   Chapter:
     polarionType: heading

   epic:
    polarionType: epic
    properties:
      description:
      outlineNumber:

• first level - name of entity (required)
• polarionType - polarion entity type ID (optional)
• properties - a list of fields to include in the model for the given entity (optional)

Later on, in the sheet configuration, you refer to the entities and their properties defined in the Model. This is why whenever you find out that you need to add any extra column for a new field, it shall first be added to the Data Model configuration.

Relationships

The Relationships section defines the relation between the selected domain model types, as well as other properties of this connection.

relationships:
    - from: epic
      to: Chapter
      cardinality: many-to-one
      storage: linkedWorkItems
      linkRole: parent
      direct:
        name: chapter
      back:
        name: epics

Where:

• from - Source entity of the relationship
• to -  Target entity of the relationship
• cardinality - many-to-many, one-to-many, or many-to-one
• storage - 
• linkRole - Link Role to be used in the dedicated pair
• direct - Navigation property pointing to the 'from' entity
• back - Navigation property pointing to the 'to' entity
• name - name of the entity

So this example relationship above shows that multiple epics can be linked to one chapter with a parent link role. 

Configuration of constraints in the Model

Constraints can be configured on a DomainModelType or on a Relationship.

They are used to specify additional parameters that shall be respected when working with the data.

Actions:

There are 3 main action constraints:

• load
• save
• pick

Each of them used to define the query according to the selected action.

Currently, the constraints can be applied only to the documents and their properties.

constraints:
  load/save/pick:
    document:
      id: folderID/documentID
      type: design_reqs_spec
      component: $context.source.document.component
      

This way, you may have any possible flexible configuration when deciding about the item location.

constraints:
  # load items in this relationship with the the following constraints
  loadFromQueries: # or just 'load' for short
    # property or navigation property name
    document:
      # property or navigation property name with Breeze query notation
      type: design_reqs_spec
      component: $context.source.document.component
      
  # additional queries when creating new item in this relationship
  saveToQueries: ... # or just 'save' for short

  # additional queries when using item picker (dropdown)
  pickFromQueries: ... # or just 'pick' for short

Constraints examples

1. Constraints on the domainModelTypes

• Load only user_need WIs from a UserNeedSpecification document:

domainModelTypes:
    UserNeed:
      polarionType: user_need
      properties:
         description:
      constraints:
        load:
          document: 
            id: Requirements/UserNeedSpecification

relationships:
  - to: UserNeed
    from: SystemRequirement
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements
      constraints:
        loadFromQueries: # or just 'load' for short
          document:
            type: system_reqs_spec

Connecting the Data Model to the Sheet Configuration

Once the Model is configured, it can be used in connection with the Sheet. 

The connection between the Data Model and a dedicated sheet configuration is defined in the "sources" section of the sheet configuration.

The most important properties are:

• id (required): unique ID for the given connection;
• model (required): specify the Model name that shall be connected to this sheet;
• title: human-readable name for this connection;
• query:
  from:entityName(required): specify the starting point for the configuration breakdown structure.  

sources:
  - id: "Powersheet"
    title: User Need
    model: rtm
    query:
      from: UserNeed

For any assistance, please don’t hesitate to reach out by submitting a ticket here.