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

Overview

This article explains how do you can 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).
 

ConfigFiles

 

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" />

Consider:

[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.

 

note_pin

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" />

Consider:

[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.

 

PasswordEnc_01

 

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

 

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.

 

PasswordEnc_02

 

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

 

CrytpPass

 

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.

 

Import1

 

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.

 

AddPassword03

 

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

oReplace target environment metadata: In Bizagi administrators can configure different settings directly in the Work Portal or Management Console, for example, the theme, environment configurations like authentication, localization (translations), live processes, among others. If this check is active, the deployment considers all the configurations done in the development environment's Work Portal, Security options, and all the metadata is replaced in the target environment.

oIgnore removing referenced objects: in the deployment procedure, Bizagi validates if you have deleted objects in your development environment which are used or are enabled in the target environment. When you enable this checkbox, this validation does not take place and the deployment is performed regardless if there are deleted elements 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.

 

Import04

 

note_pin

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:

 

ExportPackage

 

ViewEditObjects

 

note_pin

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.

 

Import03

 

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:

 

ImportAnalysis

 

note_pin

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.

 

DBSnapshot

 

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

 

DBSnapshot2

 

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

 

DBSnapshot3

 

Database snapshot is available for the following SQL instances versions:

 

SQL Instance version

Enterprise

Standard

Web

Express

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.

 

note_pin

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.