Configure User Workspace Shortcuts

This page details the specific configuration and input options for the Configure User Workspace Shortcuts Orchestrator.

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

Purpose

This Orchestrator allow you to configure Workspace Shortcuts for individual users and/or user groups. This will assist you set up key shortcuts for new team members or update existing active matters.

Operation Name

ConfigureUserWorkspaceShortcuts

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
`TargetLibraryId`	The ID of the iManage Library	Yes	iManage Library identifier i.e. ‘Active’
`TargetObjectId`	Allows you to target a specific workspace via its 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 workspace Multiple parameters can be used in the search query	No	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` `name`
`UserList`	A list of Users for the update	No (unless `GroupList` is blank)	`\|` delimited list of user IDs for example: `user1\|user 2\|user3`
`GroupList`	A list of User Groups for the update	No (unless `UserList` is blank)	`\|` delimited list of group IDs for example: `group1\|group 2\|group3`
`Action`	Specifies the type of action to apply to the row	Yes	Either: `Add` `Replace` `Remove` `Purge`
`CategoryPath`	Specifies the category path to be used/created so that the workspace can be assigned a category. If any element of the path doesn’t currently exist then it will be created	No (unless `MustBeCreatedInCategories` is set to `true` and the action is`add` or `replace`. Can be left blank if action is `remove` or `purge`	`/` delimited path of category names for the shortcut. For example: `Category A/Second Level Category/Lowest Level Category` There should not be any spaces after the `/` delimiter
`IncludeMyMatters`	Add the shortcut to My Matters	No (unless `IncludeMyFavourites`is blank)	`true` `false`
`IncludeMyFavourites`	Add the shortcut to My Favourites Not currently supported for Cloud iManage	No (unless `IncludeMyMatters`is blank)	`true` `false`
`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 ConfigureUserWorkspaceShortcutsInput (
  Id INT IDENTITY(1,1) PRIMARY KEY,
  Processed BIT NOT NULL,
  TargetLibraryId NVARCHAR(MAX) NOT NULL,
  TargetObjectId NVARCHAR(MAX) NULL,
  TargetObjectSearchQuery NVARCHAR(MAX) NULL,
  UserList NVARCHAR(MAX) NULL,
  GroupList NVARCHAR(MAX) NULL,
  [Action] VARCHAR(50) NULL,
  CategoryPath NVARCHAR(MAX) NULL,
  IncludeMyMatters BIT NULL,
  IncludeMyFavourites BIT NULL,
);

Job File Options

This section details the configurable options within the orchestrator.

Configuration	Description	Expected Value
`Enabled`	Sets whether the update process is enabled or disabled	`true` `false`
`MustBeCreatedInCategories`	Forces iManage categories to be used in shortcut creation	`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`

Output Events

These output events are specific to the Configure User Workspace Shortcuts Orchestrator and works 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`
`User`	`Add`	`Success` `Failed` `Skipped`	`user:add:success user:add:failed user:add:skipped`
`User`	`Remove`	`Success` `Failed` `Skipped`	`user:remove:success user:remove:failed user:remove:skipped`
`User`	`Replace`	`Success` `Failed` `Skipped`	`user:replace:success user:replace:failed user:replace:skipped`
`User`	`Purge`	`Success` `Failed` `Skipped`	`user:purge:success user:purge:failed user:purge: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 ConfigureUserWorkspaceShortcutsOutput(
	Id INT IDENTITY(1,1) PRIMARY KEY,
	EventTime DATETIMEOFFSET NOT NULL,
	CorrelationId VARCHAR(36) NOT NULL,
	[Action] VARCHAR(30) NOT NULL,
	[Status] VARCHAR(25) NOT NULL,
	[Message] NVARCHAR(MAX) NOT NULL,
	DataSourceRowId VARCHAR(25),
	TargetObjectType VARCHAR(25) NOT NULL,
	TargetObjectId VARCHAR(25),
	[Identity] [nvarchar](max) NULL,
	[Shortcuts] [nvarchar](max) NULL,
	[TargetSearchQuery] [nvarchar](max) NULL,
	[TargetSearchQueryResultCount] [int] NULL,
	[TargetSearchQueryResultList] [nvarchar](max) NULL
)

Sample Job File

This is an example Job File for the ConfigureUserWorkspaceShortcuts Orchestrator:

JSON

{
  "Operation": "ConfigureUserWorkspaceShortcuts",
  "Options": {
    "Enabled": true,
    "MustBeCreatedInCategories": false,
    "ActionMultipleQueryResults": false
  },
  "InputType": "CSV",
  "Inputs": {
    "CSV": {
      "Path": "<repo>\\source\\WorkspaceAutomate\\Test Files\\Csvs\\ConfigureUserWorkspaceShortcuts.csv"
    }
  },
  "Outputs": {
    "Console": {
      "Enabled": true,
      "SubscribedTo": ["Target:Action:Status"]
    }
  },
  "Integrations": {
    "IManage": {
      "URL": "<url>",
      "Username": "<username>",
      "Password": "<password>",
      "ImpersonationPassword": "<password>" //Required for On-Prem operations//
    }
  }
}

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. IncludeMyFavourites: true for iManage cloud would mark the input 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 add a shortcut.

iManage Behaviour

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

Due to limitations in the iManage API, managing users' ‘My Favourites’ is not available for Cloud iManage. Only ‘My Matters’ operations are available.

To manage user shortcuts for On-Prem, an impersonation password in the job file is required. Without an impersonation password, operations for On-Prem instances are likely to error.