This article describes the types of structures that can be exported and imported into ELMA365, as well the process of export and import.
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:
- App (
namespace.app). Atomic type of package. It contains only one app and everything related to this app.
- Workspace (
namespace). A set of apps and processes. A workspace is usually a logical unit aimed at solving a specific set of tasks.
- 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.
- Solution (
solution). A package type for exporting one or several workspaces and modules at the same time.
- 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.
Document templates used in processes to create files, belonging to the exported package.
Widgets and pages created in the app/workspace/company interfaces, as well as forms, belonging to the exported package.
App/workspace/company groups and roles, belonging to the exported package.
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.
Business processes and custom activities from modules, belonging to the exported package.
- Organizational chart
Is only exported and imported with the configuration.
Counters of workspaces and apps, belonging to the exported package.
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.
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:
- Purpose of payment
- 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.
- For that, we shall use the
search()method is available from the app description
- There are two ways to get the description:
Globaland write a syntax of the following format:
- 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:
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.
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:
- 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.
- 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:
- 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.
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.
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.
Found a typo? Highlight the text, press ctrl + enter and notify us