Publishing an org chart
With Org Chart information, the Productiv platform provides visibility into user activity across your app portfolio. This allows us to segment activity and display insights for different teams, locations and managers.
The developer APIs can be used to push a snapshot of org chart data to Productiv from one or more existing systems and view the latest snapshot of the org chart. Productiv treats the latest snapshot of the data as the current org chart for the organization.
In order to upload the current snapshot of the org chart there are 2 steps:
-
Declare a new org chart by generating a resource ID.
-
Using the resource ID, populate the org chart with users through follow-up PUT requests.
Prerequisites
All developer APIs require a Bearer access token as part of each request's headers. To see how to generate an authorization token, check out Authorization. The scopes needed for the endpoints mentioned in this guide are https://api.productiv.com/connector.write
and https://api.productiv.com/report.read
. This token expires after a certain amount of time; when the token expires a new token must be generated.
Step 1: generating a resource ID
By generating a resource ID, you are declaring a new version of your org chart. This initially empty org chart will be used by Productiv as the most up to date version of your org chart.
A resource ID acts as a uniform resource Identifier, which helps us map different sets of users to the same snapshot of the org chart. This is necessary if the org chart will have more than 1000 users since we limit the number of users that can be uploaded in one PUT request to 1000.
Adding custom fields to the org chart is optional, but it allows you to define custom fields for use in the add org chart endpoint. You may define up to 5 custom fields
The following javascript code uses the resource ID endpoint to create a new org chart.
const axios = require("axios");
const bearerToken = "some_token"; // see Authorization guide for generating a bearer token
const resourceIDURL =
"https://public-api.productiv.com/services/push/v1/customer/org-chart";
const headers = {
"content-type": "application/json",
Authorization: `Bearer ${bearerToken}`,
};
const data = {
orgChartName: "name",
customFieldsConfig: {
customField1: "Date of Birth",
customField2: "Director",
customField3: "VP",
customField4: "Entity",
customField5: "Business Unit"
}
};
(async () => {
const res = await axios.post(resourceIDURL, data, { headers });
if (res.status !== 200) {
console.error("Failed to generate a resource ID");
} else {
console.log(`Created an org chart with resource ID: ${res.data.id}`);
}
})();
If the request succeeds, you should see an output like the following:
Created an org chart with resource ID: e8760038-b691-445a-9df7-27c34f4efd2c
Step 2: adding users to the org chart
After getting a resource ID from Productiv, the org chart can be sent by issuing one or more PUT requests to the add org chart endpoint. This endpoint accepts no more than 1000 users per request, multiple PUT requests to the same resource ID are required if more than 1000 users need to be added to the org chart. When this is the case, the hasMore
field in the request body should be set to true for all but the last request.
The following code illustrates how to add a small list of users to the org chart.
const axios = require("axios");
const bearerToken = "some_token"; // see Authorization guide for generating a bearer token
const resourceID = "some_resource_ID"; // generated in step 1
const addOrgChartURL = `https://public-api.productiv.com/services/push/v1/customer/org-chart/${resourceID}`;
const headers = {
"content-type": "application/json",
Authorization: `Bearer ${bearerToken}`,
};
const data = {
hasMore: false,
users: [
{
email: "employee1@example.com",
firstName: "Employee",
lastName: "One",
team: "Engineering",
location: "San Francisco",
title: "SDE",
managerEmail: "manager1@example.com",
additionalEmails: "",
costCenter: "1004 - San Francisco",
"Date of Birth": "01/01/1990",
Director: "Jane Doe",
VP: "John Smith",
Entity: "Freelance",
"Business Unit": "Product",
},
{
email: "manager1@example.com",
firstName: "Manager",
lastName: "One",
team: "Engineering",
"Business Unit": "Marketing",
},
{
email: "employee2@example.com",
firstName: "Employee",
lastName: "Two",
team: "Sales",
},
],
};
(async () => {
const res = await axios.put(addOrgChartURL, data, { headers });
if (res.status !== 200) {
console.error("Failed to add users to the org chart");
} else {
console.log("Successfully added users to the org chart");
}
})();
Note that the user objects should match the schema described here.
Viewing the uploaded org chart
Now that the org chart has been created and users have been added to it, we can view it with the Get latest org chart endpoint. This endpoint provides a link to the CSV file that defines the org chart.
The following code snippet queries the org chart and prints out the CSV file.
const axios = require('axios');
const bearerToken = 'some_token'; // see Authorization guide for generating a bearer token
const getOrgChartURL = `https://public-api.productiv.com/services/push/v1/customer/org-chart`;
const headers = {
'content-type': 'application/json',
Authorization: `Bearer ${bearerToken}`,
};
(async () => {
const res = await axios.get(getOrgChartURL, { headers });
if (res.status !== 200) {
console.error('Failed to get org chart download link');
} else {
const orgChartRequest = await axios.get(res.data.downloadUrl);
if (orgChartRequest.status !== 200) {
console.error('Failed to read org chart');
} else {
console.log(orgChartRequest.data);
}
}
})();
On success, we should see data that we had uploaded previously:
first name,last name,primary email,department,office location,cost center,manager,additional emails,job title
Employee,One,employee1@example.com,Engineering,San Francisco,1004 - San Francisco,manager1@example.com,,SDE
Manager,One,manager1@example.com,Engineering,Other,,,,
Employee,Two,employee2@example.com,Sales,Other,,,,