Disclaimer

The material in this document is for informational purposes only. The products it describes are subject to change without prior notice, due to the manufacturer’s continuous development program. Nuix makes no representations or warranties with respect to this document or with respect to the products described herein. Nuix shall not be liable for any damages, losses, costs or expenses, direct, indirect or incidental, consequential or special, arising out of, or related to the use of this material or the products described herein.

© Nuix Canada Inc. 2024 All Rights Reserved

Introduction

This guide describes the installation of Automate. This document works like a reference - use the table of contents to look for the topic that you find out about.

The Automate software and this documentation may contain bugs, errors, or other limitations. If you encounter any issues with the Automate software or with this documentation, please contact nuix support.

While we accept feedback on all versions on the product, support is limited to the latest major and the latest minor version from the quarterly and yearly release channels. Automate recommends subscribing to product update notifications and reviewing and applying the updates within a short time after they become available.

The software requires a valid Automate license. The license is typically time-limited, and certain features of the software require a specific license edition. If you encounter any issues with the Automate license, or for specific questions about a product feature, please contact nuix support.

Styles Used in This Guide

Note: This is icon indicates that additional clarifications are provided, for example what the valid options are.
Tip: This icon lets you know that some particulary useful tidbit is provided, perhaps a way in which to use the application to achieve a certain behavior.
Warning: This icon highlights information that may help you avoid an undesired behavior.

  • Emphasized: This style indicates the name of a menu, option or link.

  • code: This style indicates code that should be used verbatim, and can refer to file paths, parameter names or Nuix search queries.

1. Architecture

1.1. Components

Several components are part of a Automate deployment:

  • Automate Scheduler: Receives requests from the analysts or from enterprise services for queuing jobs and dispatches the jobs to the Automate Engine Servers.

  • Automate Engine Server: Receives jobs from Automate Scheduler, starts Engines and runs jobs.

  • Nuix Engine: The Nuix Engine creates/opens Nuix cases and performs the required work in the cases.

  • Nuix License Source: One or several Nuix licenses sources can be used, of the following types:

    • Nuix NMS

    • Nuix License Dongle

    • Nuix Cloud License

  • Authentication Source: The service that will be used to authenticate users and determine group membership. This can be a combination of the following:

    • Nuix UMS: The Nuix User Management server

    • LDAP: On-premise Active Directory

    • Azure AD: Microsoft Azure Active Directory

    • OIDC: An Open ID Connect compliant authentication service

    • Internal: Internally defined usernames and passwords, for initial configuration.

Additionally, the following components are optional:

  • Automate OData Server: Returns utilization data using the OData protocol.

  • Automate Proxy: Offloads the data upload and hashing from the main Automate Scheduler.

  • Business Intelligence Software: A software tool that queries the Automate environment for metrics, analyzes the data and provides interactive dashboards, such as Microsoft Power BI or Tableau.

  • Microsoft SQL: Can be used to replace the built-in Scheduler database for storing job information, configuration, and audit logs.

1.2. Deployment

With the exception of Automate Engine Server which needs to be installed on each Nuix server that will be part of the Automate deployment, all remaining components can be deployed either on the same server or on dedicated servers.

When deploying the optional Automate OData Server on a server different than the server hosting Automate Scheduler, the utilization data must be redirected from the embedded database to a Microsoft SQL database.

1.2.1. Sample Distributed Architecture

This sample architecture consists in a dedicated server which hosts Automate Scheduler, several servers which host Automate Engine Servers and Nuix Engines, dedicated servers for the Nuix NMS and Nuix UMS, and connectivity with Azure AD.

Sample distributed architecture

1.2.2. Sample Standalone Architecture

This sample architecture consists in a single server which hosts the Automate Scheduler and the Automate Engine Server, several Nuix Engines, as well as the Nuix NMS and Nuix UMS.

Sample standalone architecture

1.3. Network Traffic Flow

Components in an Automate deployment communicate over HTTP. To configure the TCP ports and TLS certificates, please see section Configuration.

Traffic flow
Source Destination Protocol (Port)

Analyst Web Browser

Automate Scheduler

HTTPS (TCP/443)

Analyst Web Browser

Azure AD

HTTPS (TCP/443)

Automate Scheduler

Automate Engine Server

HTTPS (TCP/443)

Automate Engine

Automate Scheduler

HTTPS (TCP/443)

Automate Scheduler

Nuix UMS

HTTPS (TCP/443)

Automate Scheduler

Azure AD

HTTPS (TCP/443)

Nuix Engine

Nuix NMS

HTTPS (TCP/27443)

2. Prerequisites

See https://nuix.service-now.com/support?id=kb_article_view&sys_kb_id=7ef9b32b47cc96102d9c89cbd36d4368

3. Configuration

3.1. Service Settings

The configuration files are located at the following locations:

  • Automate Scheduler C:\ProgramData\Nuix\Automate\Scheduler\config\config.yml

  • Automate Engine Server C:\ProgramData\Nuix\Automate\EngineServer\config\config.yml

  • Automate OData Server C:\ProgramData\Nuix\Automate\ODataServer\config\config.yml

Additionally, certain Scheduler Service configuration options can be set using environmental variables (see section Scheduler Service Environmental Variables for more details.)

3.1.1. Scheduler Service Settings

These files follows the YAML Syntax and contain the following parameters:

  • role: SCHEDULER, indicating that the Automate Scheduler component will run;

  • apiSecret: Key used for the authentication between Automate components. Set the same random value on all Automate Scheduler, Proxy and Server instances.

  • internalCredentials: Indicates that credentials defined in the configuration file will be used for authentication. The configuration is provided in the following subkeys:

    • displayName: (Optional) The name to display in the login page for this authentication method.

    • restrictToLocalhost: (Optional) Restrict the availability of the Internal authentication to browsers from localhost. If this property is not specified, it defaults to false.

    • usersEligibleLegalHoldAdministrator: (Optional) Make Internal users eligible for Legal Hold Administrations. If this property is not specified, it defaults to false.

    • usersEligibleLegalHoldCustodian: (Optional) Make Internal users eligible for Legal Hold Custodians. If this property is not specified, it defaults to false.

    • credentials: The list of credentials.

The credentials can be provided in either PBKDF2 format, using:

  • username

  • email

  • salt, a base64 encoded string

  • iterations, the number of hash iterations

  • hash, computed using the PBKDF2WithHmacSHA512 algorithm with a key length of 512 bits.

or in cleartext, using:

  • username

  • email

  • password

Sample Internal authentication configuration with 2 users:

internalCredentials:
  displayName: UsernamePassword
  restrictToLocalhost: true
  credentials:
    - username: user1
      email: user1@example.com
      salt: NlbCqq8kL6sqdZQrjMmgSw==
      iterations: 1000000
      hash: ca4xiopDRshgyKvArOfKqBoDeVfbsOpayzVrh8n1WAWOhqvunITolqBBTiSAn1VxTBUz+15IfX4qxiTuHrthuA==

    - username: user2
      email: user2@example.com
      password: Password2@
The Internal authentication method requires storing the usernames and passwords or hashes in the configuration file. It’s recommended to restrict this method to localhost.
Set the restrictToLocalhost property to true to only allow logging in with internal credentials when accessing Automate as localhost.

  • userSessionTimeout: The duration in seconds of inactivity after which a user session expires.

  • nuixEnginePath: The location of the Nuix Engine deployment. This folder should contain bin, lib, and user-data subfolders directly.

  • log4jConfigurationFile: The log4j configuration file.

  • enableCentralizedLogging: true or false indicating if the centralized logging feature is enabled.

By default this feature is enabled, to disable this feature set the value to false

  • centralizedLoggingRetention: The duration in days that the logs will be retained for.

  • centralizedLoggingMaxSize: The max database size in bytes before a rollover.

  • centralizedLoggingSizeCheckInterval: The duration in seconds after which the database performs a size check.

  • enableRollingLoggingDatabases: When the logging database is configured for SQLite databases will be rolled, for example when the logging databases reaches the maximum size defined in the centralizedLoggingMaxSize divided by the number of rolling databases defined in the maxRollingLoggingDatabases setting. The database will be renamed and a new database will be created. By default, this feature is disabled. For example, if the user had a max size of 1GB and 5 rolling databases then the max size for all the rolling databases with be 200MB.

When the database is rolling logs, logs downloaded will be a stripped down version containing everything except the actual logs from the database and centralized logging will be disabled temporarily. If the database rotation occurs while the user is downloading logs, the download thread will exit and give the user the logs that it was able to collect and log a warning to inform the user that the download exited due to the rotation.

  • maxRollingLoggingDatabases: The maximum number of rolling databases. When the maximum number of databases is reached, the database with the oldest logs will be deleted.

  • enableCentralizedLoggingDownloadTimeout: true or false indicating if the centralized logging download timeout feature is enabled.

This feature will close the stream for downloading logs after a set interval defined in the centralizedLoggingDownloadTimeout` setting. This feature is only recommended for troubleshooting purposes and is disabled by default.

  • centralizedLoggingDownloadTimeout: The amount of time in milliseconds to download logs before exiting, by default this value is set to 180000 (3 minutes).

  • engineInitLogFolder: The log folder to use during the Engine initialization, before running job.

  • archiveJobsPastDuration: The duration in seconds after which finished jobs are automatically archived.

  • archiveJobsPastCount: The maximum number of finished jobs after which the oldest job is automatically archived.

  • server: Indicates the IP/ports to listen on and the TLS certificate for HTTPS connections.

By default, the service listens on HTTP on port 80 on localhost, and on HTTPS on port 443 all IP addresses. To restrict the server to listen on a specific IP address, change 0.0.0.0 to the required IP address in the config.yml file.
If upgrading Scheduler from a version prior to 6.0, the server will only accept HTTP/1.1 connections by default. To enable HTTP/2 connections, change type: https to type: h2 in the config.yml file.

  • webConfiguration: Indicates which Web settings to apply to the Web server used for the REST API, including HSTS, XSS protections, CORS and CSP.

  • cors: The CORS configuration.

The Automate REST API is designed to be accessed both by the webpage hosted on the Scheduler server, as well as from third-party services and web pages. For this reason, the default CORS configuration allows all origins. This configuration is secure, as each request to the REST API needs to be authenticated with a Bearer token. If there is a need to further restrict the CORS allowed origins, a stricter policy can be put in place by editing the default CORS settings in the config.yml file.

Sample CORS policy restricting the allowed origins:

  cors:
    allowedOrigins: ["https://scheduler.example.com"]

  • logging: Indicates the parameters of the logging performed by the service. These logs will also contain the information that is typically logged by Nuix Workstation. The location of the worker logs is specified in the nuixFlags parameter.

  • applicationStore: Indicates that a custom database is used for storing the audit information.

    • driverClass: net.sourceforge.jtds.jdbc.Driver

    • user: The database username

    • password: The database password

    • url: The JDBC connection string, for example jdbc:jtds:sqlserver://HOST:1433/DATABASE

    • properties: The connection properties.

Sample Microsoft SQL configuration:

applicationStore:
  driverClass: net.sourceforge.jtds.jdbc.Driver
  user: automate-service
  password: SecretGoesHere
  url: jdbc:jtds:sqlserver://localhost:1433/automate
  properties:
    charSet: UTF-8
If a username and password is not provided in the Microsoft SQL store configuration, the connection will be performed using Integrated Windows Authentication. When connecting to Microsoft SQL in this way, the Automate Scheduler service should be configured to run under an account that has access to the Microsoft SQL database.

  • utilizationStore: Indicates that a custom database is used for storing the operational utilization data.

  • loggingStore : Indicates that a custom database is used for storing logs.

The loggingStore is a circular buffer of all platform logs and is expected to generate a write throughput. It is not recommended to redirect this logging store to a SQL database.

Sample configuration relocating the loggingStore to D:\Logs\Automate:

loggingStore:
  driverClass: org.sqlite.JDBC
  url: jdbc:sqlite:D:/Logs/Automate/logging.db
  properties:
    charSet: UTF-8
The various stores listed above can be all redirected to a single Microsoft SQL database, or to separate databases as needed.

  • defaultUserSettings: Overwrite the user settings that apply when no specific configuration was set on a user profile.

Sample settings to define the allowed parameter values which are populated by default when creating a new Client or a new Matter:

defaultUserSettings:
  newMatter:
    allowedParameterValues:
      - "{custodian}": ["John Smith","Annie Rosella"]
      - "{sample_parameter_1}": []
    synchronizeJobs: true
  newClient:
    allowedParameterValues:
      - "{doc_id_prefix}": ["DOC","DOC-","DOCID"]
      - "{sample_parameter_2}": []

  • sortAllowedParametersValues: true or false indicating if the Allowed Parameter values defined in the user interface or returned by scripts should be sorted and or if they should maintain the original order.

  • jobMaximumExecutionParametersLength: The number of characters that execution parameters can have before the value gets trimmed. This only affects the performance of the front-end of scheduler. By default, this is set to 200 characters.

  • archivedJobCleanupEnabled: true or false indicating if the archive job cleaner should run or not, which deletes job, job execution logs and job operation mime type stats after an archived job is older than a set amount of days. By default, the value is false.

  • archivedJobCleanupInterval: The interval in hours for how often the job cleanup task should run. By default, this is set to 24 hours.

  • archivedJobRetentionDays: Number of days a job must be archived before it is eligible for deletion. By default, this is set to 584 days (1 year and a half).

  • synchronizeJobsOnAllMatters: true or false indicating if only one Job is allowed to run on a Matter at any given time.

  • authTokenTtl: The duration in seconds after which the user authentication token expires. The browser will make a request to refresh the authentication token at half of the token life span. By default, this is set to 600 seconds.

  • disableAuthTokenExpiration: true or false indicating that the user authentication token does not expire. By default, this is set to false.

  • expiredAuthTokenTombstone: The duration in seconds for which to keep track of expired authentication tokens. When attempting to access Automate with an expired authentication token, a friendly error message is be returned, and the current live user session is invalidated. By default, this is set to 900.

  • downgradeWebWorkerToken: true or false indicating that the browser should downgrade the Web Worker token to make it accessible by scripts in the browser. By default, this is set to false.

With the default setting of downgradeWebWorkerToken: false, when refreshing the browser window, the user will be logged out. Setting this option to true will maintain the user session when the browser window is refreshed, but makes the authentication token accessible by scripts in the browser, which is less secure.

  • enforceSingleUserSession: true or false indicating if a user can have more than one session at a time, if this option is set to true only one session will be allowed.

If a user is already signed in and another session is started for the same user, the older session will be signed out.

  • libraryFileMaxSize: The maximum size in bytes of files that can be uploaded to the File Library, by default 10000000.

The File Library is designed to store configuration files and profiles. This limit does not apply to files uploaded to Data Repositories.

  • expireIdleUploadAfter: The duration in milliseconds after which idle uploads to Data Repositories expire, by default 3600000 corresponding to 1 hour.

  • uploadBufferMaxSize: The maximum buffer size in KiB to allocate during uploads to Data Repositories, by default 8192. The buffer size can be allocated up to 3 times for each file upload, and is used only for the duration of the file upload.

When writing data to a file share connected over a high-latency network, increasing the size of the uploadBufferMaxSize may increase overall transfer performance at the cost of increased memory usage.

  • uploadHashAlgorithms: The algorithm to use for hashing on the server-side when uploading files to Data Repositories, by default MD5. To disable hashing during upload, use the value None.

Hashing files during upload requires significant CPU resources on the Scheduler server. To offload this computation to a different server, use the Scheduler Proxy role.

  • enableUtilizationEndpoint: Enable the OData service on Scheduler, by default true. To disable use the value false.

  • utilizationErrorsSoftFail: Mask utilization data database write errors to the application, by default false.

  • azureLocations: (Optional) The list of locations to run VMs in. Sample azureLocations settings:

azureLocations: westus,eastus

  • azureVmSizes: (Optional) The list of VM sizes. Sample azureVmSizes settings:

azureVmSizes: Standard_M8ms,Standard_M16ms,Standard_M32ts

3.1.2. Scheduler Service Environmental Variables

The following environmental variables can be configured to set or overwrite settings configured in the Scheduler Service configuration file:

  • Database redirection. Use the following settings to redirect the application to a SQL database:

    • AUTOMATE_STORE_APPLICATION_ENABLED: Set to true to enable

    • AUTOMATE_STORE_APPLICATION_DRIVER_CLASS: The driver class, for example org.postgresql.Driver

    • AUTOMATE_STORE_APPLICATION_URL: The JDBC connection string, for example jdbc:postgresql://postgres.example.internal:5432/automateScheduler

    • AUTOMATE_STORE_APPLICATION_USERNAME: The database username

    • AUTOMATE_STORE_APPLICATION_PASSWORD: The database password

    • AUTOMATE_STORE_APPLICATION_CHARSET: The database charset, for example UTF-8

    • AUTOMATE_STORE_LOGGING_REDIRECT_TO_APPLICATION: Set to true to redirect the centralized logging to the same location as the application store

    • AUTOMATE_CENTRALIZED_LOGGING_ENABLED: Set to false to disabled centralized logging

    • AUTOMATE_STORE_UTILIZATION_REDIRECT_TO_APPLICATION: Set to true to redirect the utilization data to the same location as the application store

    • AUTOMATE_STORE_APPLICATION_SCHEDULER_MIN_CONNECTIONS: The minimum number of connections to keep open

    • AUTOMATE_STORE_APPLICATION_SCHEDULER_MAX_CONNECTIONS: The maximum number of connections to keep open

  • Authentication. Use the following settings to configure the access credentials to log in to the application for the initial configuration:

    • Internal username/password authentication:

      • AUTOMATE_AUTH_INTERNAL_ENABLED: Set to true to enable

      • AUTOMATE_AUTH_INTERNAL_USERNAME: The username to log in with

      • AUTOMATE_AUTH_INTERNAL_EMAIL: The email address of the user

      • AUTOMATE_AUTH_INTERNAL_PASSWORD: The password to log in with.

    • Internal PBKDF2 authentication:

      • AUTOMATE_AUTH_INTERNAL_ENABLED: Set to true to enable

      • AUTOMATE_AUTH_INTERNAL_USERNAME: The username to log in with

      • AUTOMATE_AUTH_INTERNAL_EMAIL: The email address of the user

      • AUTOMATE_AUTH_INTERNAL_SALT: A base64 encoded string

      • AUTOMATE_AUTH_INTERNAL_ITERATIONS: The number of hash iterations

      • AUTOMATE_AUTH_INTERNAL_HASH: The password hash computed using the PBKDF2WithHmacSHA512 algorithm with a key length of 512 bits.

    • OIDC authentication:

      • AUTOMATE_AUTH_OIDC_ENABLED: Set to true to enable

      • AUTOMATE_AUTH_OIDC_NAME: The authentication mechanism name

      • AUTOMATE_AUTH_OIDC_DESCRIPTION: The authentication mechanism description

      • AUTOMATE_AUTH_OIDC_WELL_KNOWN_CONFIG_URI: The well-known configuration URI, for example http://keycloak:8080/realms/default/.well-known/openid-configuration

      • AUTOMATE_AUTH_OIDC_SCOPE: The scope, for example openid email profile

      • AUTOMATE_AUTH_OIDC_USERNAME_CLAIM: The username claim, for example email

      • AUTOMATE_AUTH_OIDC_CLIENT_ID: The client ID

      • AUTOMATE_AUTH_OIDC_CLIENT_SECRET: The client secret

    • Derby Control service:

      • AUTOMATE_DERBY_CONTROL_SERVICE_ENABLED: Set to true to enable

      • AUTOMATE_DERBY_CONTROL_SERVICE_NAME: The Derby Control service name

      • AUTOMATE_DERBY_CONTROL_SERVICE_DESCRIPTION: The Derby Control service description

      • AUTOMATE_DERBY_CONTROL_SERVICE_URL: The Derby Control base URL, for example http://127.0.0.1:8999/DERBY-CONTROL

  • Multi-server API Secret. Use the following settings to configure the API secret used for managing different Engine Servers:

    • AUTOMATE_API_SECRET: Key used for the authentication between Automate components. Set the same random value on all Automate Scheduler, Proxy and Server instances.

  • Security Policy. Use the following settings to configure a Security Policy:

    • AUTOMATE_SECURITY_POLICY_ENABLED: Set to true to enable

    • AUTOMATE_SECURITY_POLICY_NAME: The policy name

    • AUTOMATE_SECURITY_POLICY_DESCRIPTION: The policy description

    • AUTOMATE_SECURITY_POLICY_PRINCIPALS: The list of principals to which the policy applies. The following setting will match any authenticated user: [{"identifierType":"BUILTIN","identifierName":"AUTHENTICATED_USER"}]

    • AUTOMATE_SECURITY_POLICY_PERMISSIONS: The policy permissions, for example ["VIEW","VIEW_SENSITIVE","MODIFY","CREATE","SUBMIT_JOB","DOWNLOAD_LOGS"]

    • AUTOMATE_SECURITY_POLICY_SCOPE_BUILTIN: The policy built-in scopes, for example ["ALL_CLIENT_POOLS","ALL_CLIENTS","ALL_LIBRARIES","API_KEYS","COLLECTIONS","LEGAL_HOLDS","SCRIPTS","SCHEDULES","SECURITY","RESOURCES"]

    • AUTOMATE_SECURITY_POLICY_SCOPE: Optionally, define the full policy scopes, for example [{"identifierType":"BUILTIN","identifierName":"RESOURCES"}]

  • Security Policy. Use the following settings to configure a Automate License:

    • AUTOMATE_LICENSE_ENABLED: Set to true to enable

    • AUTOMATE_LICENSE_ID: The license ID

    • AUTOMATE_LICENSE_KEY: The license key

    • AUTOMATE_LICENSE_DIAGNOSTIC_LEVEL: The diagnostic level, for example ENHANCED

  • Nuix CLS License. Use the following settings to configure a Nuix CLS License:

    • AUTOMATE_NUIX_CLS_LICENSE_ENABLED: Set to true to enable

    • AUTOMATE_NUIX_CLS_LICENSE_NAME: The license name

    • AUTOMATE_NUIX_CLS_LICENSE_DESCRIPTION: The license description

    • AUTOMATE_NUIX_CLS_LICENSE_FILTER: The license worker filter, for example workstation

    • AUTOMATE_NUIX_CLS_LICENSE_DESCRIPTION: The license description

    • AUTOMATE_NUIX_CLS_LICENSE_USERNAME: The CLS username

    • AUTOMATE_NUIX_CLS_LICENSE_PASSWORD: The CLS password

  • Resource Pool. Use the following settings to configure a Resource Pool:

    • AUTOMATE_RESOURCE_POOL_ENABLED: Set to true to enable

    • AUTOMATE_RESOURCE_POOL_NAME: The resource pool name

    • AUTOMATE_RESOURCE_POOL_DESCRIPTION: The resource pool description

    • AUTOMATE_RESOURCE_POOL_AUTO_REGISTRATION_ENABLED: Set to true to enable auto-registration.

    • AUTOMATE_RESOURCE_POOL_AUTO_REGISTRATION_ACCESS_KEY: The auto-registration access key. The Engine Servers need to use the same key.

    • AUTOMATE_RESOURCE_POOL_AUTO_REGISTRATION_STRICT_IP: Optional, set to true to enforce registration from the same IP address as the destination server, by default false.

    • AUTOMATE_RESOURCE_POOL_AUTO_REGISTRATION_MIN_WORKERS: Optional, the auto-registration min workers, by default 1.

    • AUTOMATE_RESOURCE_POOL_AUTO_REGISTRATION_TARGET_WORKERS: Optional, the auto-registration target workers, by default 2.

    • AUTOMATE_RESOURCE_POOL_AUTO_REGISTRATION_EXECUTION_MODE: Optional, the auto-registration execution mode, by default AUTOMATE_NUIX.

  • Execution Profile. Use the following settings to configure a Execution Profile:

    • AUTOMATE_EXECUTION_PROFILE_ENABLED: Set to true to enable

    • AUTOMATE_EXECUTION_PROFILE_NAME: The execution profile name

    • AUTOMATE_EXECUTION_PROFILE_DESCRIPTION: The execution profile description

    • AUTOMATE_EXECUTION_PROFILE_ENGINE_COMMAND_LINE_PARAMS: Optional, the Engine command-line parameters, by default -Xmx16g -Dnuix.logdir=/var/log/nuix/automate -Duser.language=en -Duser.country=US.

    • AUTOMATE_EXECUTION_PROFILE_NUIX_ENGINE_FOLDER: Optional, the Nuix engine binaries folder, by default /opt/nuix/engine.

    • AUTOMATE_EXECUTION_PROFILE_ENGINE_LOG_FOLDER: Optional, the Engine log folder, by default /var/log/nuix/automate.

    • AUTOMATE_EXECUTION_PROFILE_JAVA_FOLDER: Optional, the Java binaries folder, by default blank.

    • AUTOMATE_EXECUTION_PROFILE_PARAMETERS: Optional, a JSON serialized Map<String,String> of parameter and values, by default blank.

    • AUTOMATE_EXECUTION_JOB_PROGRESS_MIN_PERCENTAGE: Optional, the minium job progress before aborting the job, by default 1.0.

    • AUTOMATE_EXECUTION_JOB_PROGRESS_TIMEOUT_HOURS: Optional, the timeout after which to abort the job if the job progress was not achieved, by default 48.0.

    • AUTOMATE_EXECUTION_OPERATION_PROGRESS_MIN_PERCENTAGE: Optional, the minimum operation progress before aborting the job, by default 1.0.

    • AUTOMATE_EXECUTION_OPERATION_PROGRESS_TIMEOUT_HOURS: Optional, the timeout after which to abort the job if the operation progress was not achieved, by default 24.0.

    • AUTOMATE_EXECUTION_SKIP_OPERATION_PROGRESS_MIN_PERCENTAGE: Optional, the minium operation progress before attempting to skip the operation, by default 1.0.

    • AUTOMATE_EXECUTION_SKIP_OPERATION_PROGRESS_TIMEOUT_HOURS: Optional, the timeout after which to attempt to skip the operation of the operation progress was not achieved, by default 12.0.

  • User Data Dir. Use the following settings to configure the User Data Dir behavior:

    • AUTOMATE_USER_DATA_DIR_SCAN_INTERVAL: Set to the interval duration in seconds at which the User Data Dir will be scanned even if the OS does not detect a change.

  • To overwrite an arbitrary setting, convert the setting name to uppercase snake case, preceded by Automate. For example, for configuring the downgradeWebWorkerToken setting, use the AUTOMATE_DOWNGRADE_WEB_WORKER_TOKEN environmental variable.

3.1.3. Scheduler Proxy Service Settings

This file follows the YAML Syntax and contain the following parameters:

  • role: PROXY, indicating that the Automate Scheduler Proxy component will run;

  • apiSecret: Key used for the authentication between Automate components. Set the same random value on all Automate Scheduler, Proxy and Server instances.

  • proxy: The details of the main Scheduler instance that the proxy uses. The configuration is provided in the following subkeys:

    • baseUrl: The URL of the Scheduler instance.

    • whitelistedCertFingerprints: Scheduler certificate fingerprints used for verification when opening a secure connection.

  • allowedAuthenticationServices: The list of authentication service names that can be used through this Proxy. If this setting is not defined, all authentication services will be allowed through the Proxy.

Sample proxy configuration:

proxy:
  baseUrl: https://scheduler.automate.local
  whitelistedCertFingerprints:
    - e62dd01ca608c10402d07714cfd626bfc6b1001e5a16ca039d1050a71f73ee24

allowedAuthenticationServices:
  - Internal
  - Lab Azure AD

  • log4jConfigurationFile: The log4j configuration file.

  • server: Indicates the web access logs settings, the HTTP protocols to listen on and the corresponding IP, port and TLS certificate for HTTPS connections.

  • webConfiguration: Indicates which Web settings to apply to the Web server used for the REST API.

3.1.4. Engine Server Service Settings

This file follows the YAML Syntax and contain the following parameters:

  • role: ENGINE_SERVER, indicating that the Automate Engine Server component will run;

  • apiSecret: Key used for the authentication between Automate components. Set the same random value on all Automate Scheduler, Proxy and Server instances.

  • nuixEnginePath: The location of the Nuix Engine deployment. This folder should contain bin, lib, and user-data subfolders directly.

  • log4jConfigurationFile: The log4j configuration file.

  • engineInitLogFolder: The temporary location used by Engines for storing configuration files and logs during the initialization phase. When running Jobs, the Engine will store the logs and configuration files at the location specified in the Execution Profile.

  • engineInitTimeout: The timeout in seconds that the Engine is allowed to initialize, by default 120.

  • engineAbortTimeout: The timeout in milliseconds that the Engine will wait to abort a job, be default 5000 (5 seconds)

  • server: Indicates the web access logs settings, the HTTP protocols to listen on and the corresponding IP, port and TLS certificate for HTTPS connections.

  • webConfiguration: Indicates which Web settings to apply to the Web server used for the REST API.

  • jobRunningLogMaxSize: Indicates the maximum number of logs that the job running log stores, by default 20.

  • logging: Indicates the parameters of the logging performed by the service. These logs will also contain the information that is typically logged by Nuix Workstation. The location of the worker logs is specified in the nuixFlags parameter.

  • workerBrokerIP: The IP address to use for hosting Worker Brokers when running Remote Workers.

  • workerBrokerStartPort: The port range start for Worker Brokers.

  • workerBrokerEndPort: The port range end for Worker Brokers.

Sample settings for configuring a Worker Broker on IP 10.0.0.1:

workerBrokerIP: 10.0.0.1
workerBrokerStartPort: 50000
workerBrokerEndPort: 50100
If the workerBrokerIP setting is not provided, the server will start a broker on a default network adapter. In an environment where servers have multiple network adapters, configure the workerBrokerIP on each server with the IP address that should be used by other servers joing remote jobs to contact this server.

3.1.5. Engine Server Service Environmental Variables

The following environmental variables can be configured to set or overwrite settings configured in the Engine Server Service configuration file:

  • Database redirection. Use the following settings to redirect the application to a SQL database:

    • AUTOMATE_STORE_APPLICATION_ENABLED: Set to true to enable

    • AUTOMATE_STORE_APPLICATION_DRIVER_CLASS: The driver class, for example org.postgresql.Driver

    • AUTOMATE_STORE_APPLICATION_URL: The JDBC connection string, for example jdbc:postgresql://postgres.example.internal:5432/automateEngineServer

    • AUTOMATE_STORE_APPLICATION_USERNAME: The database username

    • AUTOMATE_STORE_APPLICATION_PASSWORD: The database password

    • AUTOMATE_STORE_APPLICATION_CHARSET: The database charset, for example UTF-8

    • AUTOMATE_STORE_APPLICATION_SCHEDULER_MIN_CONNECTIONS: The minimum number of connections to keep open

    • AUTOMATE_STORE_APPLICATION_SCHEDULER_MAX_CONNECTIONS: The maximum number of connections to keep open

  • Auto-registration. Use the following settings to automatically register the Engine Server to a Scheduler Resource Pool. The Resource Pool must be configured with the auto-registration feature enabled:

    • AUTOMATE_REGISTRATION_ENABLED: Set to true to enable

    • AUTOMATE_REGISTRATION_SERVER_NAME: The name of the Engine Server, for example Server1

    • AUTOMATE_REGISTRATION_SERVER_URL: The URL that the Scheduler can access the Engine Server as, for example http://Server1.internal.local

    • AUTOMATE_REGISTRATION_SCHEDULER_URL: The Scheduler URL, for example http://Scheduler.internal.local

    • AUTOMATE_REGISTRATION_RESOURCE_POOL_ID: Optional, the Resource Pool ID to register with. By default, the ID of the Resource Pool configured in Scheduler with ENV variables. This setting only needs to be provided to register to a different Resource Pool.

    • AUTOMATE_REGISTRATION_ROLE_MAIN: Optional, set to true enable the Engine to act as a Main Engine in the Resouce Pool.

    • AUTOMATE_REGISTRATION_ROLE_REMOTE: Optional, set to true enable the Engine to act as a Remote Engine in the Resouce Pool.

    • AUTOMATE_REGISTRATION_RESOURCE_POOL_ACCESS_KEY: The Resource Pool access key. Se the same value the was configured on the Resource pool with the ENV variable.

  • Multi-server deployment. Use the following settings for multi-server deployment scenarios:

    • AUTOMATE_API_SECRET: Key used for the authentication between Automate components. Set the same random value on all Automate Scheduler, Proxy and Server instances.

    • AUTOMATE_SERVER_ID: Set a unique random ID for each Engine Server.

  • Engine logging layout

    • AUTOMATE_ENGINE_LOG_LAYOUT_JSON: Set to true to configure the Engine logs to be in JSON format. Note, this does not apply to the Scheduler or Engine Server log formats, which are configured directly in their respective config.yml.

3.1.6. OData Server Service Settings

This file follows the YAML Syntax and contain the following parameters:

  • role: ODATA_SERVER, indicating that the Automate OData Server component will run;

  • internalCredentials: Indicates that credentials defined in the configuration file will be used for authentication. The configuration is provided in the following subkeys:

    • displayName: (Optional) The name to display in the login page for this authentication method.

    • restrictToLocalhost: (Optional) Restrict the availability of the Internal authentication to browsers from localhost. If this property is not specified, it defaults to false.

    • credentials: The list of credentials.

The credentials can be provided in either PBKDF2 format, using:

  • username

  • email

  • salt, a base64 encoded string

  • iterations, the number of hash iterations

  • hash, computed using the PBKDF2WithHmacSHA512 algorithm with a key length of 512 bits.

or in cleartext, using:

  • username

  • email

  • password

Sample Internal authentication configuration with 2 users:

internalCredentials:
  displayName: UsernamePassword
  restrictToLocalhost: true
  credentials:
    - username: user1
      email: user1@example.com
      salt: NlbCqq8kL6sqdZQrjMmgSw==
      iterations: 1000000
      hash: ca4xiopDRshgyKvArOfKqBoDeVfbsOpayzVrh8n1WAWOhqvunITolqBBTiSAn1VxTBUz+15IfX4qxiTuHrthuA==

    - username: user2
      email: user2@example.com
      password: Password2@
The Internal authentication method requires storing the usernames and passwords or hashes in the configuration file. It’s recommended to restrict this method to localhost.
Set the restrictToLocalhost property to true to only allow logging in with internal credentials when accessing Automate as localhost.

  • server: Indicates the web access logs settings, the HTTP protocols to listen on and the corresponding IP, port and TLS certificate for HTTPS connections.

By default, the service listens on HTTP on port 8081 on localhost, and on HTTPS on port 8443 all IP addresses. To restrict the server to listen on a specific IP address, change 0.0.0.0 to the required IP address in the config.yml file.

  • webConfiguration: Indicates which Web settings to apply to the Web server used for the REST API.

  • utilizationStore: Indicates that a custom database is used for storing the audit information.

    • driverClass: net.sourceforge.jtds.jdbc.Driver

    • user: The database username

    • password: The database password

    • url: The JDBC connection string, for example jdbc:jtds:sqlserver://HOST:1433/DATABASE

    • properties: The connection properties.

Sample Microsoft SQL configuration:

utilizationStore:
  driverClass: net.sourceforge.jtds.jdbc.Driver
  user: automate-service
  password: SecretGoesHere
  url: jdbc:jtds:sqlserver://localhost:1433/automate
  properties:
    charSet: UTF-8
If a username and password is not provided in the Microsoft SQL store configuration, the connection will be performed using Integrated Windows Authentication. When connecting to Microsoft SQL in this way, the Automate Scheduler service should be configured to run under an account that has access to the Microsoft SQL database.

3.2. Authentication

3.2.1. Nuix UMS

If using the Nuix UMS authentication method, configure the UMS Authentication Service in the Automate web page, in the Settings tab, under Authentication Services. All users which are defined in the Nuix UMS will be able to log in to Automate. The access level of each user is determined by the security policies defined in the Automate web page, in the Settings tab.

3.2.2. LDAP

If using the LDAP authentication method, configure the LDAP Authentication Service in the Automate web page, in the Settings tab, under Authentication Services. All users which are defined in the provided LDAP domainDN will be able to log in to Automate. The access level of each user is determined by the security policies defined in the Automate web page, in the Settings tab.

3.2.3. Internal

If using the Internal authentication method, set the internalCredentials configuration in the YAML file as indicated in Service Settings.

3.3. Access Security Policies

Access to Automate resources is defined in the Settings page, in the Security Policies tab. The default policy allows any authenticated user to View and Modify all resources, as well as to Submit Jobs with any settings.

3.4. Memory

3.4.1. Nuix Workers

The memory of Nuix Workers can be specified either in the workflow Configuration operation, or explicitly as a command-line parameter in the Execution Profiles, for example:

-Dnuix.worker.jvm.arguments="-Xmx8g"

3.4.2. Nuix Engine

The memory of the Nuix Engine, equivalent to the memory of the Nuix Workstation as a command-line parameter in the Execution Profiles, for example:

-Xmx2g
Each Nuix Engine will run under a separate JVM and will not share memory with the other Nuix Engines or the Automate services.

3.5. Shared Data Sources

Automate workflows are executed on the servers running the Automate Engine Server component. To ensure that workflows can access cases and source data from a shared location, provide a UNC path or a mapped drive letter path which is accessible from all servers running the Automate Engine Server component.

By default, the Automate Engine Server service runs under the Local System account, and starts Engines under the same user account.

A different user account can be specified in Execution Profiles, as required.

4. Troubleshooting

4.1. Browse to Automate Scheduler

By default, Automate Scheduler listens on 127.0.0.1 on port 80 and all IP addresses on port 443. To access the default installation, browse to address: http://localhost

4.2. Automate Service Does Not Start

Automate Scheduler and Engine Server run as Windows services. If the services are started, inspect the log files at C:\Temp\Log\automate-scheduler.log and C:\Temp\Log\automate-engine-server.log.

4.3. Log In Error

If the error Error communicating with the authentication server is shown when attempting to log in, inspect the logs to determine the issue encountered by Automate when communicating with the authentication server.

4.4. Adding Automate Engine Server throws javax.net.ssl.SSLHandshakeException error

Ensure that the Java Runtime Environment from the latest version of Nuix Workstation deployed on each the Automate Scheduler server trusts the TLS certificate of the Automate Engine Server. See section Managing Certificates for more details.

5. Managing Certificates

See https://nuix.service-now.com/support?id=kb_article_view&sys_kb_id=fcd9bfe747cc96102d9c89cbd36d438f.

6. Utilization and Reporting

The Utilization and Reporting data is provided as an OData V4 feed, if this feature is enabled in the Automate license.

The OData feed only support querying the metadata and retrieving all data from the views. OData filters are not supported.

The OData feed can be accessed under the following endpoint, using Basic or Microsoft OAuth authentication:

  • /api/v2/reporting/odata

7. REST API documentation

Automate Scheduler can be accessed either directly for a browser, or using the REST API. The documentation of the API is provided in OpenAPI v3 format, under /openapi.

For example, to access the API documentation in a standard installation of Automate Scheduler, browse to http://localhost/openapi

8. Centralized Logging

Centralized logging consolidates all of the logs from Scheduler, Engine Server, Engine and Worker logs into the logging database managed by Scheduler.

Centralized logging is enabled by default, meaning that both the log file as well as the database log will exist. To disable centralized logging, set the enableCentralizedLogging key to false in the configuration YAML file as indicated in Service Settings file.

If centralized logging is disabled, the download job logs and download system logs features will be disabled.

Centralized logging will automatically delete logs older than the retention period. The default retention period is 30 days. To change the retention period, edit the centralizedLoggingRetention key in YAML file.

When the database logs size exceeds the maximum database size, older logs will be deleted. By default the maximum database size is 1000000000 bytes (1 GB). To change the default max database size edit the centralizedLoggingMaxSize key in the YAML file.

The actual centralized logging database size could exceed the specified maximum size, due to database overhead and delays in deleting old log lines.

9. Filepaths Inventory

9.1. Default Filepaths

9.1.1. Scheduler

  • C:\Program Files\Nuix\Automate: Installation folder

  • %programdata%\Nuix\Automate\Scheduler\config: Configuration folder

  • %programdata%\Nuix\Automate\Scheduler\stores: Persistence and archival of job details, utilization, audit, reporting and utilization

  • C:\Temp\logs\automate-scheduler.log: Application log

  • C:\Temp\logs\automate-scheduler.%d.log.zip: Previous application log files

  • C:\Temp\logs\automate-scheduler-access.log: Web access log

  • C:\Temp\logs\automate-scheduler-access.%d.log.zip: Previous main log files

  • C:\Temp\logs\Automate Scheduler.wrapper.log: Service wrapper logs

  • C:\Temp\logs\Automate Scheduler.err.log: Service standard error log

  • C:\Temp\logs\Automate Scheduler.out.log: Service standard output log

9.1.2. Engine Server

  • C:\Program Files\Nuix\Automate: Installation folder

  • %programdata%\Nuix\Automate\EngineServer\config: Configuration folder

  • C:\Temp\logs\automate-engine-server.log: Application log

  • C:\Temp\logs\automate-engine-server.%d.log.zip: Previous application log files

  • C:\Temp\logs\automate-engine-server-access.log: Web access log

  • C:\Temp\logs\automate-engine-server-access.%d.log.zip: Previous main log files

  • C:\Temp\logs\Automate Engine Server.wrapper.log: Service wrapper logs

  • C:\Temp\logs\Automate Engine Server.err.log: Service standard error log

  • C:\Temp\logs\Automate Engine Server.out.log: Service standard output log

9.1.3. Engine

  • C:\Temp\logs\automate-engine.aaaaaaaa-init.log: Init log

  • C:\Temp\logs\automate-engine.aaaaaaaa-init.yml: Init configuration

  • C:\Temp\logs\automate-engine.aaaaaaaa-service.exe: Service wrapper

  • C:\Temp\logs\automate-engine.aaaaaaaa-service.xml: Service configuration

  • C:\Temp\logs\automate-engine.aaaaaaaa-job.bbbbbbbb.log: Job log

  • C:\Temp\logs\automate-engine.aaaaaaaa-job.bbbbbbbb.yml: Job configuration

9.2. Changing Log Locations

The default filepaths can be changed from the following locations:

  • Scheduler main log: Update the section logging from C:\ProgramData\Nuix\Automate\Scheduler\config\config.yml

  • Scheduler service-related logs: Update the tags <workingdirectory> and <logpath> from C:\Program Files\Nuix\Automate\Scheduler\Automate Scheduler.xml

  • Engine Server main log: Update the section logging from C:\ProgramData\Nuix\Automate\EngineServer\config\config.yml

  • Engine Server service-related logs: Update the tags <workingdirectory> and <logpath> from C:\Program Files\Nuix\Automate\EngineServer\Automate Engine Server.xml

  • Engine init log, configuration and service-related logs: Update the section engineInitLogFolder from C:\ProgramData\Nuix\Automate\EngineServer\config\config.yml

  • Job log and configuration: Update the field Log Folder and set the command-line parameter -Dnuix.logdir=c:\Temp\Logs in the Execution Profile