Data model package

This topic describes the Data model package section, how to create and run a Data model (Transporter) package, and its other features.

The Data model package page allows you to create and manage Data model (previously called Transporter) packages, which contain the Data model structure (i.e. metadata) resulting from comparing two Data model snapshots. You can execute Data model packages to transport and apply the structure of the Data model contained in the package to the desired Data model of a Platform.

This feature is commonly used to transport the structure of a Data model from a "Development" environment to a "Production" environment.

In this case, usually the same Data model exists in both environments, and after making new changes to the Data model in the "Development" environment, that very Data model is transported to the "Production" environment.

To transport the new changes from a “Development” environment to a “Production” environment, proceed as follows:

1. Create a Data model snapshot in the "Production" environment and give it a name, for example, "PRODUCTION-SNAPSHOT"

2. Download the "PRODUCTION-SNAPSHOT" to your local machine

3. Upload the "PRODUCTION-SNAPSHOT" to the "Development" environment

4. Create a Data model snapshot of the Data model in the "Development" environment and give it a name, for example, "DEVELOPMENT-SNAPSHOT"

5. Create a Data model package by using both the snapshots "PRODUCTION-SNAPSHOT" and "DEVELOPMENT-SNAPSHOT" located in the "Development" environment

6. Download the Data model package to your local machine

7. Upload the Data model package in the "Production" environment and execute it

To access the Data model package section, access the System Administration area of the desired Platform and click on the Data model packages tile to open the Data model package page.

In the Data model package section, you can see all existing Data model packages and their main information; the table is sortable and searchable using the interactive header fields. You can also show or hide columns to your liking by clicking the Column chooser button in the upper right corner of the table.

The table contains the following information:

• Name. This column displays the name of each Data model package

• Target Data model (was Target db). This column displays the name of the target Data model which each Data model package will update (if executed)

• Comments. This column displays additional comments about each Data model package. You can click on the desired column cell to edit a comment

• Run. This column displays a button that you can click to execute the corresponding Data model package

• Last run. This column displays the date and time of the last run of each Data model package, in the following format: DD/MM/YYYY, HH:SS

• Result. This column displays the result of the last run of each Data model package.

Creating a Data model package

To create a Data model package, proceed as follows:

1. From the Data model package section of the desired Platform, click on the blue plus button  next to "Data model package" in the upper left corner to bring up the "New Data model package" configuration panel. You can also do this in the Data model snapshot page by selecting at least one desired Data model snapshot and clicking on the "DATA MODEL PACKAGE" button

2. Snapshot Selection. Choose the source Data model snapshot from the left dropdown list and choose the target Data model snapshot from the right dropdown list. You can click on the arrow in the middle to switch their position, if needed. Click the "NEXT" button to go to the Comparison step
    

3. Snapshot Comparison. This page displays changes to elements between the source and target Data model snapshots. On the left is a list of the types of Data model elements that have been modified. You can click on an item of the list to filter the table on the right, which displays the modified elements along with the following information:

   • Object Type. This column displays the icon related to the type of element

   • Object source name. This column displays the name of each element in the source Data model snapshot

   • Object target name. This column displays the name of each element in the target Data model snapshot

   • Action. This column displays the type of action that will be performed on each element when the Data model package is executed. The actions that display here are: "Create", "Update", or "Delete". If an "Update" action status appears, a "Log" icon is displayed
      
     Click it to open a popup window where you can check the specific change to that element
      

   You can click on one or more elements in the table on the right to include or exclude the action the Data model package would execute on those elements (if executed).

   Data model elements that can be transported

   are the following:

   • Entities

   • Relationships

   • Cubes

   • Entity format configurations (Row templates)

   • Data readers

   • Rules

   • Nexel Writeback definitions

   • BEAM Forecasting scenarios

   • BEAM Clustering scenarios

   • Procedures

   • Time range

   • Azure AutoML scenarios

   • API queries

4. 

   The comparison between elements is done by using internal identifiers (i.e. "idx" value for Cubes) for each type of element and not the display name. This is because the display name of elements can change during development and, therefore, cannot be used as an identifier for the comparison.

5. Summary. Here you can see the summary of all the actions that you have included in the Data model package in the previous step. You can click on the "CHECK CONSISTENCY" button to check for any inconsistencies between the source and target Data model snapshots as well as the actions that you have included and excluded (i.e. deleting an Entity that is part of the Structure of a Cube that will be updated. In this case, a warning message will appear). In the event of warning or error messages caused by the inclusion or exclusion of some actions, you can go back to the previous step and include or exclude them to solve such inconsistencies.
   If you cannot solve the inconsistencies in this way, then you may have to manually align the source Data model with the target Data model from the Data model area and recreate the corresponding snapshots
    

   You cannot create a Transporter package if the consistency check is not successful.

6. SAVE. Here you must enter the name of the package in the "Name" field and add any additional comments in the "Comment" field. You can also enable the "Backup" option, which automatically creates a backup of the target Data model when you execute the Transporter package.
   In addition, you can enable the "Maintenance mode" option, which automatically puts the target Data model in maintenance mode before running the Transporter package
   

7. Click on "SAVE" to save the Data model package.

Managing a Data model package

The Data model packages page allows you to perform the following management tasks on existing packages:

• Edit a Data model package

• Delete a Data model package

• Upload a Data model package to the Platform you are logged into

• Download a Data model package to your local machine

To edit a Data model package, select it to bring up the package configuration panel and modify the desired available options.

The package configuration panel displays additional information under the following menus:

• Execution command. This menu contains the commands that you can use to run the package via the CLI Automation feature

• Log. This menu contains a log that provides information about the execution of the package.

To delete Data model packages, select the desired ones and then click the trash icon.

To upload Data model packages,click on the "UPLOAD" button and choose the .trsp file containing the desired packages.

To download Data model packages, select the desired ones and then click the "DOWNLOAD" button. A .trsp file containing the selected packages will download to your local machine.

Running a Data model package

To run a Data model package, proceed as follows:

1. From the Data model package page, click on the   button under the "Run" column of the desired Data model package to run it.
    

2. Board will automatically choose the target Data model that has been configured in the Data model package and perform a pre-execution check where it will list any possible warning or error messages caused by inconsistencies found between the source and target Data models.
   You can manually change the target from the "Target DB" dropdown list.
    

3. Click on "RUN PACKAGE" to run the package

   You cannot run a Data model package if errors are detected during the pre-execution check.

The Data model package only transports the structure (i.e. metadata) of a Data model and not the data contained inside.

When you execute a package, the changes are applied as if they were manually made by a user. This means that existing data in the target Data model may be lost in various cases, such as modifying the Structure of Cubes, adjusting the Time Range, or changing the Max item number of an Entity etc.