User and Group API

This article provides sample API calls to add Users and Groups and access to Dimensions.

PREREQUISITES:

Table of contents: 

Locating User and Group ID

  1. Access Admin > System > API Toolkit
  2. Configure Users
    1. Fetch Users
    2. Create User
  3. Configure Groups
    1. Fetch Groups
    2. Create Group
  4. Configure User's Group Membership
    1. Display User's Group Membership
    2. Add User to Group
    3. Remove User from the Group
  5. Configure Group Dimension Access
    1. Display Group Dimension Access 
    2. Add Dimension Access to Group (To All Dimension Values)
    3. Add Specific Dimension Value Access to Group
Locating User and Group ID

Find User ID

  1. Access Admin > Users & Groups
  2. Select the User
  3. Copy the User ID from the URL

Find Group ID

  1. Access Admin > Users & Groups
  2. Access the Groups tab
  3. Select the Group
  4. Copy the Group ID from the URL

1. Access Admin > System > API Toolkit

2. Configure Users

2.1. Fetch Users

Fetch Users
  1. Item: user
  2. Methods: GET
  3. Optionally, specify the ID, email, or username of a User, the data of which you want to fetch
  4. Enter an API Token
  5. [Run Request]
  6. The returned object contains an array of objects, each containing User's data.

Example Response 

{
    "users": [
        {
            "id": "118",
            "username": "robert",
            "first_name": "Robert",
            "last_name": "Isaenko",
            "type": "administrator",
            "email": "[email protected]",
            "enabled": "Y",
            "ldap": "N"
        },
        {
            "id": "192",
            "username": "[email protected]",
            "first_name": "robert.isaenko@metricinsights.",
            "last_name": "",
            "type": "regular",
            "email": "[email protected]",
            "enabled": "Y",
            "ldap": "N"
        }
    ]
}

Fields Description

Field Name Value Type Description
id string The ID of the user.
username string The username of the user.
first_name string The first name of the user.
last_name string The last name of the user.
type string The type of the user (regular, power, or administrator).
email string The email of the user.
enabled string Whether or not the user is enabled.
ldap string Whether or not the user is authenticated via LDAP.

2.2. Create User

Create User

This call creates a new user. After this user is created, Login credentials are going to be sent to a specified email address.

  1. Item: user
  2. Methods: POST
  3. ID: Specify the ID of any other User previously created in the system. This User's data is going to serve as a basis for creating a new User
  4. Select Form request and define the following required User info:
    • username, first_name, last_name, email, password
      • NOTE: The email address must be unique for this particular user
    • type: regular, power, or administrator
  5. Optionally, provide the following parameters:
    • copy_from_user_id: Specify the ID of a User from whom you want to copy all permissions.
    • in_group_id: If this value is not specified, the created User is going to be assigned to a default User Group. If you want to assign a new User to a specific Group instead of a Default Group (for example, to the "Finance" group), specify the ID of the required Group in this field.
    • user_preference_template: Provide the ID of the User Preference Template
  6. Enter an API Token
  7. [Run Request]
  8. The returned object contains an array with an object which contains the newly created User's data.

3. Configure Groups

3.1. Fetch Groups

Fetch Groups
  1. Item: user_group
  2. Methods: GET
  3. Optionally, specify the ID of the group the data of which you want to fetch
  4. Enter an API Token
  5. [Run Request]
  6. The returned object contains an array of objects, each containing Group data.

Example Response 

{
    "user_groups": [
        {
            "id": "1",
            "name": "Default Group",
            "description": "Default Group - privileges accessible to all users",
            "all_access_group": "N",
            "ldap_organizational_unit": null,
            "external_group_id": null
        },
        {
            "id": "2",
            "name": "Managers",
            "description": "",
            "all_access_group": "N",
            "ldap_organizational_unit": "",
            "external_group_id": ""
        }
   ]
}

Fields Description

Field Name Value Type Description
id string The ID of the group.
name string The name of the group.
description string The description of the group.
all_access_group string Whether or not the group is an all access group.
ldap_organizational_unit string The ID of the group in LDAP.
external_group_id string The ID of the group specified in an external tool.

3.2. Create Group

  1. Item: user_group
  2. Methods: POST
  3. Specify the ID of any other User Group previously created in the system. This Group's data is going to serve as a basis for creating a new Group
  4. Select Form request and provide group info:
    • Enter a name for the new group
    • all_access_group: Specify "yes" / "no". If creating an All Access Group, its members inherit access to all available elements, Dimensions, Dimension Values, Categories, and Datasets
    • Optionally, enter a description for the Group
  5. Enter an API Token
  6. [Run Request]
  7. The returned object contains an array of objects, each containing User's data.

4. Configure User's Group Membership

4.1. Display User's Group Membership

NOTE: Each value of the id parameter in the response represents a single user-group pair and can be utilized to delete or create a new group membership.

This API call returns a full list of Groups, that the specified User is a member of.

  1. Item: user_group_member
  2. Methods: GET
  3. user: Specify the ID of a User the group membership of whom you want to display
  4. Enter an API Token
  5. [Run Request]
  6. The returned object contains an array of objects each of which contains data of the Groups where the selected User is in.

Example Response 

{
    "user_group_members": [
        {
            "id": "162",
            "user": "118",
            "group": "1"
        },
        {
            "id": "399",
            "user": "118",
            "group": "53"
        },
        {
            "id": "400",
            "user": "118",
            "group": "60"
        }
    ]
}

Fields Description

Field Name Value Type Description
id string The unqiue ID of the user-group connection. Using this ID you can unassign the user from the group.
user string The ID of the user.
group string The ID of the group.

4.2. Add User to Group

This procedure allows adding a User to a specified Group (one User at a time).

  1. Item: user_group_member
  2. Methods: POST
  3. Enter the ID of the previously created user-group pair.
  4. user_id:Specify the ID of a User you want to make a member of a specific Group
  5. user_group_id:Specify the ID of the User Group to which you want this User to be assigned
  6. Enter an API Token
  7. [Run Request]
  8. The returned object contains an object which contains data of the new user-group connection.

4.3. Remove User from the Group

  1. Item: user_group_member
  2. Method: DELETE
  3. ID: Enter the ID of the previously created user-group pair
  4. Enter an API Token
  5. [Run Request]

5. Configure Group Dimension Access

5.1. Display Group Dimension Access

  1. Item: user_group_member
  2. Methods: GET
  3. Optionally, Specify the ID of the group, the dimension access of which you want to display. If this parameter is not specified, all Groups' dimension access data is displayed
  4. Enter an API Token
  5. [Run Request]
  6. The returned object contains an array of objects, each of which represents a single group-dimension access

Example Response 

{
    "group_dimensions": [
        {
            "id": "2",
            "group": "1",
            "dimension": "2",
            "scope_of_access": "All Dimension Values"
        },
        {
            "id": "13",
            "group": "1",
            "dimension": "8",
            "scope_of_access": "Specific Dimension Values"
        },
        {
            "id": "54",
            "group": "1",
            "dimension": "53",
            "scope_of_access": "All Dimension Values"
        }
    ]
}

Fields Description

Field Name Value Type Description
id string The unqiue ID of the group-dimension connection. Using this ID you can manipulate group-dimension pairs by removing them or creating a new ones.
group string The ID of the group.
dimension string The ID of the dimension.
scope_of_access string Whether the members of the group have access to All Dimension Values or Specific Dimension Values.

5.2. Add Dimension Access to Group (To All Dimension Values)

  1. Item: group_dimension
  2. Methods: POST
  3. Enter the ID of the previously created group-dimension connection
  4. Select Form request and provide the following parameters:
    • dimension: Specify the ID of a Dimension you want to give access to
    • scope_of_access:  All Dimension Values
    • group: Specify the ID of the Group to which access should be given
  5. Enter an API Token
  6. [Run Request]
  7. The returned object contains an array with the object representing a newly created group-dimension access pair

5.3. Add Specific Dimension Value Access to Group

This API call allows to add a specific Dimension Value access to Group:

$.ajax({
  	"url":  "/api/group_dimension_value", 
  	"type":  "POST", 
  	data: JSON.stringify({
    "group": "<Group ID>",
    "dimension": "<Dimension ID>",
    "dimension_value": "<Dimension Value>"
  }),
  	"headers": 
{"Accept":"application/json"}
}).done(response=>console.log(response))

Replace the following with the actual values:

  • <Group ID>: the ID of the Group
  • <Dimension ID>: the ID of the Dimension
  • <Dimension Value>: Dimension Value

Request example:

$.ajax({
  	"url":  "/api/group_dimension_value", 
  	"type":  "POST", 
  	data: JSON.stringify({
    "group": "14",
    "dimension": "55",
    "dimension_value": "7094"
  }),
  	"headers": 
{"Accept":"application/json"}
}).done(response=>console.log(response))