Export and import structures into BRIX

This article covers the features of exporting and importing structures in BRIX.

Isolation

Isolation is one of the key concepts for moving structures between companies. Isolation ensures that the structure is transferred completely, correctly, and with all the links intact. For instance, when we export a workspace, we get an independent and functional workspace that can be imported into other companies right away.

Whenever there is a threat to isolation, export errors appear. Below we shall see how export is done exactly on the levels where it is required, without leaving anything out or taking more than necessary. Errors show that we are trying to export something that may break the isolation.

At the same time, isolation is not broken by built-in workspaces, such as CRM and System Apps. You can refer to these workspaces without expecting any export errors because the system knows that these workspaces also exist in the target company where you will later import the workspace.

Note that exporting built-in workspaces and using global constants in scripts have their own features and limitations.

Before we move on to the objectives of import and export, let's take a look at what exactly can be exported, imported, and updated.

Types of packages

In BRIX there are several types of exported and imported packages. Each package corresponds to a level of isolation:

1. App (namespace.app). Atomic type of package. It contains only one app and everything related to this app.
2. Workspace (namespace). A set of apps and processes. A workspace is usually a logical unit aimed at solving a specific set of tasks.
3. Module (namespace). A set of widgets, custom activities and API methods. In modules, you create reusable entities that can be used in different apps, interfaces, and processes. Another key usage scenario for modules is creating integrations and connecting external systems or services.
4. Solution (solution). A package type for exporting one or several workspaces and modules at the same time.
5. Configuration (global). All the workspaces, modules, organizational chart, and other objects that belong to the company.

Exported and imported structures

When exporting, importing, and updating any package, all structures are consistently checked. Still, export (and, consequently, import) is always performed at a certain level of isolation. For example, if you are exporting a solution, the document templates belonging to the apps and workplaces of this solution are exported.

Let's take a look at each step and see what it does.

• Templates. Document templates used in processes to create files, as well as templates of lists of informed users and approval sheets belonging to the exported package.

• Widgets. Widgets and pages created in the app, workspace, and company interfaces, as well as forms belonging to the exported package.

• Groups. App, workspace, and company groups and roles belonging to the exported package.
• Menu. Pages belonging to the exported package. 

Important: In this case, menu pages are meant by “pages“, not widgets of the Page type. Menu pages are the ones that the main menu or the workspace menu consists of. It is also important to understand that every app and workspace has its own page. Therefore, in this step of the importing process, the entire structure of the workspace or solution is imported. If you interrupt the import after this step (or it is interrupted due to an error), the workspaces will look as if they have been imported completely, but the pages will not load, because the apps and widgets would not have been imported.

• Processes. Business processes and custom activities from modules belonging to the exported package.
• Organizational chart. Is only exported and imported with the configuration.
• Counters. Counters of workspaces and apps belonging to the exported package. App and workspace counters can only be imported, they cannot be updated if they are already configured in the company.
• Apps. Description of apps, that is, of fields, including their settings (for example, display conditions), settings of app buttons including links to business processes, Kanban board, tiles and table settings, and other settings belonging to the exported package.
• Access permissions. Access permissions for each app in the package.
• Settings (additional import settings). List of additional parameters and settings of the module belonging to the package. When this article was written, the parameter values were not available for export.
• Extensions (Modules). Description of modules and their content.

Important: Each module component (widgets, custom activities, processes) is exported and imported by a specific service, and at a certain step. For example, when importing a module, only after the Processes step will custom activities and processes be uploaded.

• Solutions. System information about the exchange service version (it is required for compatibility with older solutions) and the list of solutions within the package. The main function is compatibility and version history.
• Events (import system bus). Event handlers created in modules belonging to the package.
• Portable services. Settings of connection to the module’s portable services. Only the settings part is exported. Images of portable services are not included in the import.
• Localization. Files with translations uploaded to the exported workspace belonging to the exported package.
• OAuth2/OIDC tokens. Templates and access levels to system items. Granted permissions are not transferred, as they are part of the platform security system.
• Portal. Pages of the external portal, as well as its branding settings. The portal is bound to a workspace and exported together with it as part of a package.
• Reports. Report forms created based on apps and business processes (report sources), including their settings, such as links between sources or report columns.
• Contracts. Contract description: list of fields, source settings, etc.

When exporting a workspace or solution with a contract whose source is an app outside the export configuration, the user will receive a warning about uploading without a source app.

Import of such a workspace or solution in case of absence of source apps will run without errors, but there will be no links between the contract and the sources.

• CRM. Settings of nurturing stages, activity log, and CRM tasks. They are exported only when exporting the CRM workspace or the whole configuration.
• Document flow. Settings of document categorization (offices, folders, and document flows) that are actually used in workspace, solution, or configuration apps.

Configuration of export or import also includes the settings of approval sheets and lists of informed users.

• Projects. Description of project types created in the Administration > Project Types workspace. It is downloaded when exporting the configuration, the Projects workspace, and solutions that contain the Projects workspace.

Important: Project templates (app items) included automatically when creating a project type are not transferred when exporting/importing structures.

• Web forms. App web forms belonging to the uploaded package.

Why are these components always checked even if the workspace doesn't, for instance, have an organizational chart? Because the export/import uses one single mechanism, and each service decides whether to be included in the package or not.

As a result, on export, BRIX always provides a file that contains the description of settings that the user decided to export. During the import of this package, the exact same settings will be imported.

States of the imported solution

An imported solution may have several statuses:

1. Locked

By default, a solution is locked after being imported. Locking means that certain parts of the solution (processes, widgets, apps, etc.) are not available in the interface.

Locking is necessary to prevent the updated parts of the solution from being changed, which would then lead to errors during updates.

However, some settings, such as permissions, can be edited even in a locked solution and are still updatable. For such settings, a separate step is provided where the user can select which access rights to update.

2. Paid

A solution can be licensed. In this case, it has to be activated. If the solution is not activated, users will not be able to access its workspaces and modules will be disabled.

Files of paid solutions are encrypted and cannot be unpacked, including via the elma365pm utility.

Depending on the solution status (locked/unlocked, paid/free), access to exporting and updating workspaces and managing modules differs. The access options are summarized below.

Modules

Workspaces

Solution dependencies

A solution can have dependencies on another solution. They are used so that solutions can be exported and imported separately from each other but still be able to refer to the structures of another solution.

Dependencies are added during the export process in the checking step. For all links to another solution, you can add a dependency using the corresponding button.

When importing a solution that has dependencies, a check will be performed to determine if the company has solutions on which the imported solution depends. If the required solutions are missing, the import will not be possible.

Cases

Now, let’s take a look at several examples of BRIX settings, and how they can be exported. For different export/import objectives, different types of packages are used.

Case 1. Invoice

Let's say your customer needs to automate invoice management to approve and pay incoming invoices. There are different purposes of payment, which the user does not enter manually, but chooses from a list. The invoices might be in either of the three currencies: rubles, US dollars, and euros. The invoices are issued to different legal entities within the customer's organization, and are paid accordingly.

The minimal set of apps for this case would be:

1. Invoices
2. Contractors
3. Purpose of payment
4. My legal entities

Two of these apps are pre-built into the system: the CRM built-in workspace has the Companies app for contractors, and the System Apps workspace has the My legal entities app for the customer’s legal entities. It is recommended to use these apps in the first place because they can be referenced without damaging the isolation.

Invoices and Purpose of payment can be placed in one workspace. Therefore, for this case, it is best to work with a workspace that will then be exported, imported, and, in the future, updated.

Always keep in mind that there will be future improvements. For example, new service apps might appear, or your scripts will reference apps from a different workspace. Let's take a look at this scenario.

Suppose, we need to search for contractors or legal entities from the Invoices workspace.

1. For that, we should use the search() method.
2. The search() method is available from the app description.
3. There are two ways to get the description:

• Enable Global and write a syntax of the following format: Global.ns._clients.app._companies.search().
• Add an App type variable with the Companies app to the context of a page/app/process. Then use the syntax of the following format: Context.fields._companies.app.search().

The first option will break the isolation even though we are referencing a built-in app because we have enabled Global in scripts, so export will not be available. On the other hand, the second option does not prevent the workspace from being exported because Global is not enabled.

Still, it is important to remember that if we add an app that is not a built-in app and does not belong to our workspace, to the context, the isolation will be violated. To correct it, you would need to include the referenced app into the export package by combining the two workspaces into a solution.

Case 2. Specific invoices

The overall situation is the same, we need to automate invoice management. Although, now we also have to implement a payment register in order to pay invoices in bulk. Also, when making a payment request, it is required to specify not only the contractor and the company but also the type of the payment, VAT, currency, department, period, etc. Since the customer works with contractors from different countries, the VAT and currency values can differ.

Even without architectural details, it is clear that this case requires a lot of apps that can be logically divided into two workspaces: Payments and Custom Objects.

In order to export the solution and deploy it in the customer's company, we shall combine the two workspaces in one package.

In this case, the combined solution will be very flexible, which is especially convenient for any future integrations with an accounting system, which can be added to the solution as a separate module.

Still, there are some details worth mentioning. We shall configure access permissions by user groups without referencing the org chart in order to preserve the isolation. We can provide or deny access to these user groups for each app in a workspace.

The question is: where shall we create these groups? The answer is simple. It doesn't really matter as long as they are created within the solution (do not forget about the isolation).

There is no need to duplicate the groups. Since both workspaces belong to the same solution, there will be no conflicts during export. Therefore, create groups in the workspace that seems more convenient and logical, and then use them throughout the entire solution.

Groups can be used not only for access settings and in swimlanes. They can also be used in notifications in business processes, so keep that in mind, and use the groups on the required isolation level.

Case 3. Large project

A client usually needs you to automate several activities. An entire team can be working on such a project, creating a rather complex configuration.

Yes, you can export and import the whole configuration. Although, is it really necessary? Let's find out.

The configuration that you are creating for the customer within this project is usually divided into logical sets of requirements. Each set can be implemented by a workspace or a solution.

Depending on how you are managing the project, you can deliver the results to the customer either set by set, or on the whole. Each workspace or solution might be developed by a team or by one person. Even the entire configuration can be done by just one person.

Why not simply do a configuration export if there are so many details?

You can do it, but we still recommend having isolated workspaces, solutions, and modules. After you have completed the project, there might be some additional development. It is always easier to deliver modifications to the customer as soon as they are ready regardless of other features that might be still in work. For example, you can improve a certain workspace, export it, and import it to the customer's company.

According to our experience, isolation is most often violated by using the organizational chart, global groups, and the Global flag in scripts. Therefore, we recommend you work as described in the first two cases in order to avoid any errors during export/import.

Export/import is more of a tool to automate the solution development and distribution cycle. To use this tool to its maximum potential, it is always important to keep isolation in mind.

Update

Updates are supported for workspaces, solutions, and modules. In this case, modules and solutions are always only updated, i.e., you cannot install two instances of the same module or solution.

During an update, the system compares the history of each updated service. The history is logged for apps, pages, processes, templates, widgets, modules, and access rights settings. For each entity, an entry is created containing the ID and the modification date.

An update can go either of the two ways:

1. The history in the package with the update is more recent than the history in the package being updated. This means that no changes have been made in the target company. In this case, the update will be installed without any conflicts.
2. The history in the two packages is not the same. This means that changes have been made in both the target company and company where you created the update. This leads to conflicts. The system will show a list of conflicted entities and will ask you to either cancel the update or replace the updated package. The changes are not merged, the configuration is completely replaced with the update.

Basically, the update isn't much different from the import, but keep in mind the following:

• During an update you add something new and change whatever is in a conflict. Nothing is deleted. For example, if you have deleted a field from an app, but in the customer's company this field remains intact, it will not be deleted during the update.
• We recommend to not introduce changes directly in the customer's company (production). It is best to distinguish the company where you develop and test new features from the one the customer will actually use. This will make it easier to deploy changes and support the system in the long run.

Soft update of solutions

For solutions, there is an option to soft update, i.e., update only those components for which no conflicts or links to conflicting components are detected.

Together with the conflicting items, the system recursively calculates the dependencies of these components on other components. This is necessary to avoid a situation where, during a soft update, a component with a conflict is not updated, but other components referencing it are updated. Such a situation can lead to a non-consistent configuration.

If the solution is partially locked, the links to components in this workspace are ignored and the components in the locked workspace are updated during a soft update.

Deleting

Deleting something is always risky. Most of the things in BRIX are only marked as deleted without being actually erased. When exporting or importing, you can get rid of unnecessary variables. If they are hard deleted, they will not be exported.

The deleted workspaces, apps, and pages will will be exported with the rest of the components.

Was this helpful?

Thanks for your feedback!

Please specify why:

Recommendations did not help meArticle is hard to understandDidn`t answer my questionContent does not match the topicOther

How we can improve it?

YesNo

Please specify whyRecommendations did not help meArticle is hard to understandDidn`t answer my questionContent does not match the topicOther