Command line configuration

You can configure process packages using command line parameters. The parameters that are used in the command line depend on the selected role.

Cross Origin Resource Sharing (CORS)

If WorkZone Process services are to be requested from web clients executed by a web browser and loaded from other domains (for example WorkZone Client and WorkZone Configurator applications hosted on a different host than Process service), you must configure the Cross-Origin Resource Sharing parameters (AllowedCORSOrigins and AllowedCorsHeaders).

See the list below for an overview of parameters and roles.

General configurations

Parameter Role Description Required/Optional

-quiet

All

Runs the Configurator without displaying the user interface.

Optional

-verbose

All

Displays progress information during configuration. The verbose mode is only relevant to use together with the quiet mode.

Optional

-remove

All

Removes the configuration.

Optional

-val

All

Validates specific roles and their associated features. No configuration will be done.

Optional

-log:C:\1.log

All

Name and destination of log file. Logs output from the Configurator to the log file.

Optional

Roles

All

Specifies which role to configure. Roles are: All, Web, Agent, Web;Agent, and DBOnly.

The All and Web;Agent values are the same. Web;Agent is the default value.

In the WorkZone Process Configuration Wizard, only the Web, Agent, and DBOnly options are available. For example, if you do not provide the Roles parameter using command line configuration, and you execute the configurator in user interface mode, the wizard will open the start page with the Web and Agent options selected corresponding to the default value Web;Agent.

DBRole

Select the DBOnly role, if you only want to configure the database.

Roles="DBOnly"

Note: You cannot select the DBOnly role in combination with other roles.

If you select a wrong set of values and launch the WorkZone Process Configuration wizard in quiet mode, it will return an error message.

The correct values for the Roles parameter are: ALL, Web, Agent, Web;Agent, and DBOnly.

Example:

Roles="DBOnly"—to configure the database.

Roles="Web;Agent" SetupDatabase=false—to configure everything else except the database.

Optional

IgnoreCertificateErrors

All

Configures all process workflows and ignores certificate errors.

Optional

DataSourceName=<ODBC datasource name>

All

The name of the database.

Required

DatabaseUserName=<name>

All

The user name of the WorkZone database administrator. For example, sjsysadm.

Required

DatabasePassword=<password>

All

The password for the WorkZone database.

Required

ContentServerUri=<url>

All

Link to the WorkZone site. For example, https://db01.lmdom.local

Required

Packages=<Extended.wzp>

Web

File name(s) of packages in the Packages folder. The Basis package is always installed. You do not need to specify it.

Optional

SetupDatabase

Database

Configures the database.

By default, this parameter is set to True.

If you set the SetupDatabase parameter to False, WorkZone Process Configurator will not make any connections to the database. This is relevant, if you do not yet have a database available. Be aware that until a database is available and configured, WorkZone Process will not work.

Optional

ForcePackageLoad

Web

Forces reload of process packages. By default, process packages are only loaded once into the database but in some situations you may want to reload the packages, for example when you install a hotfix.

Optional

PackageLoadTimeout

Web

Controls the timeout for loading a process package. You can specify a time using the time format hh:mm:ss.

For example:

  • 00:05:00 (5 minutes)
  • 00:00:30 (30 seconds)
  • 01:00:00 (One hour)

If you do not specify this parameter, the default timeout is 5 minutes.

Optional

OAuthClientSecret

All

Secret for the WorkZone Process OAuth client. The client is added automatically by WorkZone Process Configurator. The secret can be any string, but it must be exactly the same for all servers configured with WorkZone Process Configurator.

You can see the WorkZone Process OAuth client configuration in WorkZone Configurator. See OAuth2 settings in the WorkZone Configurator Administrator Guide.

If the WorkZone Process OAuth client is already configured, and you don't know the existing client secret, you have two options:

  • Delete the existing WorkZone Process OAuth client from WorkZone Configurator and re-configure WorkZone Process with a new client secret on all servers.
  • Overwrite the existing WorkZone Process OAuth client with a new client secret in WorkZone Configurator and reconfigure WorkZone Process on all servers with the new secret.

Note: This parameter is required if you use the OAuth authentication method.

Optional

AllowedCorsOrigins

Web

Define which web client applications executed in a browser hosted on other domains will be able to perform CORS requests from the server.

An origin for the AllowedCorsOrigins parameter1 must be defined as:

<scheme>://[<hostname>.]<host>[:<port>], for example Https://WZClient if the WorkZone Client is hosted on Https://WZClient and the rest of WorkZone services are hosted on another domain, such as Https://WZServices.

Origins are separated with semi-colons ";".

When using Cross-Origin Resource Sharing (CORS) with WorkZone , this parameter should be set to the specific origins as most browsers will prevent passing credentials or tokens to the service when the wild card (*) is used as the origin.

Using the wild card (*) origin means the WorkZone Process service is open for every origin. It is used when the wild card origin (*) is the only origin that is set in the configuration file or in the corresponding system environment variable, or the origin of the request is not found and the AllowedCorsOrigins parameter contains the wild card origin (*).

Example: The following parameter in the Web Config file: <add key="allowCorsOrigin" value="*" /> will fail unless the wild card origin "*" is replaced with the specific origins of the web client to be accessed.

The default value if no origins are specified is wild card (*).

 

AllowedCorsHeaders

Web

Used in a response to OPTIONS preflight request. Indicates which headers can be used during the actual HTTP CORS request.

The AllowedCorsHeaders parameter corresponds to Access-Control-Allow-Header response header (ACAH) and acts as an answer to request’s Access-Control-Request-Headers request header.

The AllowedCorsHeaders parameter1 can be configured with:

- “*” The Access-Control-Allow-Header will contain headers requested by the request as well as specific PDF headers.

- specified headers (ACAH header will contain these headers as well as specific PDF headers).

- both * and specified headers (ACAH will contain headers from the configuration and headers requested by the request as well as specific PDF headers).

The default value if no origins are specified is wild card (*).

 

1 These parameters are also mapped to the following system environment variables on the server:

  • WORKZONE_PROCESS_CORS_ALLOWEDORIGINS
  • WORKZONE_PROCESS_CORS_ALLOWEDHEADERS

System environment variables take precedence over the parameters defined in the web.config files.

Exchange configurations using EWS (Exchange Web Services)

The Exchange configurations depend on whether your organization uses Exchange On-Premises or Exchange Online. The difference between the Exchange Online and On-Premises configurations is the credentials that are used when communicating with the Exchange server. On-Premises communication uses the credentials of the process service account user and the Online communication uses the credentials of the email account.

Parameter Role Description Environment variables Required /Optional

ExchangeWebServicesUri=<Exchange EWS url>

Agent

The endpoint for the Exchange service, for example: https://dc1.lmdom.ocal/EWS/Exchange.asmx

Note: This parameter is not required if the UseAutodiscover parameter is set to TRUE.

WORKZONE_PROCESS_EXCHANGE_SERVER_URI

Required

ExchangeMailbox=<mail address>

Agent

The email address of the Exchange user who sends smartmails. If the parameter is not defined, the email address defined in the ServiceUserName parameter is used. For example, mailagent@lmdom.local.

Note: This parameter is required if the UseAutodiscover parameter is set to TRUE.

WORKZONE_PROCESS_EXCHANGE_MAILBOX

Optional

UseAutoDiscover

Agent

If set to TRUE, Autodiscover is called every time the service starts to resolve the ExchangeWebServicesUri parameter.

Default is FALSE

Note: This parameter is not applicable if you have configured WorkZone Process to use the OAuth authentication method.

 

Optional

ExchangeUserName=<name>

Agent

The email address of the Exchange user who sends smartmails.

If specified, it is used as part of the credential. Note that if you specify a user name, you must also specify a password in the ExchangeUserPassword parameter.

Note: This parameter is required if you use the OAuth authentication method.

WORKZONE_PROCESS_EXCHANGE_USER_NAME

Optional

ExchangeUserPassword=<password>

Agent

The email address password of the Exchange user who sends smartmails.

If the ExchangeUserName parameter is specified, the password is used as part of the credentials.

Note: This parameter is required if you use the OAuth authentication method.

WORKZONE_PROCESS_EXCHANGE_USER_PASSWORD

Optional

ExchangeUserDomain=<domain>

Agent

The domain where the Exchange user is located.

If the ExchangeUserName parameter is specified, the domain is used as part of the credentials. If you have specified the domain as part of the ExchangeUserName parameter, leave this parameter empty.

Note: This parameter is required if you use the OAuth authentication method.

WORKZONE_PROCESS_EXCHANGE_USER_DOMAIN

Optional

ExchangeServerVersion

Agent

Used to identify which version of Exchange is used server side.

WORKZONE_PROCESS_EXCHANGE_VERSION

Optional

Exchange configurations in cloud using Microsoft Graph

WorkZone Process Configurator supports both the public client and client credential authentication flows for Exchange Online with OAuth.

Public client flow

The public client flow corresponds to the configuration that you can set up using the WorkZone Process Configuration Wizard where you specify email address and password. See Use Exchange Online.

Azure Active Directory prerequisites

The PublicClient flow requires that an application registration is added in AAD (Azure Active Directory) for the specific tenant and that the Allow public client flows option is set for this application on the Authentication page on the control panel for the added application. It is also required to add the following delegated permissions for Microsoft Graph:

  • Mail.ReadWrite
  • Mail.ReadWrite.Shared
  • Mail.Send
  • Mail.Send.Shared
  • User.Read
  • User.ReadBasic.All
Parameter Role Description Environment variable Required /Optional

ExchangeOAuthClientId

Agent

The GUID of the client ID.

WORKZONE_PROCESS_EXCHANGE_CLIENTID

Required

ExchangeOAuthTenantId

Agent

The GUID of the tenant ID.

WORKZONE_PROCESS_EXCHANGE_TENANTID

Required

ExchangeMailbox

Agent

The email address of the Exchange user who sends smartmails.

WORKZONE_PROCESS_EXCHANGE_MAILBOX

Required

ExchangeUserPassword

Agent

The password of the service user mailbox.

WORKZONE_PROCESS_EXCHANGE_USER_PASSWORD

Required

The client credential flow

This flow is only supported using command line configuration. You cannot use the WorkZone Process Configuration Wizard. It is more complex to configure this flow properly to keep the desired security level, and setting the permissions requires setting a higher access level from the AAD administrators. Therefore this is not the recommended flow.

Azure Active Directory prerequisites

The ClientCredentials flow requires that an application registration is added in AAD (Azure Active Directory) for the specific tenant and that the following application permissions are added for Microsoft Graph:

  • Mail.ReadWrite
  • Mail.Send
  • User.Read.All

Furthermore, permissions must be scoped to the desired mailbox accounts to ensure proper security. See: Scoping application permissions to specific Exchange Online mailboxes in the Microsoft documentation.

Parameter Role Description Environment variable Required /Optional

ExchangeOAuthClientId

Agent

The GUID of the client ID.

WORKZONE_PROCESS_EXCHANGE_CLIENTID

Required

ExchangeOAuthTenantId

Agent

The GUID of the tenant ID.

WORKZONE_PROCESS_EXCHANGE_TENANTID

Required

ExchangeMailbox

Agent

The email address of the Exchange user who sends smartmails.

WORKZONE_PROCESS_EXCHANGE_MAILBOX

Required

ExchangeOAuthClientSecret Agent The secret used to access the application in Azure Active Directory.

WORKZONE_PROCESS_EXCHANGE_CLIENTSECRET

Required

Service account configuration parameters (also used by the mail agents)

Parameter Role Description Agent and Web

ServiceUserName=<service user>

Agent and Web

The user name of a WorkZone service account user who can access WorkZone.

The credentials of the service account user is used when communicating with the Exchange server if the ExchangeUserName parameter is empty.

For example: mailagent@lmdom.local.

Required

ServicePassword=<password>

Agent and Web

The password for the WorkZone service account user.

The credentials of the service account user is used when communicating with the Exchange server if the ExchangeUserName parameter is empty.

Required

ServiceDomain=<domain>

Agent and Web

The domain where the WorkZone service account user is located.

The credentials of the service user account is used when communicating with the Exchange server if ExchangeUserName is empty.

Required

Command line configuration examples

When you have installed all options, you can configure the servers. Copy the code examples below to use the code strings as a starting point for the server configurations.

Configure command line - install both roles

The following example can be modified to configure the web.and agent roles.

Scanjour.Process.Configurator.exe -quiet -verbose DataSourceName=DB01 DatabaseUserName=sjsysadm DatabasePassword=<password> ContentServerUri=https://db01.lmdom.local ServiceUserName=<service user> ServiceDomain=<domain> ServicePassword=<password> ExchangeServerUri=https://DC1.lmdom.local/EWS/Exchange.asmx ExchangeMailbox=mailagent@lmdom.local Packages=<Package1.wzp,Package2.wzp> -log:C:\1.log

The copy image is missing

Configure command line - Install agent role only

The following example can be modified to configure the agent role.

Scanjour.Process.Configurator.exe -quiet -verbose Roles="Agent" DataSourceName=DB01 DatabaseUserName=sjsysadm DatabasePassword=<password> ContentServerUri=https://db01.lmdom.local ServiceUserName=<service user> ServiceDomain=<domain> ServicePassword=<password> ExchangeServerUri=https://DC1.lmdom.local/EWS/Exchange.asmx ExchangeMailbox=mailagent@lmdom.local -log:C:\1.log

The copy image is missing

Configure command line - Install web role only

The following example can be modified to configure the web role.

Scanjour.Process.Configurator.exe -quiet -verbose Roles="Web" DataSourceName=DB01 DatabaseUserName=sjsysadm DatabasePassword=<password> ContentServerUri=https://db01.lmdom.local ServiceUserName=<service user> ServiceDomain=<domain> ServicePassword=<password> Packages=<Package1.wzp,Package2.wzp> -log:C:\1.log

The copy image is missing

Use a different user or Exchange server in a foreign domain

To be able to send e-mails from an Exchange server in a foreign domain, add the following parameters ExchangeUserName:<name>, ExchangeUserPassword:<password> , ExchangeUserDomain:<domain>.

Scanjour.Process.Configurator.exe -quiet -verbose DataSourceName=DB01 DatabaseUserName=sjsysadm DatabasePassword=<password>ContentServerUri=https://db01.lmdom.local ServiceUserName=<service user> ServiceDomain=lmdom ServicePassword=<password> ExchangeServerUri=https://DC1.lmdom.local/EWS/Exchange.asmx ExchangeUserDomain=lmdom.local ExchangeUserName=<name> ExchangeUserPassword=<password> -log:C:\1.log

The copy image is missing

Exchange Online configuration

To be able to send smartmails from an Online Exchange account, add the following parameters UseLocalExchangeServer=false ExchangeUserName=<name> ExchangeUserPassword=<password>.

Scanjour.Process.Configurator.exe -quiet -verbose DataSourceName=DB01 DatabaseUserName=sjsysadm DatabasePassword=<password> ContentServerUri=https://db01.lmdom.local ServiceUserName=<service user> ServiceDomain=<domain> ServicePassword=<password> UseAutodiscover=True ExchangeUserName=<name> ExchangeUserPassword=<password> Packages=<Package1.wzp,Package2.wzp> -log:C:\1.log

The copy image is missing

Remove/cleanup quietly without removing version from database

Scanjour.Process.Configurator.exe -remove -quiet -verbose

The copy image is missing

OAuth authentication method

Scanjour.Process.Configurator.exe -quiet -verbose DataSourceName=DB01 DatabaseUserName=sjsysadm DatabasePassword=<password> OAuthClientSecret=<secret> ContentServerUri=https://db01.lmdom.local ExchangeServerUri=https://DC1.lmdom.local/EWS/Exchange.asmx DedicatedExchangeCredentials=true ExchangeUserName=sa_wzprocess ExchangeUserDomain=lmdom ExchangeUserPassword=<password> -log:C:\1.log

The copy image is missing

Ensure that access codes and start and end dates are not overwritten

Using the Packagesparameter, you can modify access codes and the start and end date for a process. If the package does not contain values for the entries that you modify, your values will be preserved if the package is loaded again.

Package names should not contain special characters, including [.] and [,]. The reason behind this recommendation is that the –packages argument is interpreted as a comma separated list and compares the specified names with the name of the package in the package folder.