Configure Security | Administrate

This page details the specific configuration and input options for the Configure ACL Orchestrator.

This guidance should be read in conjunction with the Common Configuration page which details the standard application configuration.

Purpose

The key purpose for this Orchestrator is to carry out updates to the Access Control Lists and Default Security across Workspaces, Folders and Documents in iManage.

Operation Name

ConfigureSecurity

Common Configuration

There is common configuration available within this job Orchestrator. The common configuration options can be found here.

Input Data Schema

Data can be read via SQL or CSV and requires the following data headers and values:

CSV

Headers	Description	Mandatory	Expected Value
`Id`	This is the row ID	Yes	Numeric value
`TargetObjectType`	This specifies the type of iManage object being targeted. i.e. a Workspace	Yes	Either: `Workspace` `Folder` `Document`
`TargetLibraryId`	The ID of the iManage Library	Yes	iManage Library identifier i.e. `Active`
`TargetObjectId`	Allows you to target a specify a target (workspace, folder or document) Id	No (unless TargetObjectSearchQuery is blank). Takes priority over the search query	iManage identifier i.e. `Active!1234`
`TargetObjectSearchQuery`	A JSON object which contains a dictionary matching any applicable profile parameters for the corresponding `TargetObjectType` Multiple parameters can be used in the search query	No (unless TargetObjectId is blank)	JSON format i.e. `{"custom1": "*", "custom2": "test"}` if using csv input then escaped values need to be used for multiple parameter queries. The following keys can be provided: `custom1-30` `parentFolderId` `name`
`DefaultSecurity`	The default security to apply to the target	No	Either: `public` `private` `view` `inherit` (only applies to folders)
`UserList`	A list of Users for the update	No (unless `GroupList` is blank)	Pipe delimited list of user IDs: `user1\|user 2\|user3`
`GroupList`	A list of User Groups for the update	No (unless `UserList` is blank)	Pipe delimited list of group IDs: `group1\|group 2\|group3`
`Action`	Specifies the type of action to apply to the row	Yes	Either: `Update` `Remove`
`AccessLevel`	Specifies the Access Level to be applied	Yes (if Action = Update)	Either: `Deny` `Read` `ReadWrite` `Full`
`Processed`	Indicates if the row has been processed	No	'0'

SQL

SQL Input uses the same values as the CSV input above. The SQL Schema is detailed below:

SQL

CREATE TABLE ConfigureSecurityInput (
  Id INT IDENTITY(1,1) PRIMARY KEY,
  Processed BIT,
  TargetLibraryId VARCHAR(25) NOT NULL,
  TargetObjectType VARCHAR(25) NOT NULL,
  TargetObjectId VARCHAR(25),
  TargetObjectSearchQuery NVARCHAR(MAX),
  DefaultSecurity VARCHAR(25),
  UserList NVARCHAR(MAX),
  GroupList NVARCHAR(MAX),
  [Action] VARCHAR(25),
  AccessLevel VARCHAR(25)
);

Job File Options

This section details the configurable options within the orchestrator.

Configuration	Description	Expected Value
`IsEnabled`	Sets whether the update process is enabled or disabled	`true` `false`
`ActionMultipleQueryResults`	If enabled then the application will process all results returned by the search query. When disabled then the application will only process the request if one search result is identified	`true` `false`
`ApplyRecursively`	When enabled on the job file, then the same action is applied for all nested objects (i.e. all nested folders and documents where applicable). If enabled this will apply updates to documents and folders regardless of their ‘inherit’ status	`true` `false`
`ExcludeFoldersSetToInherit`	If enabled then any Folders set to `inherit` status will be excluded from any Default Security updates. If disabled then Folders will lose their `inherit` status when processing any updates.	`true` `false`

Output Events

These output events are specific to the Configure ACL Orchestrator and work in addition to the common output events detailed in Common Configuration

The following output events can be persisted via the ‘Subscribed To’ configuration

Target	Action	Status	Full Event Identifier
`Workspace`	`Object Query`	`Success` `Failed`	`workspace:objectquery:success workspace:objectquery:failed`
`Workspace`	`Update`	`Success` `Failed` `Skipped`	`workspace:update:success workspace:update:failed workspace:update:skipped`
`Workspace`	`Remove`	`Success` `Failed` `Skipped`	`workspace:remove:success workspace:remove:failed workspace:remove:skipped`
`Folder`	`Object Query`	`Success` `Failed`	`folder:objectquery:success folder:objectquery:failed`
`Folder`	`Update`	`Success` `Failed` `Skipped`	`folder:update:success folder:update:failed folder:update:skipped`
`Folder`	`Remove`	`Success` `Failed` `Skipped`	`folder:remove:success folder:remove:failed folder:remove:skipped`
`Document`	`Object Query`	`Success` `Failed`	`document:objectquery:success document:objectquery:failed`
`Document`	`Update`	`Success` `Failed` `Skipped`	`document:update:success document:update:failed document:update:skipped`
`Document`	`Remove`	`Success` `Failed` `Skipped`	`document:remove:success document:remove:failed document:remove:skipped`

These should be listed in the Orchestrator in the following format ‘Target:Action:Status’.

The event output schema is shown below:

SQL

CREATE TABLE ConfigureSecurityOutput (
  Id INT IDENTITY(1,1) PRIMARY KEY,
  EventTime DATETIMEOFFSET NOT NULL,
  CorrelationId VARCHAR(36) NOT NULL,
  [Action] VARCHAR(30),
  Status VARCHAR(25) NOT NULL,
  Message NVARCHAR(MAX) NOT NULL,
  DataSourceRowId VARCHAR(25),
  TargetObjectType VARCHAR(25) NOT NULL,
  TargetObjectId VARCHAR(25),
  AccessLevel VARCHAR(25),
  [Users] NVARCHAR(MAX),
  [Groups] NVARCHAR(MAX),
  DefaultSecurity NVARCHAR(25),
  AclUpdates NVARCHAR(MAX),
  Workspace NVARCHAR(500),
  Folder NVARCHAR(500),
  Document NVARCHAR(500),
  ParentWorkspaces NVARCHAR(MAX),
  TargetSearchQuery NVARCHAR(MAX), /* JSON object containing the search query */
  TargetSearchQueryResultCount INT,
  TargetSearchQueryResultList NVARCHAR(MAX)
);

Sample Job File

This is an example Job File for the ConfigureACL Orchestrator:

JSON

{
  "Operation": "ConfigureSecurity",
  "Options": {
    "ActionMultipleQueryResults": false,
    "ApplyRecursively": {
      "Enabled": false,
      "ExcludeFoldersSetToInherit": true
    }
  },
  "InputType": "CSV",
  "Inputs": {
    "CSV": {
      "Path": "<repo>\\source\\WorkspaceAutomate\\Test Files\\Csvs\\ConfigureSecurity.csv"
    }
  },
  "Outputs": {
    "Console": {
      "Enabled": true,
      "SubscribedTo": [ "*" ]
    }
  },
  "Integrations": {
    "IManage": {
      "URL": "<url>",
      "Username": "<username>",
      "Password": "<password>"
    }
  }
}

Failure and Skip Behaviour

This Orchestrator follows the standard behaviour for failed/skipped records:

Skipped = Scenarios configured to not be processed for a specific reason e.g. ExcludeFoldersSetToInherit: true would mark any folders with an Inherit status found as part of the processing of the operation as skipped.

Failed = Administrate tried to perform an action on the target object and an unexpected error occurred. e.g. iManage connection dropped and Administrate was unable to update a document that was configured to be updated.

iManage Behaviour

This section details the different behaviour across different versions of iManage i.e. On-Prem, iManage Cloud and Cloud iManage.

There are no differences for this operation between On-Prem and Cloud iManage.