Roles

Introduction

Roles connect users to a primary department, module permissions, extended department access, and optional additional attributes.

Model Definition

Alias

role

Relations

Key	Relation	Type	Relation Field(s)
department	Department	Belongs to	department_id
departments	Departments	Belongs to many	department_role
infoboardDepartments	Departments	Belongs to many	infoboard_department_role
quickTaskAssignmentsDepartments	Departments	Belongs to many	quick_task_assignments_department_role
permissions	Permissions	Belongs to many	permission_role
users	Users	Has many	role_id
folder	Folder	Belongs to	folder_id
attributeSets	AttributeSets	Morph to many	Target entity type and ID

List

List visible Roles.

Definition

GET /api/roles

Request Keys

Key	Type	Default	Description
selects	string	All fields	Comma-separated fields to return.
relations	string	Default relations	Pipe-separated relations to include.
limit	integer	No limit	Maximum number of roles.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/roles', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

[
  {
    "id": 14,
    "name": "Engineering member",
    "active": true,
    "user_id": 7,
    "department_id": 6,
    "folder_id": 12,
    "location_key": "berlin",
    "sort_number": 1
  },
  {
    "id": 15,
    "name": "Product lead",
    "active": false,
    "user_id": 8,
    "department_id": 9,
    "folder_id": null,
    "location_key": "remote",
    "sort_number": 2
  }
]

Show

Show one visible Role.

Definition

GET /api/roles/{role}

Route Parameters

Parameter	Type	Description
role	integer	Role ID.

Request Keys

Key	Type	Default	Description
selects	string	All fields	Comma-separated fields to return.
relations	string	Default relations	Pipe-separated relations to include.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/roles/14', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

{
  "id": 14,
  "name": "Engineering member",
  "active": true,
  "user_id": 7,
  "department_id": 6,
  "folder_id": 12,
  "location_key": "berlin",
  "sort_number": 1
}

Availability Information

Show availability information for Roles.

Definition

GET /api/roles/availability-information

Request Keys

Key	Type	Default	Description
department_ids	array or comma-separated integers	All departments	Departments for which availability is calculated.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/roles/availability-information', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'query' => [
        'department_ids' => [6, 9]
    ]
]);

Example Response

{
  "available_per_department": 5,
  "departments": [
    {
      "department_id": 6,
      "available": 3,
      "used": 2
    },
    {
      "department_id": 9,
      "available": 4,
      "used": 1
    }
  ]
}

Create

Create a new Role.

Definition

POST /api/roles

Request Keys

Key	Type	Default	Description
name*	string	-	Unique role name.
department_id*	integer	-	Primary Department ID.
active	boolean	true	Whether users may use the role.
folder_id	integer | null	null	Parent Folder ID.
location_key	string | null	null	Optional location identifier.
sort_number	integer	Auto	Order within the folder.
permission_ids	array	No permissions	Permission IDs granted through the role.
department_ids	array	Primary department	Departments whose content the role may access.
infoboard_department_ids	array	Primary department	Departments available for Infoboard targeting.
quick_task_assignments_department_ids	array	Primary department	Departments available for quick task assignments.
attribute_set_ids	array	Current or no sets	AttributeSets to attach.
Additional attribute keys	mixed	Defined by set	Values for attached AttributeFields.

Keys with * are required for creation.

Behavior

The authenticated user becomes user_id. The example supplies every relationship collection and additional-attribute value used to configure the new role.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/roles', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'name' => 'Customer Success lead',
        'department_id' => 6,
        'active' => true,
        'folder_id' => 12,
        'location_key' => 'berlin',
        'sort_number' => 3,
        'permission_ids' => [18, 24],
        'department_ids' => [6, 9],
        'infoboard_department_ids' => [6, 9],
        'quick_task_assignments_department_ids' => [6],
        'attribute_set_ids' => [[
            'id' => 32,
            'sort_number' => 1
        ]],
        'approval-limit' => 25000
    ]
]);

Example Response

{
  "status": "success",
  "data": {
    "id": 16,
    "name": "Customer Success lead",
    "active": true,
    "user_id": 7,
    "department_id": 6,
    "folder_id": 12,
    "location_key": "berlin",
    "sort_number": 3
  }
}

Update

Update an existing Role.

Definition

PUT /api/roles/{role}

Route Parameters

Parameter	Type	Description
role	integer	Role ID.

Request Keys

Key	Type	Default	Description
name*	string	-	Unique role name.
department_id*	integer	-	Primary Department ID.
active	boolean	true	Whether users may use the role.
folder_id	integer | null	null	Parent Folder ID.
location_key	string | null	null	Optional location identifier.
sort_number	integer	Auto	Order within the folder.
permission_ids	array	No permissions	Permission IDs granted through the role.
department_ids	array	Primary department	Departments whose content the role may access.
infoboard_department_ids	array	Primary department	Departments available for Infoboard targeting.
quick_task_assignments_department_ids	array	Primary department	Departments available for quick task assignments.
attribute_set_ids	array	Current or no sets	AttributeSets to attach.
Additional attribute keys	mixed	Defined by set	Values for attached AttributeFields.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/roles/16', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'name' => 'Customer Experience lead',
        'active' => true,
        'department_id' => 9,
        'permission_ids' => [18, 24, 27],
        'department_ids' => [6, 9],
        'infoboard_department_ids' => [9],
        'quick_task_assignments_department_ids' => [6, 9],
        'attribute_set_ids' => [[
            'id' => 32,
            'sort_number' => 1
        ]],
        'approval-limit' => 30000
    ]
]);

Example Response

{
  "status": "success",
  "data": {
    "id": 16,
    "name": "Customer Experience lead",
    "active": true,
    "user_id": 7,
    "department_id": 9,
    "folder_id": 12,
    "location_key": "berlin",
    "sort_number": 3
  }
}

Delete

Delete an existing Role.

Definition

DELETE /api/roles/{role}

Route Parameters

Parameter	Type	Description
role	integer	Role ID.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('DELETE', '/api/roles/16', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

{
  "status": "success",
  "data": null
}