User interface explained

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

User interface explained

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.

4.If you want to deploy data into your environment, use the Export and Import data utilities from the Management Console. This is known as Data Synchronization.

 

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.

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?

Export

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 is accessed directly in the seventh step of Studio's Process Wizard.

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.

 

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

 

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 procedure

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

This is the only step of the Advanced Deployment that is done in the Development environment (the others will reference the Production environment database).

 

To use it:

1. Make sure your processes are ready and that they don't need additional changes to be deployed.

2. Navigate to the seventh step of the Process Wizard and click the Export Process option.

 

ExportWizard

 

Export1_patchA

 

You will see its user interface present the following:

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

Main panel: Lists all processes and their versions. You should tick those you want to include.

Notice you may right click a process version to use the Define process dependencies to force-include in that deployment. Please bear in mind that processes that are not explicitly selected will not be deployed, even when they are related anywhere else.

To relate objects, you may select specific objects (Entities, Query forms or Business Rules) from Bizagi. If the entity marked does not have attributes, it will not be included in the deployment.

Do this by ticking the object from the hierarchical list in each tab:

 

Dependencies

 

Advanced: Additional possibilities to include or exclude those objects managed by Bizagi.

 

AdvancedOptions2

 

OPTION

WHEN TO USE IT?

Include environment parameter values

You can include managed values for your given environments. It is recommended to make sure that these parameter values (such as the SMTP server, interfaces URL, etc) correspond each to their environment configuration.

Include all user jobs

If your project uses custom jobs, make sure you tick this to make sure these are included.

Include user properties

You can include or exclude the entities associated with the user properties.

Include organization

Check any organization configuration you want to include in the deployment.

Include sub-processes

If ticked, the export dependencies analysis considers the sub-processes that are part of the processes included in the deployment.

 

3. Select the experience components by clicking the Experience tab. Bear in mind all previous considerations regarding experience components. They are highly uncoupled and could be deployed without considering their necessary relation or component to work properly. For more information please refer to the Relate Objects article.

 

advanced_componentsset

 

4. Click on the Export button.

This will generate the package with your selected objects and process versions and save it as a local .bex file.

At this point you are done using the Export, but you may rely on the Tasks after export options to review your generated package, and evaluate if you need to generate a new one.

 

AfterExport

 

After export tasks will allow you to view information contained in the package, classified by entities and by viewing which ones have their information exported completely or partially.

 

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 (the MC folder contains all 3 executable files and the dll files needed).

Then:

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

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

 

You will see its user interface present the following:

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

Load file: Use this option to commence using the CreateImport. You will need to load the .bex file created with Export.exe

Export file details: You may use View process objects to import, or the View entities to import option to review the information that is included in the package (as from the Export options to review what was exported).

 

View process objects to import shows all system and internal entities that contain information of the processes, and that will be published into the Production environment.

View entities to import shows all parameter entities which will have records published or updated into the Production environment.

 

3. Review what you will deploy.

Using the View process objects to import and View entity objects to import options, you can view exactly which objects will be included in the Deployment:

 

ViewEditObjects

 

4. Click on Apply into target database.

Through this option you will actually deploy the package. This option will run scripts at the target database (i.e, your Production environment), 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 will generate 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.

 

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.