uip ah categories, tags, collaborators, roles, users

Syntax and options for the Automation Hub category taxonomy, free-text tags, per-automation collaborators, the assignable role catalogue, and user accounts.

Categories are a hierarchical taxonomy automations are placed in; tags are free-text labels. Collaborators are the people working on one automation, each holding one or more roles — Automation Hub's assignable-role catalogue is also how uip ah users create grants tenant-wide access. See uip ah for shared concepts (projection/--all-fields, paged vs. unpaged lists) that apply to every verb here.

uip ah categories

Read the category hierarchy and place automations in it.

Synopsis

uip ah categories get [--all-fields]
uip ah categories update --file <json-file> [-y, --yes]
uip ah categories set <automation-id> --category-id <id>

uip ah categories get

Get the category hierarchy as one tree, with its level names. get, not list: the endpoint returns one nested document, not a paged collection — there's no --limit/--offset.

Options

Long	Description
--all-fields	Return the raw payload instead of Levels/Categories.

Example

uip ah categories get

Data shape (--output json)

{
  "Code": "AhCategoriesGet",
  "Data": { "Levels": [{ "Id": 1, "Name": "Business Unit" }], "Categories": [{ "Id": 4, "Name": "Finance" }] }
}

uip ah categories update

Replace the whole category tree from a file. Automation Hub has no per-category create/delete — the tree is synced as one document.

Options

Long	Value	Required	Description
--file <json-file>	path	yes	JSON with the full category tree to sync, in the shape categories get returns.
-y, --yes	flag	yes	Confirm this replaces the entire tenant category tree. Required — the CLI never prompts.

An empty or clearly-malformed file is rejected client-side before the request is sent.

Example

uip ah categories update --file ./categories.json --yes

Data shape (--output json)

{ "Code": "AhCategoriesUpdate", "Data": { "Status": "Synced" } }

uip ah categories set

Assign one automation to a category.

Arguments

Name	Required	Purpose
<automation-id>	yes	Automation id.

Options

Long	Value	Required	Description
--category-id <id>	integer	yes	Category id to assign.

Example

uip ah categories set 20 --category-id 4

Data shape (--output json)

{ "Code": "AhCategoriesSet", "Data": { "AutomationId": 20, "CategoryId": 4 } }

uip ah tags

Set the tags on an automation.

uip ah tags set

Replace an automation's tags with the given set — this replaces the whole tag list rather than merging (matching uip config set's replace semantics).

Arguments

Name	Required	Purpose
<automation-id>	yes	Automation id.

Options

Long	Value	Required	Description
--tags <tag...>	repeatable	yes	The complete tag set for this automation.

Example

uip ah tags set 20 --tags finance "quick win"

Data shape (--output json)

{ "Code": "AhTagsSet", "Data": { "AutomationId": 20, "Tags": ["finance", "quick win"] } }

uip ah collaborators

Manage who collaborates on an automation. Its own resource group rather than a verb on automations, so the standard CRUD verbs stay available for it.

Synopsis

uip ah collaborators list --automation-id <id> [--limit <n>] [--offset <n>] [--all-fields]
uip ah collaborators create <automation-id> --user-id <id...> --role-id <id...>
uip ah collaborators delete <automation-id> --user-id <id...> --role-id <id...> [-y, --yes]

uip ah collaborators list

Options

Long	Value	Required	Description
--automation-id <id>	integer	yes	Automation to read (a query parameter on this endpoint, not a positional).
--limit <n> / --offset <n>	integer	no	Paging, applied client-side (unpaged endpoint).
--all-fields	flag	no	Return the raw payload.

Example

uip ah collaborators list --automation-id 20

Data shape (--output json)

{
  "Code": "AhCollaboratorsList",
  "Data": [
    { "Id": 1, "Email": "[e-mail]", "FirstName": "Jane", "LastName": "Doe", "JobTitle": "Analyst", "Department": "Finance", "BusinessUnit": "EMEA", "IsActive": 1 }
  ]
}

uip ah collaborators create

Add collaborators to an automation.

Arguments

Name	Required	Purpose
<automation-id>	yes	Automation id.

Options

Long	Value	Required	Description
--user-id <id...>	repeatable	yes	User ids to add.
--role-id <id...>	repeatable	yes	Role ids to grant every added user (applied to all of them — a per-user role split needs one call per user). Only active roles of type process are accepted; the endpoint rejects any other kind.

At least one --role-id is required — the endpoint rejects a collaborator entry with no role.

Example

uip ah collaborators create 20 --user-id 3 --role-id 3

Data shape (--output json)

{ "Code": "AhCollaboratorsCreate", "Data": { "AutomationId": 20, "UserIds": [3] } }

uip ah collaborators delete

Remove collaborator roles from users on an automation. The endpoint deletes role assignments rather than the collaborator record, so --role-id is required — strip every role a user holds and they stop being a collaborator.

Arguments

Name	Required	Purpose
<automation-id>	yes	Automation id.

Options

Long	Value	Required	Description
--user-id <id...>	repeatable	yes	User ids to remove roles from.
--role-id <id...>	repeatable	yes	Role ids to remove from each user.
-y, --yes	flag	yes	Confirm this irreversible operation. Required — the CLI never prompts.

Example

uip ah collaborators delete 20 --user-id 3 --role-id 3 --yes

Data shape (--output json)

{ "Code": "AhCollaboratorsDelete", "Data": { "AutomationId": 20, "UserIds": [3], "RoleIds": [3] } }

uip ah roles

Discover the Automation Hub roles that can be assigned. Read-only.

uip ah roles list

Options

Long	Description
--limit <n> / --offset <n>	Paging, applied client-side (unpaged endpoint).
--all-fields	Return the raw payload.

Example

uip ah roles list

Data shape (--output json)

{
  "Code": "AhRolesList",
  "Data": [
    { "Id": 2, "Name": "System Admin", "Slug": "ah-system-admin", "Type": "service", "Description": "...", "IsActive": 1, "IsDefault": 0 }
  ]
}

Slug is the value uip ah users create --role takes; Id/Type are what collaborators create --role-id filters on (only Type: "process" roles are accepted there).

uip ah users

Manage Automation Hub users and their roles.

Synopsis

uip ah users list [--search <text>] [--sort-by <field>] [--sort-order asc|desc] [--department <name>] [--business-unit <name>] [--location <name>] [--job-title <title>] [--invite-status <status>] [--role <slug>] [--limit <n>] [--offset <n>] [--all-fields]
uip ah users create --email <email> [write options...] --role-id <id...>
uip ah users update --email <email> [write options...]

uip ah users list

Options

Long	Value	Description
--search <text>	string	Free-text search.
--sort-by <field>	string	Field to sort on, e.g. user_email.
--sort-order <direction>	asc|desc	Sort direction.
--department <name> / --business-unit <name> / --location <name> / --job-title <title>	string	Scope filters.
--invite-status <status>	string	Only this invite status.
--role <slug>	string	Only users holding this role slug.
--limit <n> / --offset <n>	integer	Paging. Default --limit 20.
--all-fields	flag	Return the raw payload.

Example

uip ah users list --department Finance --limit 20

Data shape (--output json)

{
  "Code": "AhUsersList",
  "Data": [
    { "Id": 3, "Email": "[e-mail]", "FirstName": "Jane", "LastName": "Doe", "JobTitle": "Analyst", "Department": "Finance", "BusinessUnit": "EMEA", "Location": "Boston", "IsAdmin": 0, "IsActive": 1, "InviteStatus": 2, "AutomationCount": 3 }
  ],
  "Pagination": { "Returned": 1, "Limit": 20, "Offset": 0 }
}

uip ah users create

Add an existing Automation Cloud user to Automation Hub. This imports a user who is already in the organization — it cannot invite a new one, and fails with an explicit instructional error if the address is unknown to Automation Cloud.

Options

Long	Value	Required	Description
--email <email>	email	yes	User email address.
--first-name <name> / --last-name <name>	string	conditionally	Required by the service on write (see below).
--job-title <title> / --department <name> / --business-unit <name> / --location <name>	string	conditionally	Required by the service on write.
--invite-status <status>	integer	no	Numeric Automation Hub invite-status code. Default 2 on create.
--active	flag	no	Mark the user active. Default on create. Conflicts with --inactive.
--inactive	flag	no	Mark the user inactive. Conflicts with --active.
--role-id <id...>	repeatable	no	Role ids to assign (uip ah roles list for the ids).

Automation Hub requires nine fields to carry a value on every write (email, first-name, last-name, business-unit, department, location, job-title, invite-status, active/inactive) — on create, none has a stored fallback, so any omitted field fails client-side naming exactly which flags to pass.

Example

uip ah users create --email [e-mail] --first-name Jane --last-name Doe \
  --job-title Analyst --department Finance --business-unit EMEA --location Boston --role-id 3

Data shape (--output json)

{ "Code": "AhUsersCreate", "Data": { "Email": "[e-mail]", "Status": "Created" } }

uip ah users update

Update a user, found by --email. Automation Hub replaces the whole user record on write, so fields you don't pass are carried over from the stored record — except that the service still rejects the write if any of the nine required fields is empty on both the flag and the stored record.

Options

Same flags as create, but only --email is required — the rest fill gaps from the existing record.

Example

uip ah users update --email [e-mail] --job-title 'Senior Analyst'

Data shape (--output json)

{ "Code": "AhUsersUpdate", "Data": { "Email": "[e-mail]", "Status": "Updated" } }

Related

• uip ah — overview, concepts, audit-logs, auth-info.
• Automations, idea-flows, business-cases, phases, questionnaires, pipelines
• Applications, components, documents, media, store-listings, store-reviews

See also

• Tools (plugins)
• Global options
• Exit codes