Manager Roll Up Guide

This guide describes how iQmetrix Partners can retrieve the manager data configured in RQ using the iQmetrix Entity Manager and DataConnect APIs.

The manager field retrieved through this guide is configured in the RQ in the following places:

Locations - Corporate Office Setup
Districts - District Setup
Regions - Region Setup (see screenshot below)

Screenshot of region setup in RQ

Prerequisites

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

You must have your Partner onboarding package from iQmetrix, which includes your access credentials needed to access iQmetrix APIs
Each RQ database you access must have User Manager enabled with all users synced to User Manager
Each RQ database you access must have Company Tree sync enabled with all locations synced
Each RQ database you access must be on version 6.24 or later

Limitations

Please note the following limitations of this guide:

When enabled, the manager value is synced to the Entity Manager API and is updated when the manager is added, changed or deleted in RQ.
If the manager’s RQ account is disabled, it has no impact on their ability to be assigned as a manager.
If the manager account assigned in RQ is not synced to Entity Manager (User Manager is not enabled, or users are not synced to User Manager), the value will appear as null in the API

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.

Step 1 - Get a List of Companies

The first step is to get a list of companies you have contracted with using the Relationships endpoint.

From the response, CompanyID will be used in subsequent calls.

Example Request

POST https://dataconnect.iqmetrix.net/partner/relationships
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz

Example Response

HTTP 200 Content-Type: application/json

[
  {
    "CompanyID": 521528,
    "CompanyName": "KentelRC",
    "DoingBusinessAs": "Kentel",
    "PreferredEndpoint": "https://dataconnectrc-useast.iqmetrix.net",
    "DateCreatedUTC": "2019-03-19T19:51:09.763"
  }
]

Step 2 - Get Company Tree for a Company

Next, use the Entity Manager API to retrieve the full Company Tree using Get a Company Tree and the parameters:

CompanyId - From Step 1

From the response, parse the tree structure and extract the Id of each object as well as the Id of the parent object.

In our example, there is:

A Division with Id 521529 and parent NodeId 521528
A Group with Id 521530 and parent NodeId 521529
A Location with Id 521531 and parent NodeId 521530

Then examine the Role value, and use the following table to determine the next step.

Role	Next Step
Division	Get Details for a Division
Group	Get Details for a Group
Location	Get Details fo a Location

Example Request

GET https://entitymanager.iqmetrix.net/v1/Companies(521528)/Tree
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz

Example Response

HTTP 200 Content-Type: application/json

{
  "Id": 521528,
  "Name": "Kentel",
  "DisplayName": "",
  "Description": "",
  "Role": "Company",
  "ClientEntityId": null,
  "Version": 2,
  "Nodes": [
    {
      "Id": 521529,
      "Name": "First Division",
      "DisplayName": "",
      "Description": "",
      "Role": "Division",
      "ClientEntityId": null,
      "Version": 2,
      "Nodes": [
        {
          "Id": 521530,
          "Name": "First Group",
          "DisplayName": "",
          "Description": "",
          "Role": "Group",
          "ClientEntityId": null,
          "Version": 2,
          "Nodes": [
            {
              "Id": 521530,
              "Name": "First Location",
              "DisplayName": "",
              "Description": "",
              "Role": "Location",
              "ClientEntityId": null,
              "Version": 2,
              "Nodes": [],
            }
          ]
        } 
      ]    
    }
  ]
}

Step 3a - Get Details for a Division

For each Division in the Company Tree, retrieve the identifier of the associated manager using Retrieve Division Details and the parameters:

CompanyId - From Step 1
NodeId - From Step 2
Id (DivisionId) - From Step 2

From the response, ManagerUserId 4392053 will be used in subsequent steps.

Example Request

GET https://entitymanager.iqmetrix.net/v1/companies(521528)/tree/nodes(521528)/divisions(521529)?$extend=attributes
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz

Example Response

HTTP 200 Content-Type: application/json

{
  "Id": 521529,
  "Name": "First Division",
  "DisplayName": "",
  "Description": "",
  "Roles": [
    {
      "Name": "Division"
    }
  ],
  "Role": "Division",
  "SortName": "first division",
  "Attributes": {
    "ManagerUserId": 4392053
  },
  "Relationships": [
    {
      "Id": 308000,
      "Definition": 13,
      "Source": 521528,
      "Destination": 521529,
      "CreatedUtc": "2019-03-19T19:11:33.616Z",
      "Version": 1
    }
  ],
  "Version": 315,
  "CreatedUtc": "2019-03-19T19:11:33.6Z",
  "LastModifiedUtc": "2020-01-28T08:36:16.65Z",
  "CorrelationId": "2",
  "ClientEntityId": null,
  "TypeId": null,
  "Logo": null,
  "Website": null
}

Step 3b - Get Details for a Group

For each Group in the Company Tree, retrieve the identifier of the associated manager using Retrieve Group Details and the parameters:

CompanyId - From Step 1
NodeId - From Step 2
Id (GroupId) - From Step 2

From the response, ManagerUserId 4392053 will be used in subsequent steps.

Example Request

GET https://entitymanager.iqmetrix.net/v1/companies(521528)/tree/nodes(521529)/groups(521530)?$extend=attributes
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz

Example Response

HTTP 200 Content-Type: application/json

{
  "Id": 521530,
  "Name": "First Group",
  "DisplayName": "",
  "Description": "",
  "Roles": [
    {
      "Name": "Group"
    }
  ],
  "Role": "Group",
  "SortName": "first group",
  "Attributes": {
    "ManagerUserId": 4392053
  },
  "Relationships": [
    {
      "Id": 308009,
      "Definition": 12,
      "Source": 521529,
      "Destination": 521530,
      "CreatedUtc": "2019-03-19T19:11:40.149Z",
      "Version": 1
    }
  ],
  "Version": 5,
  "CreatedUtc": "2019-03-19T19:11:40.133Z",
  "LastModifiedUtc": "2020-01-28T08:36:51.743Z",
  "CorrelationId": "5",
  "ClientEntityId": null,
  "TypeId": null,
  "Logo": null,
  "Website": null
}

Step 3c - Get Details for a Location

For each Location in the Company Tree, retrieve the identifier of the associated manager using Get a Location for a Company and the parameters:

CompanyId - From Step 1
Id (LocationId) - From Step 2

From the response, ManagerUserId 4392053 will be used in subsequent steps.

Example Request

GET https://entitymanager.iqmetrix.net/v1/Companies(521528)/Locations(521531)
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz

Example Response

HTTP 200 Content-Type: application/json

{
  "Id": "14202",
  "Name": "First Location",
  "DisplayName": "First Location",
  "Description": "This Location is used to clear out discounted inventory",
  "Roles": [
    "Company"
  ],
  "CreatedUtc": "2015-02-26T00:03:01.372Z",
  "LastModifiedUtc": "2015-02-27T00:03:06.392Z",
  "Area": {},
  "Address": {
    "AddressLine1": "4970 Hillside Avenue",
    "AddressLine2": "Apt 115",
    "City": "Edmonton",
    "StateCode": "ON",
    "StateName": "Ontario",
    "CountryCode": "string",
    "CountryName": "Canada",
    "Zip": "P9H 9I4"
  },
  "Attributes": {
    "ManagerUserId": 4392053
  },
  "ClientEntityId": "123",
  "Contacts": [],
  "Geography": {},
  "Relationships": [],
  "SortName": "first location",
  "StoreHours": {},
  "StorePhoneNumbers": [
    {
      "Description": "Main Line",
      "Number": "5555555555",
      "Extension": "1234"
    }
  ],
  "TimeZone": {
    "Id": "string",
    "DaylightSavingTimeEnabled": true
  },
  "Version": "13",
  "CorrelationId": "string",
  "LocationType": "string",
  "LocationSubType": "string",
  "Logo": {},
  "Role": "string",
  "TypeId": 0,
  "Website": "string"
}

Step 4 - Get Details for a User

To retrieve details about a manager such as name and email, use Get a Single User and the parameter:

ManagerUserId - From Step 3a, Step 3b or Step 3c

Example Request

GET https://usermanager.iqmetrix.net/v1/users(4392053)
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz

Example Response

HTTP 200 Content-Type: application/json

{
  "Id": 4392053,
  "CorrelationId": null,
  "ClientUserId": null,
  "FirstName": "api.support",
  "LastName": "iqmetrix",
  "UserName": "api.support.kentel",
  "Email": "api.support.kentel@iqmetrix.com",
  "IsActive": true,
  "ParentEntityId": 521528,
  "ParentEntityName": "Kentel",
  "Profiles": [],
  "Picture": null,
  "Address": {
    "AddressLine1": "123 Main St",
    "AddressLine2": null,
    "City": "North Pole",
    "StateCode": "SK",
    "CountryCode": "CA",
    "Zip": "H0H0H0"
  },
  "PhoneNumbers": [],
  "JobTitle": "Santa",
  "Attributes": {},
  "Version": 1
}