Using an external session state repository

<< Click to Display Table of Contents >>

Navigation:  Bizagi Engine > Bizagi system administration > Bizagi server configuration > Bizagi Engine .NET platform configuration > Clusters and server management  >

Using an external session state repository



When using a cluster configuration in Bizagi, by default, each of the multiple nodes of that Bizagi cluster will store the information regarding the user's session.

However and in order to achieve greater scalability and enhanced reliability, you may choose to delegate the storage of such session state information externally into a central repository .

You may do so by having Bizagi rely on a session state database or a session state server, as supported by Microsoft's .NET framework.

Generally, using a session state server should be faster, while using a session state database supports best higher concurrency.


Note that in addition to providing high availability, the use of a cluster is fundamental for your system to be able to scale easily.

For more information about using a clustered configuration in Bizagi, refer to Clusters and servers management.



Why can this alternative help?

This alternative is useful for scalability purposes, specially to optimize the processing in nodes when having implemented processes which are expected to produce a large amount of cases or activities, performed by the same subset of end users over a short period of time.

By having sessions delegated to a central repository, processing of requests is distributed as efficiently as supported by the algorithm in your load balancer, and it is done across the multiple nodes of the Bizagi cluster while avoiding the use of session affinity configuration (i.e, when having sessions bound to a specific node to process all requests from that same user's session, i.e sticky sessions).

In addition to being more scalable, for the same reason of avoiding a local management of sessions, this alternative is also more reliable for the IIS, mainly because sessions stored externally (e.g, in a SQL Server database) will survive ASP.NET restarting and recycling, or even SQL Server restarts.




The use of an external session state storage relies on the technology as supported by Microsoft's .NET framework.

This means that it applies for project using IIS and a Microsoft SQL Server database (when choosing a session state database).

Note that to use a session state database, it is recommended to use a Standard or Enterprise edition for you SQL Server).

For more information, refer to



What you need to do

In this section we will illustrate how to perform setup by using a session state database, in which case, these steps are carried out:


1. Create the session state database in your SQL Server instance.

This is done through the use of a utility provided by the .NET framework itself.


2. Configure your Bizagi Work portal to use the session state database.

This may be done through the IIS Manager graphical options, or by directly editing the web.config file of Bizagi Work portal.



If you wish to use a session state server instead, you don't need to create the database (skip step #1), and you would need to configure your Bizagi Work portal to use a server instead of a database in step #2.



Follow these steps.


1.  Create the session state database in your SQL Server instance.

1.1. Open a command prompt with admin rights and browse to the path of your installed .NET framework.

It is recommended to use the utility as provided by the .NET framework in its version 4.0 full (since it is the version to be used by Bizagi Work portal).

To ensure this, you may use the utility directly from your Bizagi server (having by default, the version 4.0 full for a 64-bit architecture installed at: C:\Windows\Microsoft.NET\Framework64\v4.0.30319\).


1.2. Execute the utility (called aspnet_regsql.exe), by using those parameters which will create the tables and schema to store sessions, and by defining a custom database.

Do this by using the following:

aspnet_regsql.exe -S [SQL_INSTANCE] -E -ssadd -sstype c -d [DATABASE_NAME]





[SQL_INSTANCE]: Is the name of your SQL Server instance. Recall using backslash for named instances.

[DATABASE_NAME]: Is the name you will give to your custom database.


Notice that -E uses the current credentials from the user running the command prompt which should be valid if these are allowed at that instance with sysadmin rights (given that mixed mode in SQL Server supports Windows authentication). In case you do not wish to use the current user's credential, use the -U and -P parameters (to specify a username and password respectively).

Further options of the aspnet_regsql parameters, refer to:



Recall that the session state database alternative is recommended for Standard or Enterprise editions of SQL Server.

You may previously verify the edition of your SQL Server by executing select @@version:




Once the command is executed, you may verify directly at your SQL Server instance that the custom database has been created while having the ASPStateTempApplications and ASPStateTempSessions tables:





Note that it is recommended to rely on a custom database in order to have persistent session state information which is not affected for instance by a database restart (as opposed to relying on tempdb), and in order to set up such feature as independently as possible (as opposed to using the ASPState database which is set per instance).


2. Configure your Bizagi Work portal to use the session state database.

Note that this configuration may be done by directly editing the web.config file of Bizagi Work portal, or through the IIS Manager options (which present a UI for such change, though it results in the same changes at the web.config file).

The sample shown below illustrates the use of a session state database.


To do this through direct modification of the web.config file consider that this file is located by default at C:\Bizagi\Projects\WidgetContest\WebApplication\, and you would need to edit the attributes of the <sessionState> element, so that these are left having these values:

mode: SQLServer

allowCustomSqlDatabase: true

timeout: 20 (default value)

cookieless: false

sqlConnectionString: Data Source=[SQL_INSTANCE];Initial Catalog=[DATABASE_NAME];User ID=[LOGIN];Password=[PASSWORD];


For the sqlConnectionString connection values, consider:

[SQL_INSTANCE]: The identifier for the database server (or IP address), including its instance.

[DATABASE_NAME]: The name of the custom database, just as created through the aspnet_regsql.exe utility in the previous step.

[LOGIN]: The account login for the connection's access.

[PASSWORD]: The password for that login.


For example:

<sessionState allowCustomSqlDatabase="true" cookieless="UseCookies" mode="SQLServer" sqlConnectionString="Server=MyServer\SQL2012;Database=MySessionsDB;User ID=MySQLAccount;Password=MySQLAccount" timeout="20" />




To do this through the UI options of the IIS Manager, locate your Bizagi Work portal specific site, and click the Session state feature:




Make sure you tick the SQLServer mode, and specify further details.



If you wish to use a session state server instead, select State Server mode instead.


Notice that you need to select Enable custom database as well:




Notice that by default, a 20 minute Time-out is set.


For the Connection String, you may edit the field directly or use the Create... button to specify a connection assisted (recommended).

When doing so, consider:

Server: The identifier for the database server (or IP address), including its instance.

Database: The name of the database, just as created through the aspnet_regsql.exe utility in the previous step.

Credentials: Use the option to Specify credentials. Use the Set... button to input the account login and its password.




Click Ok to save changes.

You may verify the web.config file to check for such applied changes.



When having customized sections, or modifications at the web.config file, such as the one above, one of the two alternatives needs to be followed when carrying out a version upgrade:


1. If doing this through Bizagi Management Console, you will need to reconfigure and verify that the use of a session state is still applied after the upgrade (and backing up customizations before doing so is recommended).

Note that by default, the upgrade done by the Management Console will not consider if you have done modifications to the original files and file structure.


2. You may choose to do this through a manual procedure (without using Bizagi Management Console).

If you do, make sure you consider all the relevant components and files that you need to replace manually for the Work Portal and Scheduler, while verifying that you keep your configured customizations (in this case, the use of the session state database).