Advanced Deployment executables

<< Click to Display Table of Contents >>

Navigation:  Automation Server > Automation Server configuration and administration guide > Initial project configuration > Deployment of processes and new versions > Advanced Deployment >

Advanced Deployment executables

Overview

This article explains the set of executable files or utilities that are needed to perform an Advanced Deployment by using the user interface dedicated to it.

The general outline of steps required is:

1.Use the CreateDatabase utility to create an empty database in the target environment.

2.Create a .bex file with the Export utility.

3.Import the previously exported .bex file into the target environment by using the CreateImport environment.

 

Optionally, if you need to update specific elements in your processes, use the Microdeployment utility. For more information, refer to Microdeployment.

 

Advanced Deployment executable files

The Advanced Deployment consists of an Export tool that helps you create a Deployment Package, and it also includes two executable files, each having its own configuration file, that are meant to be executed in the target environment. Furthermore, an additional tool to deploy specific components.

These executable files come in by default installed where the Management Console is installed (at C:\Program Files\Bizagi\Bizagi Studio\MC\).

 

ExecutableFiles2

 

The purpose of each executable file and where it should be used is described in the following table (the file is located having this same name with the .exe file extension).

 

Executable

Purpose

Where should it be used?

CreateDatabase.exe

Creates a blank database of Bizagi's model, just like a database is created initially when you create a project through Bizagi Studio or the Management Console options.

It is especially needed because the Advanced Deployment does not create that blank database, but parts from an existing one to apply project-specific  objects (entities, forms, rules, etc).

On a machine with access to the Production environment's database server.

CreateImport.exe

Applies the changes into your Production environment. This is done after analysis of the .bex export file against the Production environment, and considering how any existing information should be handled (i.e merge of records).

On a machine with access to the Production environment's database server.

Export.exe

Creates a .bex export file where you will have a package of objects from your Development environment of selected process versions.

On a machine with access to the Development environment's database.

It can be accessed directly in the seventh step of Studio's Process Wizard.

MicroDeployment.exe

Creates a .bex export file where you will have a package of updated objects from your Development environment. For more information, refer to Microdeployment.

 

Configuration files

Configuration files for the two mentioned executable files have the same name to their corresponding file, though they have .config as their extension.

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

CreateDatabase.exe.config for CreateDatabase.exe

CreateImport.exe config for CreateImport.exe

Export.exe config for Export.exe

MicroDeployment.exe config for MicroDeployment.exe

 

All configuration files have 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 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

 

CreateDatabase.exe

You will need it to create a blank database of Bizagi's model, only the very first time when you actually create the target environment's database.

Otherwise, for incremental deployments, you do not need to use it since you will be deploying changes and new process versions over an existing database.

 

Recall that for projects running in a .NET platform, you may consider using the One-click Deployment for the very first deployment.

If you do use the One-click Deployment for the initial deployment, then you may skip the CreateDatabase.exe use.

 

note_pin

Keep in mind regarding the new database you want to create:

If you are using SQL Server, then your instance should have an explicit predefined TCP/IP port.

For more information about SQL Server requirements and configuration, refer to SQL Server Configuration.

If you are using Oracle, you need to have previously created the BizagiAdmon user and consider that the password you set for your new Database, must be the same one used by the BizagiAdmon user.

For more information about Oracle requirements and preconfiguration, refer to Creating a project using Oracle.

 

To use CreateDatabase.exe, first make sure you have copied the whole MC folder in a local path of a machine that has network access to your Production environment database (the MC folder contains the executable files and the dlls needed).

Then:

1. Edit the CreateDatabase.exe.config file so that you specify the connection details of the database you want to create.

2. Execute CreateDatabase.exe.

You will see its user interface present the following:

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

 

CreateDatabase

 

note_pin

Bear in mind that the unicode settings of your development database will be copied to your production environment.

 

3. Create the database.

For this, use either of the 2 create options.

Create Bizagi Test database: Click this link to start with the creation of the blank Bizagi model database.

Through this option, this database will be automatically marked as a Test database.

Create Bizagi Production database: Click this link to start with the creation of the blank Bizagi model database.

Through this option, this database will be automatically marked as a Production database.

 

CreateDatabase_confirm

 

Once you confirm this action, the database creation will show its current progress:

 

CreateDatabase_progress

 

Once you are notified it has been finished, you may close the executable.

 

CreateDatabase_finished

 

Export.exe

Use this tool to generate the initial package of objects you want to deploy from your Development environment.

This step of the Advanced Deployment is done in the Development environment.

 

What you need to do

Before you start, make sure your processes are ready and that they don't need additional changes to be deployed.

To use Export.exe, edit the Export.exe.config file so that you specify the connection details of your Development environment database.

This is step is also located in the seventh step of the Process Wizard, clicking the Export Process option.

 

ExportWizard

 

You can also select the Advanced option located in the Deployment section of the Export/Import menu.

 

Export05

 

A window appears with the Advanced deployment wizard.

 

Export1_patchA

 

You will see its user interface present the following:

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

Processes Tab: Displays all processes and their versions. You should select those you want to include. When you right click a process version and select Define process dependencies a window appears where you can select the dependencies you want to force-include in your deployment. Keep in mind that only the selected processes are deployed, those which are not selected are not deployed even when they are related with other selected objects. Select the Entities, Query forms or Business Rules that you want to relate from the list. When a selected entity does not have attributes, it will not be included in the deployment.

 

Dependencies

 

Experience tab: Select the experience components you want to deploy. Keep in mind that experience elements are highly uncoupled and can be deployed without considering their necessary relation or component to work properly. For more information refer to Relate Objects.

 

advanced_components

 

Advanced tab: Select the objects you wish to include in the deployment. Among these objects you can select the themes you've made with the Theme Builder, Environment parameters, authentication options and user properties.

 

AdvancedOptions2

 

note_pin

When you choose to include environment parameters make sure that these parameter values, such as the SMTP server and interfaces URL, correspond to their environment configuration. When you deploy the package with these settings the target environment's parameters will be overwritten.

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.

 

Description tab: Add the information you consider relevant for this package such as the included processes, their versions, entities and other relevant changes.

 

ExportDescription

 

Click on the Export button.

This generates the package with your selected objects and process versions and save it as a local .bex file. A window appears informing that the export was successful and it shows a summary of your export file.

 

AfterExport

 

You can check the contents of the export package by clicking the View Package button.

 

ExportPackage

 

note_pin

When a parameter entity managed in production is considered in the deployment package, all of its attributes and relations are included, even unused ones.

 

CreateImport.exe

Use this executable to review and apply the package you created through Export.

In the revision carried out at this point you will consider if the package will be applied in your Production environment by evaluating for the last time the information to be applied.

At the end of the revision, you will be able to apply the file selected, which is the final package for your Production environment.

 

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

 

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.

 

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.

Backup Database: Create a snapshot of your target database.

Specify the file you want to import: Use the Browse button to load the .bex file created with Export.exe. The path to the file appears in this field.

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

 

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 Backup database 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

-

-

-

SQL 2008 R2

-

-

-

 

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.

 

MicroDeployment.exe

Use this tool to generate the package of specific objects you want to deploy from your Development environment.

This step is done in the Development environment.

 

What you need to do

To use MicroDeployment.exe, edit the MicroDeployment.exe.config file so that you specify the connection details of your Development environment database.

This is step is also located in the seventh step of the Process Wizard and click theMicrodeployment option.

 

ExporMD1

 

You can also select the Advanced option located in the Deployment section of the Export/Import menu.

 

MicroDep

 

A window appears with the Microdeployment wizard.

 

Microdeployment06

 

For more information, refer to Microdeployment.

 

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.