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

¹ 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

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

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

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

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

Remove/cleanup quietly without removing version from database

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

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

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.