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:

Screenshot of region setup in RQ

Prerequisites

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

Limitations

Please note the following limitations of this guide:

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,

Example Request

GET 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:

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:

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:

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:

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:

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:

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
}