Overview

This guide is intended to walk you through the process of adding an 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:

You must have RQ v5.12 or later (supports two-way communication between APIs and RQ)
You must have your onboarding package from iQmetrix, which includes your access credentials and environments
Your Company Tree in RQ, representing company structure (stores, groups, divisions, etc.) must be created

Before You Begin

To make requests to iQmetrix APIs, you must first generate an Access Token using the access credentials from your onboarding package.

For more information on authentication and how to generate an access token, see Authenticating with iQmetrix APIs.

Steps

Step 1 - Creating a User

To import a user from your existing system use Importing an Existing User and the following parameters:

ParentEntityId - Use CompanyId provided in onboarding package

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.

From the response, the following values will be used in later steps:

Id (19760) - Identifier of the newly created user

Example Request

POST https://usermanagerrc.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": "5555555555",
            "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,
    "ParentEntityName": null,
    "Profiles": [],
    "Picture": null,
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "PhoneNumbers": [
        {
            "Number": "5555555555",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
    "JobTitle": "Sales Clerk",
    "Attributes": {},
    "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, use Setting a Temporary Password.

Example Request

POST https://usermanagerrc.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, use Getting All Locations for a Company and the following parameters:

CompanyId - Provided in onboarding package

From the response, the following values will be used in later steps:

Id (14202) - Identifier of a RQ location in the Entity Manager API

Example Request

GET https://entitymanagerrc.iqmetrix.net/v1/Companies({CompanyId})/Locations
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json

Example Response

HTTP 200 Content-Type: application/json

{
    "LocationStatus": "Active",
    "LocationType": null,
    "LocationSubType": null,
    "Address": {
        "AddressLine1": "1521 Main St",
        "AddressLine2": null,
        "City": "Huntington Beach",
        "StateCode": "CA",
        "StateName": "California",
        "CountryCode": "US",
        "CountryName": "United States",
        "Zip": "90210"
    },
    "Contacts": [],
    "StorePhoneNumbers": [],
    "Area": null,
    "StoreHours": {},
    "Geography": null,
    "TimeZone": {
        "Id": "Central Standard Time",
        "DaylightSavingTimeEnabled": false
    },
    "Id": 14202,
    "Name": "Location",
    "DisplayName": "",
    "Description": "",
    "Roles": [
        {
            "Name": "Location"
        }
    ],
    "Role": "Location",
    "SortName": "Location",
    "Attributes": {},
    "Relationships": [
        {
            "Id": 667847,
            "Definition": 16,
            "Source": 173600,
            "Destination": 611444,
            "CreatedUtc": "2019-06-26T18:15:54.332Z",
            "Version": 1
        }
    ],
    "Version": 14,
    "CreatedUtc": "2016-08-11T15:06:44.111Z",
    "LastModifiedUtc": "2020-05-04T08:16:59.364Z",
    "CorrelationId": "6935",
    "ClientEntityId": null,
    "TypeId": 1818,
    "Logo": null,
    "Website": null
}

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, use Assigning a User to a Location and the following parameters:

CompanyId - Provided in onboarding package
UserId - From Step 1
LocationId - From Step 2

Example Request

PUT https://usermanagerrc.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

Step 4 - Getting Security Roles

To control what your new User is able to do, you will need to assign the user to a Security Role. First, retrieve a list of all Security Roles for your company using Get All Security Roles for an Entity and the following parameters:

EntityId - Use CompanyId provided in onboarding package. You can also use the identifier of a Group, Division or Location from the Entity Manager API

From the response, the following values will be used in later steps:

Id (316) - Identifier of a Security Role in the User Manager API

Example Request

GET https://usermanagerrc.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",
        "SecurityModelVersion": 1,
        "IsCrossEntity": false,
        "IsProtected": false
    }
]

Step 5 - Assigning Security Roles

All Users must have a Security Role or they will not be able to interact with RQ.

RQ Security Role

Assign a Security Roles to your user using Assigning a Security Role to a User and the following parameters:

UserId - From Step 1
EntityId - Use CompanyId provided in onboarding package. You can also use the identifier of a Group, Division or Location from the Entity Manager API
SecurityRoleId - From Step 4

Example Request

POST https://usermanagerrc.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 using Update a User Record.

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

Example Request

PUT https://usermanagerrc.iqmetrix.net/v1/Users({UserId})
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
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,
    "ParentEntityName": null,
    "Profiles": [],
    "Picture": null,
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "PhoneNumbers": [
        {
            "Number": "1234567890",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
    "JobTitle": "Sales Clerk",
    "Attributes": {},
    "Version": 1
}

Example Response

HTTP 200 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,
    "ParentEntityName": null,
    "Profiles": [],
    "Picture": null,
    "Address": {
        "AddressLine1": "1432 Merry View Road",
        "AddressLine2": "",
        "City": "Big Windy",
        "StateCode": "ON",
        "CountryCode": "CA",
        "Zip": "A1A2B2"
    },
    "PhoneNumbers": [
        {
            "Number": "1234567890",
            "Extension": "5532",
            "Type": "Work"
        }
    ],
    "JobTitle": "Sales Clerk",
    "Attributes": {},
    "Version": 2
}

(Optional) Terminating an Employee

An employee can be terminated at anytime using Disable a User.

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://usermanagerrc.iqmetrix.net/v1/Users({UserId})
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz

Example Response

HTTP 200 Content-Type: application/json