Skip to main content
Matrix42 Self-Service Help Center

Configuration Project Development

Overview

Configuration Packaging is installed as an additional extension and can be found in Administration application → Extensions → Configuration Projects navigation item:

CP_datasetview1.png

The Configuration Projects page provides the following information on the available in the system packages under development:

  • Name: the manually created name of the project;
  • In Progress: current status of the project development;
  • Last Update: date and time of the latest recorded changes in the project;
  • Developing By: list of users who are currently working on the project and are automatically recording the changes. If the project is not set to In progress by any user this field is empty. Also, the user is not shown if any changes are currently applied or edited manually while the project is not set to In progress. 

All the changes, either recorded automatically, added manually, or edited, as well as the change contributors, are tracked in the Change Log of the project.

Add Configuration Project

To add a new project click Add Configuration Project action:

CP_add_new_project.png

Fill out the necessary information and click Done:

Screen Shot 2020-06-16 at 4.09.46 PM.png

The Name and Description are available in the package.json file of the exported project. 

The created project is available for all users of the system who have access to the Configuration Projects extensions and can be picked for development by one or several users at the same time.

The project is created but the automatic recording of the changes has not started yet.

Start Recording

Only one project can be actively developed by the same user on the current environment at the same time. 

To start automatic recording in the Configuration Projects:

  1. Click on the necessary Configuration Project;
  2. Apply Start Recording action:

start_recording1.png

The project you are currently developing is marked in bold.

The automatic recording is performed for all newly added and all changes of the user interface elements, layouts, schema modifications, and objects that are present in the default installation of the Matrix42 Solution Builder. All required and essential for the Configuration Project package changes are tracked automatically.

Stop Recording

Stop Recording when all the necessary changes were introduced via the user interface and automatically recorded to the project, or the development should be paused, or you want to switch to another project.

In the Configuration Projects navigation item:

  1. Click on the necessary Configuration Project;
  2. Apply Stop Recording action:

CP_stop_recording.png

Changes are no longer recorded automatically to the project and you can Start Recording in another project.

At the same time, all projects can be edited manually without changing the recording status. Therefore, the manually applied changes in one project will not interfere with another project that is currently In Progress

Project Preview

Click on the Configuration Project for preview:

CP_preview1.png

 

  • Name: the name of the project;
  • Owner: a person who created the Configuration Project;
  • Active Users: persons who Started Recording of the project and are considered by the system as active users;
  • Created: date and time when the project was created;
  • Last Updated: date and time of the latest applied changes in the project;
  • Current Version: current version of the project under development;
  • Change Log: lists a set of changes that were applied in the scope of the Configuration Project. Includes:
    • entity type
    • entity name
    • optional enumeration of the applied changes if they are automatically grouped and optimized in one record (for automatic recording)
    • operation type (create, update, or delete marked with the color label of the record), date, and contributor name

Change Log does not include all changes as they can be optimized, combined, automatically removed due to redundancy or not tracked by design. Therefore, all objects that are considered as required and essential for the Configuration Project are tracked, e.g. new User Role; the new user added to the system or changes in the Global System Settings are not tracked by design.

For more details see Change Optimization section.

Edit Project

On the preview page, click Edit action to modify the general information of the Configuration Project, manually introduce new, edit or delete available changes of the project, as listed on the dedicated views.

General

  • Name: the name of the project that later will be used in the package export and subsequent installation on another environment.
  • Description: optional description of the project.

Schema

This view provides a list of schema changes that were recorded automatically or added/edited manually for the current Configuration Project.

Configuration Items section 

Schema changes in the Configuration Items may look as follows:

CP_Schema_CI.png

  • Name: the name of the Configuration Item;
  • Operation: operation type used for the Configuration Item (add, update, delete);
  • Date: date and time of the change;
  • Changed By: author of the change;
  • Version: package version indicating when the change was introduced;
  • Order: information denoting in which order the changes of the package are installed. The order is assigned automatically with the first export of the package and if necessary can be further edited manually. See Schema Scripts Order section for more details;
  • Description: automatically generated description of the change.

Possible operations when adding or editing the Configuration Item (CI) change manually:

  • update CI: this operation allows you to update CI property and add/delete Data Definition from the CI;
    • CI properties store the settings of the Configuration Item, like display name, description, CI type, etc. See Configuration Item page for more details.
    • Data Definitions (DD) are the main components of the CI that create a new object. Each DD is represented by a table in the database and contains attributes providing the Schema for user data. See Configuration Item page for more details.
  • add CI: choose from the list of available in the system Configuration Items;
  • delete CI: this operation requires the technical name and ID of the Configuration Item. Tend to use the automatic recording to fill out all necessary fields correctly. Please note, that in case of manual editing the system uses the Configuration Item ID as the main identifier of the object that will be deleted by the installed package. Configuration Item name is not verified by the system or bound to the Configuration Item ID and may be used for your convenience for differentiating the manually added change.

CP_CI_change_delete_CI.png

Configuration Items section: example of delete operation for the Configuration Item

Schema script order field is available for editing once the Configuration Package is exported.  The Export to Package action assigns the schema scripts execution order automatically for each change in the package.

Data Definitions section

Schema changes in the Data Definition may look as follows:

CP_DD_edit.png

  • Name: the name of the Data Definition;
  • Operation: operation type used for the Data Definition (add, update, delete);
  • Date: date and time of the change;
  • Changed By: author of the change;
  • Version: package version indicating when the change was introduced;
  • Order: information denoting in which order the changes of the package are installed. The order is assigned automatically with the first export of the package and if necessary can be further edited manually. See Schema Scripts Order section for more details;
  • Description: automatically generated description of the change.

Possible operations when adding or editing the Data Definition (DD) change manually:

  • update DD: this operation allows you to update the property, change attribute of the Data Definition, or add new relation;
    • properties store the general settings of the Data Definition, like display name, description, class type, etc. See Data Definition: General page for more details.
    • attributes of the Data Definition represent the columns in the database tables. See Data Definition: Attributes page for more details.
    • relations allows you to add relations between DDs. See Data Definition: Relations page for more details.
  • add DD: choose from the list of available in the system Data Definitions;
  • delete DD: this operation requires the technical name and ID of the Data Definition. Tend to use the automatic recording to fill out all necessary fields correctly. Please note, that in case of manual editing the system uses the Data Definition ID as the main identifier of the object that will be deleted by the installed package. Data Definition name is not verified by the system or bound to the Data Definition ID and may be used for your convenience for differentiating the manually added change.

CP_DD_update.png

Data Definitions section: example of manually updating a Data Definition property Data listed in the Changes section of the page

Layouts 

This view provides a list of changes related to the Layouts and Global Localization Strings that were recorded automatically or added/edited manually for the current Configuration Project.

Layouts

Changes in the Layouts section may look as follows:

CP_Layouts_changes.png

  • Name: the name of the Layout;
  • Operation: operation type used for the Layout (add, update, delete);
  • Date: date and time of the change;
  • Changed By: author of the change;
  • Version: package version indicating when the change was introduced;
  • Order: information denoting in which order the changes of the package are installed. The order is assigned automatically with the first export of the package and if necessary can be further edited manually. See Schema Scripts Order section for more details;
  • Description: automatically generated description of the change.

Layouts section lists all possible changes in the project that include the following types of Layouts:

Only published layouts are exported to the package.

Possible operations when adding or editing the Layout change manually:

  • update: this operation allows you to update the property, localization, layout view or audience of the Layout;
  • add: choose the layout type and the name of the layout from the list of available in the system items;
  • delete: this operation requires the Layout type, Display Name, and ID of the Layout. Tend to use the automatic recording to fill out all necessary fields correctly. Please note, that in case of manual editing the system uses the Layout ID as the main identifier of the object that will be deleted by the installed package. Display Name is not verified by the system or bound to the Layout ID and may be used for your convenience for differentiating the manually added change.

CP_Layout_add.png

Layouts section: example of manually adding a Dataset View to the Configuration Project

Global Localization Strings

Changes in the Global Localization Strings section may look as follows:

CP_global_loc_string2.png

  • Name: the name of the Global Localization Strings;
  • Operation: operation type used for the Layout (add, update, delete);
  • Date: date and time of the change;
  • Changed By: author of the change;
  • Version: package version indicating when the change was introduced;
  • Order: information denoting in which order the changes of the package are installed. The order is assigned automatically with the first export of the package and if necessary can be further edited manually. See Schema Scripts Order section for more details;
  • Description: automatically generated description of the change.

Global Localization Strings can be added in the Layout Designer and imported/edited in the Administration application → User Interface → Localization (use Reload action to retrieve the latest changes to the list). 

Possible operations when adding or editing the Global Localization Strings change manually:

  • update: this operation allows you to update the localization string;
  • add: choose the Localization String name from the list of available in the system items;
  • delete: this operation requires the Display Name and Localization String ID.
    • Automatic recording of delete operations: for the proper functioning of the generated in the package script and correct data recording, it is recommended to use the automatic recording for the delete operations.
    • Manual adding of delete operations: in case the delete operation is added manually to the change log, the system uses the specified Localization String ID as the main identifier of the object that will be removed from the system. Display Name is not verified by the system or bound to the Localization String ID and may be used for your convenience for differentiating the manually added change.

CP_global_loc_add.png

Global Localization Strings section: example of manually adding a Localization String to the Configuration Project

Objects

This view provides a list of changes related to other Objects that are considered by the system as required and essential for Configuration Project development. These include changes in Applications, Navigation Items, Data Queries, User Roles, Actions. Objects section does not include changes in the data, for instance, a new User Role is tracked automatically by the system and is recorder to the package while adding a new user to the User Role is not tracked.

Not all objects are tracked automatically. For a complete list of tracked objects and object changes see Configuration Package features section.

Changes in the Objects section may look as follows:

CP_Objects.png

  • Name: the name of the Object;
  • Operation: operation type used for the Object (add, delete);
  • Date: date and time of the change;
  • Changed By: author of the change;
  • Version: package version indicating when the change was introduced;
  • Order: information denoting in which order the changes of the package are installed. The order is assigned automatically with the first export of the package and if necessary can be further edited manually. See Schema Scripts Order section for more details;
  • Description: automatically generated description of the change.

Possible operations for manual editing of the Object changes: 

  • add/update: choose the Configuration Item and the name of the Object from the list of available in the system items. Additionally, you can specify:
    • Include Multi Relations allows selecting the related to the object items that should be exported to the package (N:M relations), for instance, an Action can be used in several Applications. Include as many multi relations as necessary for the object. Make sure that the environment where the package is going to be installed already has the object referenced by the multi relation. Single relation is considered as a part of an object and is included in the package by default;
    • Always Full Import option by default is disabled so that the object will be installed only once on the target system and the changes will be merged if such an object already exists. Select the checkbox to always run the full import of the object.  Please note, that with this option enabled, the custom changes of this object will be overwritten each time the package is installed.  From a technical perspective, the enabled Always Full Import option generates scripts that are run in the merge mode and have Register="false" property during installation on the target system.
  • delete: this operation requires the Configuration Item, Display Name, and Object ID. Tend to use the automatic recording to fill out all necessary fields correctly. Please note, that in case of manual editing the system uses the Object ID as the main identifier of the object that will be deleted by the installed package. Display Name is not verified by the system or bound to the Object ID and may be used for your convenience for differentiating the manually added change. 

CP_edit_objects.png

Objects section: example of manually adding/updating an Object in the Configuration Project.

Layout objects can not be managed from the Object view and must be handled in the Layouts section:

CP_obj_warning.png

Workflows

The package stores only the newest changes and only one and the latest version of the workflow.

The workflow that is set to run on Matrix42 Worker workflow engine is not published. Workflows that are running on AppFabric workflow engine are published automatically.

The system automatically tracks only workflows that have the status "Released" and the Configuration Project is actively tracked (is set to "In Progress").

Changes in the Workflows section may look as follows:

CP_workflows.png

  • Name: the name of the Workflow;
  • Operation: operation type used for the Object (update);
  • Date: date and time of the change;
  • Changed By: author of the change;
  • Version: package version indicating when the change was introduced;
  • Order: information denoting in which order the changes of the package are installed. The order is assigned automatically with the first export of the package and if necessary can be further edited manually. See Schema Scripts Order section for more details.

Possible operations for manual editing of the Workflow changes: 

  • add/update: choose the Workflow from the list of available in the system items:

CP_workflows_update.png

Workflows section: example of manually adding/updating the Workflow in the Configuration Project.

Files

This view includes the following categories:

CP_files.png

  • Assemblies: allows adding the .dll files. Choose from the list of suggested files. The list includes only custom files that have been changed in the system. The files that are a part of the standard system are not suggested in the list. Use Assemblies section to include assemblies from the following folders:
    • bin
    • svc\bin
    • ServiceRepository\BinaryComponents' 
  • Front-End Workspaces: choose the workspace from the list. The package will include everything that is present in the selected folder.  Workspaces include front-end resources (like Javascript libraries, CSS, images, etc.) required for building user interfaces in Matrix42 platform. For more details see Front-End Workspaces page.
  • Files: allows adding other files that do not belong to any of the available sections of the Configuration Project, like images or icons that are not a part of the Workspaces, configuration files, other special files, like .XML, etc.

Ways to define the path and the file:

Define the relative path to the directory and files, wildcards * and ? are supported (e.g. Web\*.ico).

Use \**\ before mask to search in all subdirectories (e.g. Web\Images\**\*.png):

CP_file_path.png

Samples:

Case Path
Specific file DataGateway\Apps\Matrix42.DataGateway.Inventory\Extensions\AntiXssLibrary.dll
Files with '.png' extension from 'Web\Images' directory (doesn't include files from the subdirectory) Web\Images\*.png
Files with '.png' extension from 'Web\Images' directory and all subdirectories Web\Images\**\*.png
All files from 'Web\Images' directory and all subdirectories Web\Images\**
Find subdirectories having the name ending with 'x64' on any level in 'Web\Images' directory and include all files with '.ico' extension located in found directories and all subdirectories

Web\Images\**\*x64\**\*.ico


Files section can't be used to include files from the following folders:

  • bin
  • svc\bin
  • ServiceRepository\BinaryComponents
  • Messages

Setup Directives

Use this section to manually configure the Configuration Project installation/uninstallation properties and provide additional SQL and/or PowerShell scripts.

By default, all properties are disabled:

setup_directives.png

Such configuration allows minimizing the Configuration Package installation time, makes it seamless and unnoticeable for the active users, and essentially reduces or even brings down to zero the system's downtime. 

The system downtime is possible when the Configuration Package includes assemblies added in the Files section of the Configuration Project. In this case, the system can stop/restart the necessary services and turn on the maintenance mode during the package installation even if it is not explicitly configured in the Setup Directives.

All configured properties are exported to the Configuration Package.

Properties:

  • Install/Uninstall Package in Maintenance Mode: select the checkbox to explicitly enable the Configuration Package installation in system maintenance mode.
  • Recycle Web Application (M42Services): select the checkbox to restart the service that is necessary for running the website;
  • Restart Matrix42 Windows Services: select the checkbox to restart the following services:
    • HostCommon: part of the background engines infrastructure that handles the background processes that run on the application server; 
    • HostCommon x86: part of the background engines infrastructure that handles the background processes that run on the application server. This service specifically operates the processes that still need to run on the 32-bit subsystem;
    • Scheduler: a background engine that is responsible for activating scheduled tasks;
    • Data Gateway: a container for the logic that is executed remotely;
    • Worker: part of the Matrix42 Workers infrastructure.

Install:

  • Installation SQL Script: optional script that can be used for the database changes that cannot be added in the other way, e.g. with Schema Scripts. SQL script is applied after Schema Script installation. See Package Installation Sequence section for details.
  • Installation PowerShell Script: optional script that is applied after SQLScript installation. See Package Installation Sequence section for details.

Update Operations: Full Export & Changes Only

Update operations can be configured and exported in two modes. These options are applied for:

  • Schema changes (Configuration Items, Data Definitions)
  • Layouts (Previews, Dialogs, Control Descriptors, Landing Pages, Wizards, Dataset Views)

Export Changes Only

By default, all update operations for the enumerated above entities automatically track only the changes that can be listed as follows: 

CP_changes_only.png

The Export to Package action retrieves only the changes of the entity.

This approach allows working on several projects in the same environment and tracks only relevant Configuration Project changes for each Configuration Package. 

Full Export

The enabled Full Export option allows exporting the entire entity and all its properties as is, including all configuration options of the entity that are stored in the system at the given moment.

CP_full_export.png

Once the entity is saved in the Full Import mode the list of changes is no longer available and can not be restored automatically if the Full Import mode is disabled.

The full import option generates scripts that are run in the merge mode on the target system.

  • Was this article helpful?