Overview

This guide is intended to walk you through the process of adding a employee from your system into RQ as an employee (user) and assigning it to a location with a security role.

Users in the User Manager represent Employee accounts from the User Manager that are used to access data within RQ. To learn more about this interaction, see User Manager.

Who Is This Guide For?

The intended audience for this guide are developers who are integrating employees within their system into User Manager.

Prerequisites

To use this guide, the following steps must be completed:

Tip: If the above steps are not complete or you are not sure, contact Support.

Before You Begin

To make requests to iQmetrix APIs, you must generate an Access Token.

Definition: An Access Token is a serialized security object that identifies its owner and allows authenticated access to iQmetrix APIs.

Use the request Obtaining an Access Token and the following parameters:

Example Request (cURL)
curl -X POST \
  https://accountsdemo.iqmetrix.net/v1/oauth2/token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&client_id=PROVIDEDCLIENTID&client_secret=PROVIDEDSECRET&username=EMAIL&password=PASSWORD'
Example Response
HTTP 200
{
    "access_token": "b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz",
    "expires_in": 43199,
    "refresh_token": "FOPAB0K3eshQjrJW4mt6FbWF3OwDJL7CGdZX"
}

The token (access_token) is placed in the Authorization header of requests to iQmetrix APIs, prefixed by the word Bearer.

Example
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz

Steps

Step 1 - Creating a User

If you omit the password field (e.g. a brand new employee) you must set a temporary password or the user will not be able to log in to RQ.

To import a user from your existing system, see Importing an Existing User.

Employee Fields

Example Request
POST https://usermanagerdemo.iqmetrix.net/v1/Users/importExisting
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json
{
    "UserName": "johnb@test.com",
    "Password": "samplepassword",
    "Email": "johnb@test.com",
    "FirstName": "John",
    "LastName": "Bates",
    "ParentEntityId": 14146,
    "ClientUserId": "132",
    "JobTitle": "Sales Clerk",
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "PhoneNumbers": [
        {
            "Number": "6135550127",
            "Extension": "5532",
            "Type": "Work"
        }
    ]
}
Example Response
HTTP 201 Content-Type: application/json
{
    "Password": null,
    "Id": 19760,
    "CorrelationId": null,
    "ClientUserId": "132",
    "FirstName": "John",
    "LastName": "Bates",
    "UserName": "johnb@test.com",
    "Email": "johnb@test.com",
    "IsActive": true,
    "ParentEntityId": 14146,
    "Profiles": [],
    "Picture": null,
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "PhoneNumbers": [
        {
            "Number": "6135550127",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
    "JobTitle": "Sales Clerk",
    "Version": 1
}

(Optional) Setting a Temporary Password

If you omitted the password from the previous step, then you must force the user to change their password when logging in for the first time.

To set a temporary password for your user, see Setting a Temporary Password

Example Request
POST https://usermanagerdemo.iqmetrix.net/v1/Users({UserId})/TemporaryPassword
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json
{
    "Password": "newpa55word"
}
Example Response
HTTP 204 Content-Type: application/json

Step 2 - Get Locations

Once you have created a user in the system, the next step involves location assignment within your company tree. This ensures that employee visibility and activity is restricted to that particular location. For more information on Company Tree, see Company Tree.

To get a list of locations, see Getting All Locations for a Company

Example Request
GET https://entitymanagerdemo.iqmetrix.net/v1/Companies({CompanyId})/Locations
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Example Response
HTTP 200 Content-Type: application/json
{
    "Id": 14202,
    "Name": "Dufferin Mall",
    "Description": "This Location is used to clear out discounted inventory",
    "Roles": [
        {
            "Name": "Location"
        }
    ],
    "CreatedUTC": "2015-02-26T00:03:01.372Z",
    "LastModifiedUTC": "2015-02-27T00:03:06.392Z",
    "Area": {
        "Value": 1100,
        "Unit": "SqFt"
    },
    "Address": {
        "AddressLine1": "4970 Hillside Avenue",
        "AddressLine2": "Apt 115",
        "City": "Edmonton",
        "StateCode": "ON",
        "StateName": "Ontario",
        "CountryCode": "CA",
        "CountryName": "Canada",
        "Zip": "P9H 9I4"
    },
    "Attributes": {},
    "ClientEntityId": "123",
    "Contacts": [
        {
            "Name": "John Smith",
            "Description": "Store Manager",
            "PhoneNumbers": [
                {
                    "Description": "Main Line",
                    "Number": "5555555555",
                    "Extension": "1234"
                }
            ]
        }
    ],
    "Geography": {
        "Longitude": -104.612034,
        "Latitude": 50.443559
    },
    "Relationships": [],
    "SortName": "dufferin mall",
    "StoreHours": {
        "Monday": {
            "Open": {
                "Hour": 10,
                "Minute": 0
            },
            "Close": {
                "Hour": 10,
                "Minute": 0
            }
        },
        ...
    },
    "StorePhoneNumbers": [
        {
            "Description": "Main Line",
            "Number": "5555555555",
            "Extension": "1234"
        }
    ],
    "TimeZone": {
        "Id": "Alaskan Standard Time",
        "DaylightSavingTimeEnabled": true
    },
    "Version": 13
}

Step 3 - Assigning a Location to a User

The employee from your system will need to be assigned to a location within the company tree in RQ.

To assign a user to a location, see Assigning a User to a Location

Example Request
PUT https://usermanagerdemo.iqmetrix.net/v1/Users({UserId})/Locations({LocationId})
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json
Example Response
HTTP 204 Content-Type: application/json

rq assigned location

Step 4 - Getting Security Roles

Getting the security roles for a company is the quickest way to retrieve security roles. You are also able to retrieve security roles by Location or Division/Group.

Please note down the Security Role Id that you will be assigning based on the EntityId you provided.

For more information, see Getting All Security Roles for an Entity

Example Request
GET https://usermanagerdemo.iqmetrix.net/v1/Entities({EntityId})/SecurityRoles
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Example Response
HTTP 200 Content-Type: application/json
[
    {
        "Id": 316,
        "Name": "Store Manager"
    }
]

Step 5 - Assigning Security Roles

The goal of this step is to ensure that your employee has a security role in RQ that matches their role in your system. If a Security Role is not assigned to a User, then they will not be able to interact with RQ.

The EntityId assigned to this User would be the Company ID, Location ID, or a Group or Division ID.

For our scenario, we are assigning the security role Store Manager at this location.

To assign a security role, see Assigning a Security Role to a User

RQ Security Role

Example Request
POST https://usermanagerdemo.iqmetrix.net/v1/Users({UserId})/AssignedRoles
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json
{
    "EntityId": 14159,
    "SecurityRoleId": 316
}
Example Response
HTTP 201 Content-Type: application/json
{
    "Id": 6548,
    "EntityId": 14159,
    "SecurityRoleId": 316,
    "UserId": 19760
}

(Optional) Updating a User

A user, its properties, and attributes can be updated anytime by Updating a User

You cannot change a user’s password using this method. To update their password, you must set a temporary password.

Example Request
PUT https://usermanagerdemo.iqmetrix.net/v1/Users({UserId})
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json
{
    "Id": 19760,
    "FirstName": "John",
    "LastName": "Bates",
    "UserName": "johnb@kentel.com",
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "Attributes": {
        "Department": "Sales"
    },
    "ClientUserId": "132",
    "Email": "johnb@kentel.com",
    "IsActive": true,
    "JobTitle": "Sales Clerk",
    "ParentEntityId": 1,
    "PhoneNumbers": [
        {
            "Number": "6135550127",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
    "Picture": {},
    "Version": 1
}
Example Response
HTTP 200 Content-Type: application/json
{
    "Id": 2576,
    "FirstName": "John",
    "LastName": "Bates",
    "UserName": "johnb@kentel.com",
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "Attributes": {
        "Department": "Sales"
    },
    "ClientUserId": "132",
    "Email": "johnb@kentel.com",
    "IsActive": true,
    "JobTitle": "Sales Clerk",
    "ParentEntityId": 1,
    "PhoneNumbers": [
        {
            "Number": "6135550127",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
    "Picture": {},
    "Version": 1
}

(Optional) Terminating an Employee

An employee can be terminated at anytime by Disabling their user account.

This method does not delete the employee or free up their email address or username to be used to create another User. To free up an email address or username, you must instead update the email or username of the original User to something else.

Example Request
DELETE https://usermanagerdemo.iqmetrix.net/v1/Users({UserId})
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Example Response
HTTP 200 Content-Type: application/json
Was this page helpful?