Tags, categories and roles

Tags

Tags come in twelve kinds, one for each kind of record that can be tagged: client, location, contact, credential, asset, vendor, domain, license, service, network, document and ticket. A tag of one kind can't go on another kind of record.

A tag needs the role area of its kind of record - Support for asset tags, Clients for contact tags, and so on. See Keys and permissions.

Records that can be tagged also come with their tags when you read them, as a tags list.

Read

With no kind, the list has every kind the key's agent can read.

{
  "success": "True",
  "count": 1,
  "data": [
    { "tag_id": 8, "tag_name": "Key Account", "tag_description": null, "tag_kind": "client", "tag_type": 1, "tag_color": "#ffc107", "tag_icon": "star", "tag_archived_at": null, "tag_record_ids": [1, 2, 3, 4, 12, 13] }
  ]
}

tag_icon is a Font Awesome icon's name, and tag_type is the kind's number, from 1 for client to 12 for ticket.

Create

Only a key whose agent is an admin can make tags, as in Admin > Tags.

{ "api_key": "YOUR_API_KEY", "kind": "asset", "name": "Imaging", "color": "#0d6efd", "icon": "x-ray" }

Set a record's tags

The agent needs to be able to change that kind of record (Modify). A name that isn't a tag of that kind yet becomes a new tag when the agent is an admin, and is skipped otherwise. An archived tag stays on a record that already has it, but can't be newly added.

The response lists the record's tags afterwards, with what changed in message:

curl -X POST https://itflow.example.com/api/v1/tags/update.php \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_API_KEY", "client_id": 1, "kind": "asset", "record_id": 9, "tags": ["Imaging"], "mode": "add"}'

{
  "success": "True",
  "count": 6,
  "message": "Added tag Imaging",
  "data": [
    { "tag_id": 67, "tag_name": "Backed Up", "tag_kind": "asset", "tag_type": 5, "tag_color": "#001f3f", "tag_icon": "database" },
    { "tag_id": 118, "tag_name": "Imaging", "tag_kind": "asset", "tag_type": 5, "tag_color": "#0d6efd", "tag_icon": "x-ray" }
  ]
}

Categories

The categories in Admin > Categories are read only through the API.

kind can also be the name Admin > Categories shows, such as Asset Status, and capitals don't matter. With no kind, the list has every kind the key's agent can read.

{
  "success": "True",
  "count": 1,
  "data": [
    { "category_id": 6, "category_name": "Software", "category_description": null, "category_type": "Expense", "category_color": "#add8e6", "category_icon": null, "category_order": 0, "category_archived_at": null, "category_used": 51, "category_used_by": { "expenses": 27, "budget": 24 } }
  ]
}

category_used is how many records have the category, archived ones too, and category_used_by breaks that down by kind of record. Both are null for a key whose agent can't see every client.

Fields: category_id, category_name, category_description, category_type, category_color, category_icon, category_order, category_created_at, category_updated_at, category_archived_at, category_used, category_used_by.

Roles

A key whose agent is an admin reads every role. Any other key reads only its own agent's role, so an integration can check what it's allowed to do.

{
  "success": "True",
  "count": 1,
  "data": [
    {
      "role_id": 2,
      "role_name": "Technician",
      "role_description": "Built-in - Limited access to technical-focused modules",
      "role_is_admin": 0,
      "role_levels": { "module_client": 2, "module_support": 2, "module_credential": 2, "module_sales": 2, "module_financial": 0, "module_reporting": 0, "module_ai": 1 },
      "role_agents": 2,
      "role_created_at": "2024-09-03 09:00:00",
      "role_updated_at": null,
      "role_archived_at": null
    }
  ]
}

role_levels gives each area's level: 0 none, 1 Read, 2 Modify and 3 Full. An admin role (role_is_admin 1) can do everything, whatever its levels say. role_agents is how many active agents have the role.