Common Configuration | Administrate

This page details the standard configuration options available across all Orchestrators.

Orchestrator Operation

This section details the common configurations and input parameters share across all Orchestrators.

Options

This section provides Orchestrator specific configuration. See the Features section of this user guide for further details on each Orchestrator.

Input Data Schema

Administrate can take inputs from two sources, CSV and SQL. Each input has different connection requirements and behaviours as detailed below:

CSV

CSV input requires a file ‘Path’ to be provided in the Orchestrator Configuration.

CSV inputs require a Processed indicator to be set to ‘0'. Once Administrate has processed the input csv it will generate a new csv with a timestamp included in the file name and the Processed indicator set to '1'

SQL

SQL input requires the following:

Connection String - this is mandatory
Table - this is mandatory
Schema - this is optional

Sql inputs require a Processed indicator to be set to ‘0'. Once Administrate has processed the record it will update it with the Processed indicator set to '1'.

Common Input Considerations

Across Administrate there are standard processing behaviours to be aware of:

Custom Values with Parental Ownership

Within iManage Custom1 and Custom29 are parent values. Custom2 and Custom30 are inherently child values of Custom1 and Custom29, respectively.

When using Search Queries, by default you will need to specify a Custom1 and Custom29 value when also searching by Custom2 and Custom30 values. This is to ensure appropriate targeting of specific workspaces is maintained and avoid unintended widespread changes to the iManage DMS.

You can bypass this restriction by using a wildcard value * in the parent value.

Date Range Searches

When using the ObjectSearchQuery across the Orchestrators, you can provide iManage custom field values as the search criteria. If you are searching a custom field with a Date type then you will need to pass it a date range. For example:

{"custom23from": "2022-06-19T00:00:00.000Z", "custom23to": "2022-06-21T23:59:59.999Z"}

Configuration

Configuration is specific to each Orchestrator as details under the Orchestrators section.

If any required configuration options are missing from the processing Orchestrator, Administrate will default to the least destructive option, for example if you do not set a true or false value for the Enabled flag on the Purge Workspace Orchestrator then it will be defaulted to false

Integrations

Administrate works solely with iManage and requires the following configuration inputs:

Configuration	Description	Mandatory	Example Value
`URL`	This is the iManage URL	Yes	https://cloudimanage.com
`Username`	This is the Username of the account being used by Administrate (usually a service account)	Yes	ServiceAccount1
`Password`	The password associated to the above account	Yes	n/a
`ClientId`	Unique Client Id for the Administrate application installed in iManage	Yes	UUID value for example: `a7b9c2d4-e5f6-4g8h-9i0j-k1l2m3n4o5p6`
`ClientSecret`	Unique Client Secret for the Administrate application installed in iManage	Yes	UUID value for example: `a7b9c2d4-e5f6-4g8h-9i0j-k1l2m3n4o5p6`
`ImpersonationPassword`	This is required for On-Prem iManage	No	Password123

Outputs

Administrate supports several output options with various input requirements. Outputs can be configured at a feature level as each Orchestrator will have output events specific to the data it is processing. There are standard output events available across all Orchestrators:

Target	Action	Status	Full Event Identifier
`Application`	`Launch`	`Success` `Failed` `Skipped`	`application:launch:success` `application:launch:failed` `application:launch:skipped`
`Application`	`QueryLicence`	`Success` `Failed` `Skipped`	`application:querylicence:success` `application:querylicence:failed` `application:querylicence:skipped`
`Application`	`ConfirmLatestVersion`	`Success` `Failed` `Skipped`	`application:confirmlatestversion:success` `application:confirmlatestversion:failed` `application:confirmlatestversion:skipped`

These should be listed in the Orchestrator in the following format ‘Target:Action:Status’. All of these options will accept wildcards which can enable you to subscribe to all events for example ["*"] or ["application:*:*"] or ["*:*:success"]. Orchestrators will also accept an empty array [] which will subscribe to all available events.

Output Methods

The following output methods are available across all Orchestrators.

Multiple events of each type can be created for all outputs except the console. This allows you to configure specific outputs to different audiences for example:

An email output to your IT support desk for any processing failures
An email output to your business group for successful processing

This is actioned via the Handlers option shown in the example job file schemas below

Console

This will output the events to the Command Console window and has the following configurations:

Configuration

Description

Mandatory

Expected Value

Enabled

This can enable or disable the output feature.

True/ False

Default value: False

SubscribedTo

This is a customisable list of events that will be tracked in the output. The available events are specific to each Orchestrator.

An array of strings in the format Target:Action:Status

Default value: Subscribe to all available events

Note that unlike all other output methods, there can only be a single console output configured.

Sample Job File Schema

JSON

  "Outputs": {
    "Console": {
      "Enabled": true,
      "SubscribedTo": [
        "*:*:*"
      ]

CSV

This will output the events to a csv file and has the following configurations:

Configuration	Description	Mandatory	Expected Value
`Enabled`	This can enable or disable the output feature.	No	`True`/ `False` Default value: `False`
`Path`	The file path for the csv report to be saved to. Available as a default value.	Yes	A string.
`FileNameTemplate`	The file name template for the csv.	No	A string. Variables can be used. See table below for all available variables. Default value: `Administrate_Report_<DATETIME>`
`SubscribedTo`	This is a customisable list of events that will be tracked in the output. The available events are specific to each Orchestrator.	No	An array of strings in the format `Target:Action:Status` Default value: Subscribe to all available events

The following variables can be used in FileNameTemplate for the csv output. Variables should be encased within < > and are case-insensitive.

Variable	Description
`Date`	The date of the run execution, in local-host-time, in the `d` format (short date pattern) for the execution locale
`DateTime`	The date time of the run execution, in local-host-time, in the `g` format (short date time pattern) for the execution locale
`JobId`	The correlation identifier for the job that’s running

Sample Job File Schema

JSON

    "CSV": {
      "Defaults": {
        "Path": "<path>"
      },
      "Handlers": [
        {
          "Enabled": false,
          "Path": "<path>",
          "FileNameTemplate": "Administrate_Report_<DATETIME>",
          "SubscribedTo": [ "*:*:*" ]
        }
      ]

Email

This will output the events via email and has the following configurations:

Configuration	Description	Mandatory	Expected Value
`Enabled`	This can enable or disable the output feature.	No	`True`/ `False` Default value: `False`
`Host`	This is the hosting service you utilise for emails. Available as a default value.	Yes	A string
`Port`	References the specific port to be used for the host service. Available as a default value.	Yes	Numeric value
`RequiresAuthentication`	Specify whether the mail server requires authentication.	No	`True`/ `False` Default value: `False`
`Credentials`	Available as a default value.	Yes if `RequiresAuthentication` is `True`, otherwise no
`UseDefault`	When enabled this uses the current users Windows configuration for connection	No	`True`/ `False` Default value: `True`
`Username`	The username of the email account being used	Yes, when `Credentials` are specified	A string
`Password`	The password of the email account being used	Yes, when `Credentials` are specified	A string
`SSL`	Can be enabled for when SSL is required. Available as a default value.	No	`True`/ `False` Default value: `False`
`FromAddress`	Specify the senders email address to use. Available as a default value.	Yes	A string
`ToAddresses`	Specify the recipients of the email.	Yes	An array of strings i.e. `["test1@email.com", "test2@email.com"]`
`BatchResults`	If enabled, will batch up all notifications to the end of the run.	No	`True`/ `False` Default value: `True`
`SubjectTemplate`	Specify the template text to use for the email subject.	No	A string. Variables can be used. See table below for all available variables. Default value: If `BatchResult` is true: `Administrate Batch Update - {{JobId}}` If `BatchResult` is false: `Administrate {{OperationName}} {{Status}} - {{TargetType}} {{Action}}`
`BodyTemplateFile`	The absolute/relative path to the template to use for event email body. If relative, it's relative to the executable location.	No	A string
`SubscribedTo`	This is a customisable list of events that will be tracked in the output. The available events are specific to each Orchestrator.	No	An array of strings in the format `Target:Action:Status` Default value: Subscribe to all available events

The following variables can be used in the SubjectTemplate and the body template file for the email output. Variables should be encased within {{ }} and are case-insensitive.

Variable	Description
`Machine`	The name of the machine the executable is running on.
`Date`	The date of the run execution, in local-host-time, in the `d` format (short date pattern) for the execution locale
`Time`	The time of the run execution, local-host-time, in the `t` format (short time pattern) for the execution locale
`DateTime`	The date time of the run execution, in local-host-time, in the `g` format (short date time pattern) for the execution locale
`OperationFriendlyName`	A user friendly name of the orchestrator being executed (space between words, correct punctuation, no abbreviations)
`OperationName`	The name of the orchestrator, as provided in the job file.
`JobId`	The correlation identifier for the job that’s running.
`DataSourceRowId`	The identifier from the input data row
`TargetObjectId`	The identifier of the target entity, if applicable. Only applicable for single-entity events.
`TargetType`	The target type of the event.
`TargetObjectName`	The name of the target entity, if applicable. Only applicable for single-entity events.
`Action`	The action performed (or attempted) on the `target`
`Status`	The status of the action performed (or attempted) on the target.
`EventData_<PropertyName>`	A dynamically retrieved property from the event dynamic data output
`Message`	The message emitted with the event.

Sample Job File Schema

JSON

    "Email": {
      "Defaults": {
        "Host": "smtp.office365.com",
        "Port": 442,
        "Credentials": {
          "UseDefault": false,
          "Username": "",
          "Password": ""
        },
        "SSL": false,
        "FromAddress": ""
      },
      "Handlers": [
        {
          "Enabled": false,
          "Host": "smtp.office365.com",
          "Port": 442,
          "Credentials": {
            "UseDefault": false,
            "Username": "",
            "Password": ""
          },
          "SSL": false,
          "RequiresAuthentication": false,
          "FromAddress": "",
          "ToAddresses": [ "" ],
          "SubscribedTo": [ "*" ],
          "SubjectTemplate": "",
          "BodyTemplateFile": "",
          "BatchResults": true
        }
      ]
    },

SQL

This will output the events to a specified SQL table and has the following configurations:

Configuration	Description	Mandatory	Expected Value
`Enabled`	This can enable or disable the output feature	No	`True` `False` Default value: `False`
`ConnectionString`	This is the SQL connection string. Available as a default value.	Yes	A string.
`Table`	This specifies the table to write the output to	Yes	A string.
`Schema`	This specific the database schema and is an optional configuration	No	A string. Default value: `dbo`
`SubscribedTo`	This is a customisable list of events that will be tracked in the output. The available events are specific to each Orchestrator.	No	An array of strings in the format `Target:Action:Status` Default value: Subscribe to all available events

Sample Job File Schema

JSON

    "SQL": {
      "Defaults": {
        "ConnectionString": "<connstr>"
      },
      "Handlers": [
        {
          "Enabled": false,
          "ConnectionString": "<connstr>",
          "Table": "<table>",
          "Schema": "<schema>",
          "SubscribedTo": [ "*" ]
        }
      ]
    },

Webhook

This will output the events via a webhook and has the following configurations:

Configuration	Description	Mandatory	Expected Value
`Enabled`	This can enable or disable the output feature	No	`True` `False` Default value: `False`
`URL`	The base URL for the webhook	Yes	A string
`Authentication`	Available as a default value.	Yes
`Scheme`	This is the authentication scheme to user for the webhook requests.	No	An empty string, `basic` or `bearer` Default value: empty string
`Username`	The user name for the webhook request.	Yes, when `Scheme` is `basic` or `bearer`.	A string.
`Password`	The password for the webhook request.	Yes, when `Scheme` is `bearer`.	A string.
`Headers`	Headers to add to the webhook request. Available as a default value.	No	An array of name value pairs.
`SubscribedTo`	This is a customisable list of events that will be tracked in the output. The available events are specific to each Orchestrator.	No	An array of strings in the format `Target:Action:Status` Default value: Subscribe to all available events

Sample Job File Schema

JSON

      "Handlers": [
        {
          "Enabled": true,
          "URL": "https://webhook.site/e46d96d0-32cd-448a-9f75-53c2ab201922",
          "SubscribedTo": [ "*" ],
          "Authentication": { // required section.
            "Scheme": "",
            "Username": "",
            "Password": ""
          },
          "Headers": [
            {
              "Name": "X-Header-Name",
              "Value": "Example"
            }
          ]
        }
      ]

Full Job File Schema

This section details the complete list of configuration available within the Administrate Job File schema (excluding any Orchestrator specific config):

JSON

{
  "Operation": "OrchestratorName",
  "InputType": "CSV",
  "Options": {
    "ActionMultipleQueryResults": false,
    "ApplyRecursively": false
  },
  "Inputs": {
    "CSV": {
      "Path": "<path>"
    },
    "SQL": {
      "ConnectionString": "<connstr>",
      "Table": "<table>",
      "Schema": "<schema>"
    }
  },
  "Integrations": {
    "IManage": {
      "URL": "<url>",
      "Username": "<username>",
      "Password": "<password>",
      "ClientId": "<id>",
      "ClientSecret": "<secret>",
      "ImpersonationPassword": "<password>"
    }
  },
  "Outputs": {
    "Console": {
      "Enabled": true,
      "SubscribedTo": [
        "*:*:*"
      ]
    },
    "CSV": {
      "Defaults": {
        "Path": "<path>"
      },
      "Handlers": [
        {
          "Enabled": false,
          "Path": "<path>",
          "FileNameTemplate": "Administrate_Report_<DATETIME>",
          "SubscribedTo": [ "*:*:*" ]
        }
      ]
    },
    "Email": {
      "Defaults": {
        "Host": "smtp.office365.com",
        "Port": 442,
        "Credentials": {
          "UseDefault": false,
          "Username": "",
          "Password": ""
        },
        "SSL": false,
        "FromAddress": ""
      },
      "Handlers": [
        {
          "Enabled": false,
          "Host": "smtp.office365.com",
          "Port": 442,
          "Credentials": {
            "UseDefault": false,
            "Username": "",
            "Password": ""
          },
          "SSL": false,
          "RequiresAuthentication": false,
          "FromAddress": "",
          "ToAddresses": [ "" ],
          "SubscribedTo": [ "*" ],
          "SubjectTemplate": "",
          "BodyTemplateFile": "",
          "BatchResults": true
        }
      ]
    },
    "SQL": {
      "Defaults": {
        "ConnectionString": "<connstr>"
      },
      "Handlers": [
        {
          "Enabled": false,
          "ConnectionString": "<connstr>",
          "Table": "<table>",
          "Schema": "<schema>",
          "SubscribedTo": [ "*" ]
        }
      ]
    },
    "Webhook": {
      "Defaults": {
        "Headers": [],
        "Authentication": { // required section.
          "Scheme": "",
          "Username": "",
          "Password": ""
        }
      },
      "Handlers": [
        {
          "Enabled": true,
          "URL": "https://webhook.site/e49d97d0-32cd-448a-9f75-53c2ab201922",
          "SubscribedTo": [ "*" ],
          "Authentication": { // required section.
            "Scheme": "",
            "Username": "",
            "Password": ""
          },
          "Headers": [
            {
              "Name": "X-Dummy-Header-Name",
              "Value": "Example"
            }
          ]
        }
      ]
    }
  }
}

Logging Configuration

The appsettings.logging.json file controls the configuration for logging in Administrate.

By default, logs are restricted to Information in production. This can be changed without a code change or redeployment by updating restrictedToMinimumLevel to other options such as Verbose or Debug.

Also by default, logging from third-party namespaces such as TigerEye.IManageDmsWrapper and Polly are disabled so as to not clog the logs. If these need adjusting, they can either be removed from the Override section under Serilog, or their log level can similarly be adjusted.