Export and import structures into ELMA365

This article describes the types of structures that can be exported and imported into ELMA365, as well the process of export and import.

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 is it 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, System apps and others. 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.

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 ELMA365 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, 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.

What is included in export/import

When exporting, importing, checking or updating any package, the user performs the same steps. 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, belonging to the exported package.

• Widgets

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

• Groups

App/workspace/company groups and roles, belonging to the exported package.

• Menu

Pages belonging to the exported package. Note: by pages here we understand menu pages, not pages created with widgets. The menu pages are the ones that belong to the main menu or the workspace menu. It is also important to understand that every app and workspace have their own page. Therefore, on this step of the importing process, the entire structure of the workspace/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 not 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.

• 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 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. Please note that 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 customer 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.

Why does the system always perform all of these step 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 ELMA365 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.

Now, keeping in mind all the theory described above, lets take a look at several examples of ELMA365 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 companies

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 places 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 the Invoices workspace.

1. For that, we shall use the search() method
2. The search() method is available from the app description
3. There are two ways to get the description:
   1. Enable Global and write a syntax of the following format: Global.ns._clients.app._companies.search().
   2. To the context of a page/app/process add an App type variable with the Companies app. Then use the syntax of the following format: Context.fields._companies.app.search().

Option a 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. Option b on the other hand 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 the 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 payment request, it is required to specify no 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 the groups in the workspace that seems more convenient and logical, and then use them throughout the entire solution.

By the way, 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 your 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 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 is scripts. Therefore, we recommend you work as described in the first two cases in order to avoid any errors during export/import.

About updates

At the moment this article is written, updates work for workspaces and solutions.

During an update, the system compares the history of each updated service. The history is logged for apps, pages, processes, templates, widgets, and modules. 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, update isn't much different from import. Just keep in mind the following:

1. 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.
2. 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.

About deleting

Deleting something in always risky. Most of the things in ELMA365 are only marked as deleted without being actually erased. When exporting,  you can get rid of unnecessary variables, they will not be downloaded.

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

Conclusion

Export and import are basically part of the development cycle. In order to use this tool to the fullest, you should always keep in mind the importance of isolation.

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

Found a typo? Highlight the text, press ctrl + enter and notify us