# Manual Installation

## Overview <a href="#workflowgen-setup-manual" id="workflowgen-setup-manual"></a>

The following procedure applies to the setup using the WorkflowGen manual installation pack.

{% hint style="warning" %}
The [web server](https://docs.workflowgen.com/tech/8.0/system-requirements#web-server) and [database server](https://docs.workflowgen.com/tech/8.0/system-requirements#database-server) requirements must be met before proceeding with the following installation.
{% endhint %}

## Installation pack

Start by extracting the manual installation pack (`.zip`) to a temporary folder on the WorkflowGen web server (e.g. `DRIVE:\temp`).

The installation pack contains these folders:

* `Databases`: The MS SQL Server database creation scripts<br>
* `Inetpub`: The WorkflowGen application files<br>
* `Program Files`: The WorkflowGen Windows services application file

## WorkflowGen files and folders architecture

The recommended physical directory structure for WorkflowGen web application files and folders should be under `DRIVE:\Inetpub\wwwroot\wfgen`. This folder contains static resources such as images, HTML files and process data, and the applications used by WorkflowGen.

1. Copy the source `\Inetpub` folder to your destination `DRIVE:\` (e.g. `DRIVE:\Inetpub\wwwroot\wfgen`).<br>
2. Copy the source `Advantys` folder (`\Program Files\Advantys`) to your destination `DRIVE:\Program Files` (e.g. `DRIVE:\Program Files\Advantys\WorkflowGen\Services\bin`).<br>

   ✏️ **Note:** If you already have another version of WorkflowGen installed on the same server and you want to keep your previous WorkflowGen services, we suggest you choose another installation folder for version 8 (e.g. `DRIVE:\Program Files\Advantys\WorkflowGen v8\Services\bin`).

## Database creation

{% hint style="warning" %}
WorkflowGen does not support case sensitive collation, so you must set up the database to be case **insensitive** to avoid errors.
{% endhint %}

### MS SQL Server configuration

#### **Option 1: Create the database manually using the `create.sql` SQL script**

1. Open the SQL Server Management Studio tool and connect to your database server with an administrator account (e.g. `SA`).<br>
2. Create a new database (e.g. `WFGEN`).<br>
3. Create a new SQL Server user account (e.g. `WFGEN_USER`).<br>
4. Give this user `db_datawriter` and `db_datareader` permissions for the `WFGEN` database. <br>
5. Open the `DRIVE:\temp\manual\Databases\MsSQLServer` source folder and run the `create.sql` script on the new database instance.

#### **Option 2: Create the database manually using SQL scripts**

1. Open the SQL Server Management Studio tool and connect to your database server with an administrator account (e.g. `SA`).<br>
2. Create a new database (e.g. `WFGEN`).<br>
3. Create a new SQL Server user account (e.g. `WFGEN_USER`).<br>
4. Give this user `db_datawriter` and `db_datareader` permissions for the `WFGEN` database.<br>
5. Open the `DRIVE:\temp\manual\Databases\MsSQLServer` source folder and run the `create.sql` database creation script on the new database instance.

### Azure SQL database configuration

Azure SQL database needs to be created and configured manually; see the [Azure SQL database configuration](https://docs.advantys.com/workflowgen-for-azure/azure-sql-database-configuration) section in the [WorkflowGen for Azure](https://docs.advantys.com/workflowgen-for-azure/) guide for instructions on how to do this.

## WorkflowGen Administrator account setup

WorkflowGen requires a valid Windows NT or Active Directory account. This account will be used by the WorkflowGen Administrator, but it is not necessary to define it as a NT or Active Directory Administrator.

{% hint style="info" %}

* You can use an existing user account or create a new user account with the name `Domain\wfgen_admin`.<br>
* If you use a different account name other than `wfgen_admin`, then you **MUST** change the `WorkflowGen Administrator` username in the WorkflowGen database. To do this, in the **Users** table, find the record with the **USERNAME** column value `wfgen_admin`, then change it to your custom user account name.
  {% endhint %}

## WorkflowGen web configuration

1. Open and edit the `DRIVE:\Inetpub\wwwroot\wfgen\web.config` WorkflowGen web configuration file.<br>
2. Update the database connection string:<br>
   * **MS SQL Server:** `<add name="MainDbSource" connectionString="Data Source=localhost;Initial Catalog=WFGEN;User ID=WFGEN_USER;Password=Admin123!;" providerName="System.Data.SqlClient" />`<br>
   * **Azure SQL Database:** See the [Azure SQL Database Configuration](https://docs.advantys.com/workflowgen-for-azure/azure-sql-database-configuration) section in the [WorkflowGen for Azure](https://docs.advantys.com/workflowgen-for-azure/) guide.<br>
3. Update the "WorkflowGen Administrator" username to allow access to the configuration panel (e.g. `<add key="ApplicationConfigAllowedUsersLogin" value="wfgen_admin" />`).<br>
4. Update the application URL (e.g. `<add key="ApplicationUrl" value="http://yoursite/wfgen" />`).<br>
5. Add a 32-character alphanumeric encryption key (e.g. `<add key="ApplicationSecurityPasswordSymmetricEncryptionKey" value="XXXXXXXXXXXXXXXXXXX....." />`).

For more information about the other configuration settings, see the [Web and Application Configuration Parameters](https://docs.workflowgen.com/tech/8.0/appendix-web-and-application-configuration-parameters) appendix.

## WorkflowGen Windows Services installation

{% hint style="info" %}

* The user or identity used to run WorkflowGen Windows Services must be an administrator, be part of the **Administrators** group, or be a Windows system account (such as `Local System`). You can check this by running `services.msc`.<br>
* If you have specified a custom installation path for the services, you will need to update the path inside the `DRIVE:\Program Files\Advantys[Custom WorkflowGen]\Services\bin\winsvc-install.cmd` script (e.g. `%windir%\Microsoft.NET\Framework\v4.0.30319\InstallUtil.exe /i "C:\Program Files\Advantys\[Custom WorkflowGen]\Services\bin\WfgDirectoriesSyncService.exe"`).<br>
* If you are installing these services along with previous WorkflowGen services on the same server, you will need to provide a new service name (e.g. `WorkflowGenEngineServiceV7`) for both the Engine and Directory services in their configuration files (`[WfgWorkflowEngineService.exe].config`: `<add key="ServiceName" value="WorkflowGenEngineServiceV7"></add>`) and script files (`winsvc-install.cmd`: rename all `[WorkflowGenEngineService]` to `[WorkflowGenEngineServiceV7]`). (See the [Configuring multiple instances of WorkflowGen](https://docs.workflowgen.com/tech/8.0/advanced-configuration#configuring-multiple-instances-of-workflowgen) section for information and instructions on how to configure multiple WorkflowGen services on the same server.)
  {% endhint %}

### **Installation**

1. Open and edit the `DRIVE:\Program Files\Advantys\WorkflowGen\Services\bin\WfgWorkflowEngineService.exe.config` Engine service configuration file.<br>
2. Update the WorkflowGen web configuration path (e.g. `<add key="WebConfigPath" value="DRIVE:\inetpub\wwwroot\wfgen\web.config" />`).<br>
3. Open and edit the `DRIVE:\Program Files\Advantys\WorkflowGen\Services\bin\WfgDirectoriesSyncService.exe.config` Directory Synchronization service configuration file.<br>
4. Update the WorkflowGen web configuration path (e.g. `<add key="WebConfigPath" value="DRIVE:\inetpub\wwwroot\wfgen\web.config" />`).<br>

   ✏️ **Note:** `WfgWorkflowEngineService.exe` and `WfgDirectoriesSyncService.exe` might be blocked. To check this, right-click on them and choose **Properties**. If the **Security** section is displayed at the bottom of the **General** tab, these executables have been blocked; in this case, click **Unblock**.<br>
5. Run `DRIVE:\Program Files\Advantys\WorkflowGen\Services\bin\winsvc-install.cmd` **as Administrator**.

## Configuring IIS

### Creating the application pool

It is recommended that WorkflowGen be isolated from other applications by creating its own application pool and associating all declared applications with the new application pool.

{% hint style="info" %}
Domain users and the Windows accounts used to run the WorkflowGen IIS application pool and Engine service must have read and write permissions for the `\wfgen\app_data` folder.
{% endhint %}

1. In **IIS Manager**, click **Application pools**. In the right-hand pane, right-click and select **Add application pool**, and give it a name (e.g. `WorkflowGen`).<br>
2. Select the **.NET Framework 4** version.<br>
3. Select **Integrated pipeline mode**.<br>
4. Click **OK**.

### Creating the website (if WorkflowGen is set up on a new website)

1. Launch **IIS Manager** and expand the tree structure under the IIS server name where you want to create the new site.<br>
2. Right-click the **Sites** icon and select **Add Web Site**. Enter the name of the site, select its application pool (if other than the default), and enter the physical path of the root (click **Browse** and select the `\wwwroot` folder, usually `DRIVE:\inetpub\wwwroot\`).<br>
3. Select the binding as being `http` or `https` (note that `https` requires an SSL certificate). Select a port (the default is `80`) and/or a host header. Please contact your IIS administrator to review your options regarding setting up appropriate website settings.

### Configuring the website

#### **Default document**

The `default.aspx` default document type must be created if it does not exist. By default, this default document should exist on an IIS server running .NET.

To verify this, click the icon of the site, and ensure that the pane on the right-hand side shows the **Features view** (the tab at the bottom of the pane allows you to switch between **Features** and **Content**). Double-click the **Default document** icon. If `default.aspx` is missing from the list, add it to the beginning of the comma-separated list displayed. To improve performance you can move `default.aspx` to the beginning of the list if it is not already there.

#### **Authentication**

1. Click the icon of the site, and ensure that the pane on the right-hand side shows the **Features view**.<br>
2. Double-click the **Authentication** icon.<br>
3. Right-click on **Anonymous authentication** and select **Disable**.<br>
4. Right-click on **Basic authentication** and select **Enable**. You will be able to change the authentication method by following the instructions in the [Security](https://docs.workflowgen.com/tech/8.0/security) section.

### Creating the WorkflowGen application

1. In **IIS Manager**, right-click on `wfgen` under the `\wwwroot` folder and select **Convert to application**.<br>
2. Select the WorkflowGen application pool if it is not the default, then click **OK**.

### Creating workflow applications and services

The `\wfgen\ws` and `\wfgen\WfApps\WebForms` applications within WorkflowGen must be created. To do this, repeat the same steps you performed for `\wfgen` in the previous section.

### ISAPI and CGI restrictions

If you are using IIS 8 and above and your application pool is set to use **Classic Managed Pipeline Mode**, make sure ASP.NET v4.0.30319 is set to `Allowed` in the IIS manager **ISAPI and CGI Restrictions** list.

## Application files access configuration

### File permissions

File permission settings can be configured as follows for the WorkflowGen application identity:

* `DRIVE:\Inetpub\wwwroot\wfgen`: Modify all

According to your authentication method (see [Security](https://docs.workflowgen.com/tech/8.0/security)), the WorkflowGen application identity can be:

* The corresponding Windows users<br>
* The ASP.NET or IIS application pool identity

## Configuring the WorkflowGen root website to auto-redirect to the `wfgen` web app

If you would like your WorkflowGen root website (e.g. `https://server`) to auto-redirect to the `https://server/wfgen` web app, follow the procedure below.

{% hint style="info" %}
As of version 7.15.0, the PowerShell setup comes with this configuration pre-installed on your WorkflowGen server. This procedure is only applicable when installing WorkflowGen manually or upgrading an existing previous WorkflowGen server.
{% endhint %}

1. Make sure the [URL Rewrite](https://www.iis.net/downloads/microsoft/url-rewrite) tool is installed on your WorkflowGen server.<br>
2. Create or update the `web.config` file in your website's root folder (e.g. `DRIVE:\inetpub\wwwroot\web.config`).\
   \
   ⚠️ **Warning:** This is **not** the same `web.config` file as the main WorkflowGen `web.config` file (located in `DRIVE:\inetpub\wwroot\wfgen\web.config`).<br>
3. Define the rewrite rule node as shown below (`configuration` / `system.webServer` / `<rewrite>` / `<rules>` / `<rule>`):

   ```markup
   <?xml version="1.0" encoding="UTF-8"?>
   <configuration>
       <system.webServer>
           <rewrite>
               <rules>
                   <rule name="Rewrite to wfgen" stopProcessing="true">
                       <match url="(^$|^wfgen$|^wfgen/$)" />
                       <action type="Rewrite" url="/wfgen/show.aspx?QUERY=CONTEXT&amp;REQUEST_QUERY=WELCOME&amp;NO_REDIR=Y" />
                   </rule>
               </rules>
           </rewrite>
       </system.webServer>
   </configuration>
   ```

## WorkflowGen Node.js-based web applications

To use the optional GraphQL, incoming webhooks, OpenID Connect Auth, and SCIM APIs, you must first install the following requirements:

* [Node.js v14.16.1 LTS](https://nodejs.org/download/release/v14.16.1/)<br>
* [iisnode](https://github.com/Azure/iisnode/releases/tag/v0.2.21)<br>
* [IIS URL Rewrite](https://www.iis.net/downloads/microsoft/url-rewrite)<br>
* [Visual C++ Redistributable](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads)<br>

  ✏️ **Note:** This library is required if you encounter the error `The specified module could not be found` regarding the `edge` and `edge-js` libraries when accessing the `/wfgen/graphql`, `/wfgen/hooks`, or `/wfgen/scim` web apps.&#x20;

{% hint style="info" %}
After enabling GraphQL, incoming webhooks, OpenID Connect Auth, or SCIM, the WorkflowGen DLLs will be in use by Node.js, so they will be locked from being updated. In order to update the DLLs, it is necessary to stop IIS.
{% endhint %}

### **Enabling WorkflowGen GraphQL**

1. In IIS, convert `/wfgen/graphql` to an application with a .NET 4 application pool (integrated pipeline). <br>
2. Configure the GraphQL application authentication mode: <br>
   * **For Windows or Basic authentication:** Enable Basic authentication. <br>
   * **For WorkflowGen Applicative authentication:**
     * Make sure the `/wfgen` web application already has WorkflowGen Applicative authentication enabled.
     * Enable Anonymous authentication.

### **Enabling WorkflowGen incoming webhooks**

In IIS, convert `/wfgen/hooks` to an application with a .NET 4 application pool (integrated pipeline), and configure the webhook application in **Anonymous** authentication mode.

{% hint style="info" %}
If your WorkflowGen is configured to use WorkflowGen Applicative authentication or a custom authentication, you must remove the authentication module from the `/hooks/web.config` file by defining a `<location>` node within the `<configuration>` node as follows:

#### **For WorkflowGen Applicative authentication:**

```markup
<location path="hooks" inheritInChildApplications="false">
    <system.webServer>
        <modules>
            <remove name="ApplicationSecurityAuthenticationModule" />
        </modules>
    </system.webServer>
</location>
```

#### **For Custom authentication:**

```markup
<location path="hooks" inheritInChildApplications="false">
    <system.webServer>
        <modules>
            <remove name="MyCustomAuthModule" />
        </modules>
    </system.webServer>
</location>
```

{% endhint %}

### **Enabling WorkflowGen OpenID Connect Auth**

In IIS, convert `/wfgen/auth` to an application with a .NET 4 application pool (integrated pipeline), and configure the application in **Anonymous** authentication mode. &#x20;

{% hint style="info" %}
If your WorkflowGen is configured to use WorkflowGen Applicative authentication or a custom authentication, you must remove the authentication module from the `/auth/web.config` file by defining a `<location>` node within the `<configuration>` node as follows:

#### **For WorkflowGen Applicative authentication:**

```markup
<location path="auth" inheritInChildApplications="false">
    <system.webServer>
        <modules>
            <remove name="ApplicationSecurityAuthenticationModule" />
        </modules>
    </system.webServer>
</location>
```

#### **For Custom authentication:**

```markup
<location path="auth" inheritInChildApplications="false">
    <system.webServer>
        <modules>
            <remove name="MyCustomAuthModule" />
        </modules>
    </system.webServer>
</location>
```

{% endhint %}

### **Enabling WorkflowGen SCIM**

In IIS, convert `/wfgen/scim` to an application with a .NET 4 application pool (integrated pipeline), and configure the application in **Anonymous** authentication mode. &#x20;

{% hint style="info" %}
If your WorkflowGen is configured to use WorkflowGen Applicative authentication or a custom authentication, you must remove the authentication module from the `/scim/web.config` file by defining a `<location>` node within the `<configuration>` node as follows:

#### **For WorkflowGen Applicative authentication:**

```markup
<location path="scim" inheritInChildApplications="false">
    <system.webServer>
        <modules>
            <remove name="ApplicationSecurityAuthenticationModule" />
        </modules>
    </system.webServer>
</location>
```

#### **For Custom authentication:**

```markup
<location path="scim" inheritInChildApplications="false">
    <system.webServer>
        <modules>
            <remove name="MyCustomAuthModule" />
        </modules>
    </system.webServer>
</location>
```

{% endhint %}