Advanced Deployment

<< Click to Display Table of Contents >>

Navigation:  Bizagi Engine > Bizagi system administration > Deployment of processes and new versions >

Advanced Deployment


Bizagi presents an Advanced Deployment as an alternative to the One-click Deployment in Bizagi Studio, to perform Deployments of Processes in specific scenarios having sophisticated requirements.

For more information about the One-click Deployment which assists this process (automatically deploying process packages in an online manner), refer to Deploying your processes.



When to use the Advanced Deployment?

Deployments of Processes is done once the automation stage is completed and when you wish to publish your processes into a Test or Production environment.

The Advanced Deployment will offer further possibilities for the following specific scenarios:


1. Projects requiring an Offline Deployment.

Offline Deployment is needed when there is no network connectivity between the development environment (where the Studio is) and the final production environment (i.e, located in the cloud, a data center on a different network, etc).


2. Projects having automation of processes in a parallel schedule.

Applies for large scale projects in which a large number of users are working in a collaborative environment, and some processes are ready to go live, but others are still being automated.

In that case, you may choose to use the Advanced Deployment if you want to quickly publish those ready processes without holding the progress of the other processes (in other words, you can publish processes while others are being worked on).


3. Projects with more than the 3 default environments.

Some mission-critical processes or some corporate policies may demand the use of additional environments to those 3 default ones presented in the One-click Deployment in Bizagi.

The One-click Deployment will consider its main Development environment, alongside a Test and Production environment.

When using additional environments such as a Staging or Production replica environment, you will need to use the Advanced Deployment.


4. Projects in which you want to keep certain previous information

The Advanced Deployment offers a more flexible procedure than the traditional deployment, mainly because it enables revision and modification of each change in the Development environment which will be published into the Test or Production environment.

This comes in handy for advanced users which are certain of changes they don't want to publish.

In this way, all of the objects in Bizagi (Entities, rules, forms, etc) from one or more processes, can be explicitly selected or unselected (to disregard them) for the deployment to the target environment.

This includes the possibility of preserving cases in the Test environment as well.



How does the Advanced Deployment work?

Briefly, the Advanced Deployment will allow you to select the Processes and Sub-Processes (their versions) which will be published to Test or Production, through a set of 4 executable files.


You can optionally:

Include objects which are not necessarily attached to the selected Processes, in order to force-include them in the deployment.

Exclude objects which you do not want to deploy because your are certain you don't want/need them in your production environment.


This information is exported into a Deployment package file (in Bizagi, this file will be using the .bex extension).  


The .bex file is taken to the Production server, and this file becomes an input to analyze and preview the importing actions (those carried when publishing into an existing Test or Production environment), in order to ensure that the objects (and their data) will be taken as planned.

The analysis in this point, launches a comparison against the target environment involved in the Deployment applying.



Before you continue, make sure you acknowledge the following considerations.


1. Initial deployment through the One-click Deployment recommended

When running your Processes in a .NET platform, it is recommended to perform an initial deployment (the first deployment) through the One-click Deployment.

This will assist the creation of the target environment (Work portal, database and Scheduler service) and allow Bizagi to validate objects which should not be deleted or modified from that point on, in the Development environment.

If using the One-click Deployment for this purpose is not suitable, then you will need to create the initial database with Bizagi's blank model through the Advanced Deployment executable files.



2. Once through Advanced Deployment, there's no turning back.

It is Ok, if you choose to switch to the Advanced Deployment if you had already used the One-click Deployment (but not vice versa).

This means that once you choose to use the Advanced Deployment  to perform your Deployments, it will not be possible to go back and attempt to use the traditional One-click Deployment available in Bizagi Studio.


In other words, for any project which has already used the Advanced Deployment, any Deployments will need to be done using the same Advanced Deployment.


3. Always create backups.

The Advanced Deployment does not create backups of any database.

Remember that as a contingency measure, it is always recommended to take backups of all your existing environments before doing major changes to any environment.  Major changes include a Deployment by either the advanced or traditional One-click procedure.


This means that when using the Advanced Deployment, a backup snapshot of your target environment (Test or Production) should always be taken at least before applying any Import files.


4. Do not delete objects in development unless unused in production

It is really important that you acknowledge the following: when using the Advanced Deployment, Bizagi Studio won't be performing any validations for dependencies. This means being able to tell if an object has been already deployed to Production.

Due to this, it is strictly required that objects in the Development environment are not deleted (when being used in Production already), and that you always create new versions of Processes whenever you need to perform adjustments over Processes.


5. Plan and coordinate your deployment

Similarly to the One-click Deployment, it is recommended to schedule and perform the Advanced Deployment at non-working hours.

This also promotes any contingency measure towards restoring a backup (previous snapshot of the solution), should the Deployment results not be as expected.


6. Consider additional environments if needed

When Processes instances are critical, and depending on the nature of the changes incoming from Development (i.e it is strictly needed to test existing instances), you may choose to use an alternative environment (Staging or Production Replica), used to perform rigorous testing and user acceptance tests, especially focused on the existing Production cases (live Process instances).

This means that beforehand, you should create a temporary environment for the sole purpose of testing the final Deployment into Production.

By doing this, and through a backup and restore approach, you would have a way to review if any changes or additional information are required for the Deployment.

When using such environment, make sure that the SMTP Server, any configured interfaces, ECMs or data providers, the set e-mails for your users or any other setting, does not trigger your actual Production settings.



Required profile

The profile of the user working with the Advanced Deployment needs to:

1. Have a basic understanding of XML structure (in order to configure the config files).

2. Have access to the project environments' Databases (with the superuser credentials).

3. Have expertise or important know-how, about the concepts involved in a Deployment of a project in Bizagi.

For more information about the treatment for deploying objects in Bizagi, refer to deployed objects.

4. Have an understanding of the implemented Processes in the project.

This means knowing about these processes' purposes, data model, versions, integrations, security settings, environment settings management (i.e policy, alarms, parameter entity values), and general workings.


Take into account that for proper testing (carrying our user acceptance tests), this will include being able to tell which is the expected behavior of the Processes in the Work Portal (under the different business scenarios).



Advanced Deployment executable files

The Advanced Deployment provides 3 different executable files, each having its own configuration file.

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




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




Where should it be used?


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.


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.

You may use it directly where you have Bizagi Studio installed.


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 above 3 executable files are named after those executable files but have the .config file extension.

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

CreateDatabase.exe.config for CreateDatabase.exe

Export.exe.config for Export.exe

CreateImport.exe config for CreateImport.exe


All configuration files have the following structure and required configuration in which 3 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 password for the above login. It is strongly recommended to encrypt the password using Password Encryption feature.

[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 password for that user schema. It is strongly recommended to encrypt the password using Password Encryption feature.




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.



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 all 3 executable files and the dlls needed).


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.





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.




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




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





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

This should be the only executable file which is configured to reference the Development environment database (the others will reference the Production environment database).


To use Export.exe:

1. Edit the Export.exe.config file so that you specify the connection details of your Development environment project.

2. Execute Export.exe.




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:




Set Advanced Import-export: It is recommended to click this button to mark that your project uses the Advanced deployment.

This will aid Bizagi to validate and guide you the features you should use or considerations for eventual Bizagi version upgrades.




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






Include environment parameter values

You may 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 user jobs

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

Include organization

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

Include authentication options.

You may include the authentication options you have previously customized in Bizagi Studio for this project. Nonetheless, these options can be managed through the Management Console in your production environment.

Include records of parameter entities managed in production

You may initially and from Bizagi Studio options, make sure you tick each parameter entity whose records you will need to be deployed from the Development environment.

If you do have entities that need their values updated from the Development environment, make sure this item is ticked.


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.




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.




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.



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


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

2. Execute CreateImport.exe.




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/edit process objects to import and View/edit entity objects to import options, exclude any information you don't want to deploy to your final environment.


Through both options you can view exactly which objects will be included in the Deployment:




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




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:




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.