Persistence Provider Initialization

First, it is necessary to determine whether you need an SQL or NoSQL database and download the necessary provider from the downloads page or via NuGet. You will find provider's source code in the downloaded archive or in our GitHub repository.

If you use an RDMS such as MS SQL Server, PostgreSQL, Oracle or MySql you have to run the CreatePersistenceObjects.sql script, that creates the following tables in the database:

• WorkflowProcessScheme — all process schemes are kept here. The Scheme column contains a serialized XML scheme, the SchemeCode column has the scheme name (code). DefiningParameters and DefiningParametersHash columns contain the parameters passed to the scheme generator (feel free to explore the Scheme Generation section to learn how to use them). IsObsolete indicates the scheme's relevance: if it's relevant, new processes will rest on it (read the Schemes Update section). Other columns contain data for creating subprocesses (read about parallel branches in the Parallel Branches section).
• WorkflowProcessInstance — contains process data, such as the current activity and state, previous activities, etc. There is also IDs of parent and root processes here.
• WorkflowProcessInstancePersistence — this table keeps process parameters. Parameter values are serialized in JSON and shown in the Value column.
• WorkflowProcessTransitionHistory — contains information about successful process transitions. The table is used for process tracking.
• WorkflowProcessInstanceStatus — the Status field indicates current process status: 0 - Initialized, 1 - Running, 2 - Idled, 3 - Finalized.
• WorkflowProcessTimer — contains trigger actuation times for different processes.
• WorkflowGlobalParameter — global Code Actions and subprocess trees are stored here.
• WorkflowScheme — this table is used by the scheme generator by default. The scheme from designer is saved here; if WorkflowRuntime can't find a relevant scheme in the WorkflowProcessScheme table, it grabs the scheme from here.
• WorkflowInbox — doesn't belong to Workflow Engine but is used in our examples as the inbox folder.
• WorkflowRuntime - information about all workflow runtimes connected to this database is kept here.
• WorkflowSync - is used in the multi-server mode for timer synchronization.

If you use Oracle, the tables will have different names:

• WORKFLOWPROCESSTRANSITIONH instead of WorkflowProcessTransitionHistory;
• WORKFLOWPROCESSINSTANCEP instead of WorkflowProcessInstancePersistence;
• WORKFLOWPROCESSINSTANCES instead of WorkflowProcessInstanceStatus;

Furthermore, all data are kept structurally in similar objects with MongoDB.

Take a look at the example of persistence provider initialization that you will need in the next section. The code for relational databases is quite similar.

.NET Framework

The ConnectionString initialization for WorkflowRuntime should be specified and use it at the start of the application.

MS SQL Server

// Get a DB connection string
var connectionString = System.Configuration.ConfigurationManager.ConnectionStrings["ConnectionString"].ConnectionString;
// Initiate a provider
var dbProvider = new MSSQLProvider(connectionString);

MySQL

// Get a DB connection string
var connectionString = System.Configuration.ConfigurationManager.ConnectionStrings["ConnectionString"].ConnectionString;
// Initiate a provider
var dbProvider = new MySQLProvider(connectionString);

PostgreSQL

// Get a DB connection string
var connectionString = System.Configuration.ConfigurationManager.ConnectionStrings["ConnectionString"].ConnectionString;
// Initiate a provider
var dbProvider = new PostgreSQLProvider(connectionString);

Oracle

// Get a DB connection string
var connectionString = System.Configuration.ConfigurationManager.ConnectionStrings["ConnectionString"].ConnectionString;
// Initiate a provider
var dbProvider = new OracleProvider(connectionString);

MongoDB

// Get DB's URL and name from config
var url = ConfigurationManager.AppSettings["Url"];
var databaseName = ConfigurationManager.AppSettings["DatabaseName"];
// Create a MongoDatabase object
var mongoDatabase = new MongoClient(url).GetServer().GetDatabase(databaseName);
// Initiate a provider
var dbProvider = new MongoDBProvider(mongoDatabase);

In addition, you should specify the connection string in the application configuration file web.config depending on your database provider and according to the following syntax.

<configuration>
    <connectionStrings>
        <add name="ConnectionString"
             providerName="System.Data.ProviderName"
             connectionString="Valid Connection String;"/>
    </connectionStrings>
</configuration>

.NET Core and .NET

To connect to the database you need the following:

1. A connection string to connect to the database. For example, you can describe it in appsettings.json in the ASP.NET application.
2. Create an instance of the database provider.
3. Pass the database provider instance when creating the Workflow Engine.

Below are examples for different databases (ASP.NET):

MS SQL Server

appsettings.json

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=(local);Initial Catalog=wfe_sample;User ID=sa;Password=1"
  }
}

Program.cs

var connectionString = app.Configuration.GetConnectionString("DefaultConnection");
var provider = new MSSQLProvider(connectionString);
var runtime = new WorkflowRuntime()
    .WithPersistenceProvider(provider);

MySQL

appsettings.json

{
  "ConnectionStrings": {
    "DefaultConnection": "server=127.0.0.1;uid=root;pwd=myPassword;database=wfe_sample"
  }
}

Program.cs

var connectionString = app.Configuration.GetConnectionString("DefaultConnection");
var provider = new MySQLProvider(connectionString);
var runtime = new WorkflowRuntime()
    .WithPersistenceProvider(provider);

info

The root user does not have a default password. You either need to change the connection setting in configuration file or change the root account to match the password.

PostgreSQL

appsettings.json

{
  "ConnectionStrings": {
    "DefaultConnection": "User ID=postgres;Password=1;Host=localhost;Port=5432;Database=wfe_sample;"
  }
}

Program.cs

var connectionString = app.Configuration.GetConnectionString("DefaultConnection");
var provider = new PostgreSQLProvider(connectionString);
var runtime = new WorkflowRuntime()
    .WithPersistenceProvider(provider);

Oracle

appsettings.json

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(COMMUNITY = tcp.world)(PROTOCOL = TCP)(Host = MyHost)(Port = 1521)))(CONNECT_DATA=(SID=MyOracleSID)));User ID=myUsername;Password=myPassword;"
  }
}

Program.cs

var connectionString = app.Configuration.GetConnectionString("DefaultConnection");
var provider = new OracleProvider(connectionString);
var runtime = new WorkflowRuntime()
    .WithPersistenceProvider(provider);

MongoDB

appsettings.json

{
  "ConnectionStrings": {
    "DefaultConnection": "mongodb://localhost:27017/WorkflowEngine"
  }
}

Program.cs

var connectionString = app.Configuration.GetConnectionString("DefaultConnection");
var dbName = MongoUrl.Create(connectionString).DatabaseName;
var client = new MongoClient(connectionString);
var provider = new MongoDBProvider(client.GetDatabase(dbName));
var runtime = new WorkflowRuntime()
    .WithPersistenceProvider(provider);

The next section outlines WorkflowRuntime object initialization and creation.