Apply the package using executable

<< Click to Display Table of Contents >>

Navigation:  Automation Server > Deployment  > Advanced Deployment > How to apply a deployment package >

Apply the package using executable


This article explains how to apply a deployment package using the Bizagi Engine executable file.


Advanced Deployment executable file

The Advanced Deployment consists of an Export tool that helps you import a Deployment Package. This executable file comes in by default installed where the Management Console is installed (at C:\Program Files\Bizagi\Bizagi Studio\MC\).


Configuration file

Configuration file for the executable file has the same name to its corresponding file, though it has .config as its extension.

Such configuration file are XML-formatted, and would be accordingly:

CreateImport.exe config for CreateImport.exe


The configuration file has the following structure and required configuration in which three main keys are found inside of the <appSettings> element:

ProofConcept_Utility: Contains the name of the executable file without its extension.

DSNDB: Contains the connection string to the database that the executable connects to. For the CreateDatabase.exe, this connection represents the database that will be created.

PROVIDERTYPE: Contains the specific data provider to be used for the above connection (SQL Server or Oracle).



To configure the executable, you need to make sure that you specify the connection and provider as described below.


When using SQL Server:

<add key="DSNDB" value="Persist Security Info=True;User ID=[SQL_Login];Password=[Login_password];Data Source=[DB_Server]\[Named_instance];Initial Catalog=[Database];" />

<add key="PROVIDERTYPE" value="MSSqlClient" />


[SQL_Login]: The login account used to connect to that SQL Server database instance.

[Login_password]: The encrypted password for the above login.

[DB_Server]: Name or IP address of the database server. Use \[Named_instance] when applies, if your database instance is not the unnamed default one.

[Database]: The name of the project environment's database. Recall that specifically for the CreateDatabase, this database you specify is the one that will be created.



When configuring the executable, the SQL Server login used will require sysadmin rights.


When using Oracle:

<add key="DSNDB" value="Data Source=[DB_Server]:[Port_number]/[Service];User ID=[User_schema];Password=[User_schema_password];Unicode=True;" />

<add key="PROVIDERTYPE" value="Oracle" />


[DB_Server]: Name or IP address of the database server.

[Port_number]: The TCP port used for the connection to the database service.

[Service]: The service identification for an Oracle instance.

[User_schema]: The name of the project environment's database. Recall that specifically for the CreateDatabase, this database you specify is the one that will be created.

[User_schema_password]: The encrypted password for that user schema.


As mentioned above, the password of the database must be encrypted to protect it in case of unauthorized access to the configuration files. Follow this procedure to encrypt the password:


1. In the Work Portal of your development environment, click on Admin and then in the Security menu select Password Encryption.




This will display a window in which, you can cipher any text.


2. Type the string to cipher in the Encryption Text field and confirm in the field below. This will make sure that the text entered for the first time is correct. If both fields do not match, the password will not be ciphered.

Finally, click Encrypt.




3. The Ciphetext field will display the password encrypted. Copy this string and paste it in the related property according to your Database engine.




Timeout configuration

In deployment, updating the properties of tables such as indexes, new attributes, or even data, can take several minutes, depending on whether the deployment package contains transactional objects to update or not and the size of the table that needs to be updated in the target environment. For example when you add new business keys.


Bizagi has a configuration key, to set a deployment timeout. In the CreateImport.exe config file, you can add the following key in the appsettings tag.


<add key="TimeoutForDeploymentInMinutes" value="25" />


With this key, you can set the time in minutes for the deployment timeout. The key can also be set in the following executable files associated with the advanced deployment:

· CreateImport.exe

· ImportProcessTemplate.exe

· MicroDeployment.exe


Open the CreateImport executable

To use CreateImport.exe, first make sure you have already copied the whole MC folder in a local path of a machine that has network access to your Production environment database. Know that the MC folder contains all three executable files and the .dll files needed.

Edit the CreateImport.exe.config file so that you specify the connection details of your Production environment database.

Execute CreateImport.exe.




A window appears with the import wizard, which presents the following:

Target Database: shows the database and its database server, to which the executable was configured.

Database snapshot: creates a backup of your target database.

Specify the file you want to import: use the Browse button to load the .bex file created with Export.exe. If the .bex file was generated with a password, a window will appear requesting it. The path to the file appears in this field.




oEnable metadata validation: performs validations in the metadata to reduce deployment errors.

oReplace target environment metadata: Inside Bizagi, administrators can configure different settings from the Work Portal or Management Console, such as the theme, environment configurations like authentication, localization (translations), live processes, among others. When this check is enabled, the deployment collects all configurations done in the Development environment's Work Portal, and Security options, and the metadata's override is replaced in the Target environment. The checkbox is responsible for identifying overrides in the Target environment and replacing the metadata, giving priority, and aligning primarily with the deployment settings.


When configurations are made from the Work Portal or the Management Console after deployment, an override will be generated in the modified objects. If this checkbox is not enabled, object changes made in the development environment will still be reflected in the Target environment when the deployment is performed except in the override. However, when the checkbox is enabled, the override will be replaced by the object changes made in the Development environment.



Its highly recommended to disable this check box to avoid losing data in the overriding of objects.


In the Objects in Override table, you can see which objects are editable in the Production environment, and can be in Override in the Production environment. If the Replace target environment metadata check is enabled, it will overwrite what is in the Production environment. If the object has a value other than N/A in the Advanced Option column, it means that it is included in the advanced options of the deployment. When the value is N/A, the objects of that type cannot be selected or specified and, in a deployment, they can end up being included due to dependencies.


oIgnore removing referenced objects: When objects are deleted in the Development environment, dependencies from the deleted entity will be carried out in the deployment package. In the deployment procedure, Bizagi evaluates which objects have been removed from the package and if one of them is still under use in the target environment, it will ignore those objects from the import.


For example, you can have two processes (1 and 2 respectively) in Studio sharing the same entity. When both processes are deployed, they will be visible in the Development environment. If the entity is deleted in the Development environment and deployment is performed for Process 1, the dependencies from the deleted entity will be carried out in the deployment package while in the target environment Process 2 will still use the shared entity.



Its highly recommended to activate this check box to avoid conflicts with the objects used in the target environment.


Package information: this section shows the author (user), project, source database and the export date of the package to import.

You may use View process objects to import, or the View export advanced options option to review the information that is included in the package as from the Export options to review what was exported.

oView process objects to import: view all objects that contain process information that will be published into the Production environment.

oView export advanced options: view all the advanced options that will be published and updated into the Production environment.

oView description: view the .bex file export summary, written by the user who generated the file.





We strongly recommend that you select the Enable metadata validation option. This validation detects two of the most common errors that occur during a deployment:

References to objects that don't exist in the catalog: When a deployed object has a reference to an object that doesn't exist in the package or in the target database this validation is triggered.

Processes without an associated version: When objects like rules or experience elements don't have an associated process version, this validation error is triggered. If this happens, you must review your deployment configuration and make sure you selected an associated version for these objects.

These validations are important because they reduce errors in the Production environment substantially.


Review what will be deployed using the View process objects to import, View export advanced options and View description options. You can check the objects that will be included in the deployment:







If you check the Authentication options, the authentication configured in the target environment will be overridden. Do not use this option unless you are sure to change the authentication options with the configuration of your source environment.


Click on Apply package. This option deploys the package by running scripts in the target database, and therefore it is important you take proper measures at this point.




This procedure may take a few minutes and it is important that you are aware that it will run scripts at the database.

Once it is done, it will notify the success:





This process generates a log in the folder where you ran the CreateImport.exe. This log will let you easily identify the cause of an error or if the process was executed successfully. Its name will be logImport[TimeStamp].txt where the timestamp will follow this format YYYYMMDD hh_mm_ss.


If the import is successful the log will look like this:

3/01/2019 3:06:43 PM: Workspace is valid!
3/01/2019 3:07:11 PM: Adapter execution
3/01/2019 3:08:35 PM: Import catalog end

If instead the process had an execution error your log will look like this

2/21/2019 11:05:04 AM: Exception on Import: Package version is not supported by this version of bizagi: 11.1.0
2/21/2019 11:05:08 AM: [{"type":"IncompatibleVersion","Message":"Package version is not supported by this version of bizagi: 11.1.0"}]


The first line of the log will show you what kind of error Bizagi found in trying to import your process. On the second line you can find more information regarding the error. Keep in mind that the log will vary depending on the error.


Database Snapshot

In the Advanced Deployment, you import the BEX file using the createImport.exe executable. Bizagi offers an option to generate a snapshot of the target database, which you can revert easily if there is an external issue affecting the database in the deployment procedure and you want to return to its initial state previous the deployment. Reverting a database is faster than restoring a backup, which makes the deployment efficient.


When you open the createImport.exe, you can click the Database snapshot link. This automatically generates a snapshot in the database.




The snapshot name is the name of the source database with a time stamp as follows: [Database_name]_yyyyMMMdd_HHmmss.




The snapshot is always stored in the same source database's instance, and is a read-only file:




Database snapshot is available for the following SQL instances versions:


SQL Instance version





SQL 2017

SQL 2016 SP1

SQL 2016




SQL 2014




SQL 2012





Snapshot Considerations

Please bear in mind the following recommendations:

If a snapshot exists you cannot delete or restore your database. You must delete the snapshot first.

Do not leave snapshots permanently. They must be used to revert rapidly the database to an original state if needed. After used it is recommended to clean all your snapshots.

A snapshot do not replace backups. Please keep all your backup schema.



We recommend looking at snapshot considerations in the following link.


What is next?

Once you have completed your process deployment through the Advanced Deployment, we recommend you clean up the server's cache before announcing that the deployment procedure is completed.


When running your processes in an IIS, after performing an advanced deployment you should clear the cache of your Work portal and database.

In order to do this, invoke the following Bizagi web services as available in every project:

Render cache as stored in the database: http://[your_server][your_project]/webservices/cache.asmx?op=CleanRenderCache

Application cache: http://[your_server][your_project]/webservices/cache.asmx?op=CleanUpCache


Note that you should restart your IIS services.


The deployment procedure only considers metadata, meaning that if you want to preserve the User's data and values of parameter entities  managed in production from your development environment in the target environment, you must do a Data Synchronization.