GET/ managements

In Guardian, one is able to define a hierarchy which represents the organizational structure of a company, allowing management responsibilities to be distributed among regional managers, branch managers, human resources specialists, etc—in fact, a company’s hierarchy can be defined to any level of specificity required for a given organization.

A management enables additional user permissions by extending user scope. Specifically, defining a management associates a set of employees with a user, allowing him or her to view and modify the employees’ cases. A management scope is defined by first creating a group, and then associating the manager’s user account with that group.

Requesting GET /v1/managements returns a list containing the associations between each user and the employees within their organizational level. The groups which can be assigned are restricted only by the structure of a Company’s hierarchy.

Although this API call returns a list, management groups logically describe a tree structure, mirroring the organization of the company. A group is identified by a unique path from the root of the hierarchy to the desired node. Multiple managements can exist for the same group node, differing only by the assigned manager.

Note: Although the meaning of a company hierarchy is defined by the organization during the provisioning process, there is a limitation that the hierarchy must be no more than 5 levels deep. This 5 level maximum excludes the root level, which exists for every company.
An organization may define levels for: locations, legal entities, and custom fields. These must be defined in Guardian before using them in a group or a management.

In the response of a call to GET /v1/managements, each entry defines a user’s relationship to a defined employee group. The group is represented by an array of attribute values (the array of attribute values is equivalent to the node path described above). The attribute values are listed in hierarchical order; the first element in the list is the first level of the hierarchy below the company node in the tree, and subsequent elements traverse the tree from top to bottom. The more attributes defined in the group parameter, the lower in the hierarchy/smaller the employee population.

When the group parameter is [] (an explicit empty list, not null), the associated user is assigned to the entire company (root node) and has access to all employees.

Results are unordered, and should be processed individually. Results can be narrowed by including filters with the request. Optional root, group and userId filter parameters can be included in the request to retrieve management records for the specified group level and/or user. The options root and group are mutually exclusive.

Method

GET

Resource Information

Requires authentication?	YES
Response formats	JSON

Parameters

Parameter	Required	Description
id	No	The ID of the managements relationship of the user to a specific employee group
root	No	Utilize root=true to return the management assigned to the entire company; note that this will not additionally return child group nodes
group	No	The ordered list (i.e. hierarchical order or node path) of integer and/or string attributes that identify the employee group within the hierarchy for which to return employee group assignment results. Location and Legal Entity hierarchical attributes are defined by integer value (ID) while Custom Field hierarchical attributes are defined by string
userId	No	The ID of the user for whom to return employee group assignments

Example

Request Example
GET https://<server>/v1/managements
Response Example

{
 ""searchResult"": [
 { ""userId"": 34434,
 ""group"": [
 27546,
 894,
 ""custom 10""
 ],
 ""id"": 1206
 },
 { ""userId"": 34434,
 ""group"": [
 27550
 ],
 ""id"": 560
 },
 {
 ""userId"": 34434,
 ""group"": [
 27549
 ],
 ""id"": 559
 },
 {
 ""userId"": 34434,
 ""group"": [
 27548
 ],
 ""id"": 558
 },
 {
 ""userId"": 34434,
 ""group"": [
 27547
 ],
 ""id"": 557
 }
 ]
}

Single Record Request Example

GET https://<server>/v1/managements/<management_id>

Single Record Response Example

{
 ""userId"": 34434,
 ""group"": [
 27546,
 894,
 ""custom 10""
 ],
 ""id"": 1206
}

Additional Examples
Request: GET https://<server>/v1/managements?root=true
Response:


{
 ""userId"": 34433,
 ""group"": [
 ],
 ""id"": 1563
}

Request: GET https://<server>/v1/managements?group=<level_1_id>
Response:


{
 ""userId"": 34434,
 ""group"": [
 27547
 ],
 ""id"": 557
}

Request: GET https://<server>/v1/managements?group=<level_1_id>?group=<level_2_id>
Response:


{
 ""userId"": 34434,
 ""group"": [
 27546,
 894,
 ],
 ""id"": 1206
}

Request: GET https://<server>/v1/managements?userId=<userId>
Response:


{
 ""userId"": 34434,
 ""group"": [
 27546,
 894,
 ""custom 10""
 ],
 ""id"": 1206
},
{
 ""userId"": 34434,
 ""group"": [
 27550
 ],
 ""id"": 560
},
{
 ""userId"": 34434,
 ""group"": [
 27549
 ],
 ""id"": 559
},
{
 ""userId"": 34434,
 ""group"": [
 27548
 ],
 ""id"": 558
},
{
 ""userId"": 34434,
 ""group"": [
 27547
 ],
 ""id"": 557
}

Request: GET https://<server>/v1/managements?userId=<userId>&group=<level_1_id>
Response:


{
 ""userId"": 34434,
 ""group"": [
 27547
 ],
 ""id"": 557
}