Restflow.io

## Introduction

For operations teams at fast-growing startups, keeping organizational charts updated is a persistent challenge. Org charts provide critical visibility into team structures, reporting lines, and departmental hierarchies — crucial for onboarding, planning, and communication. However, manual updates are error-prone and time-consuming.

This guide shows you how to build a fully automated workflow using **n8n**, an open-source workflow automation tool, to generate org charts directly from your company’s directory API (such as Microsoft Graph API or Google Directory API). By connecting to your employee data source and dynamically building a visualization-ready JSON, you can keep your org charts current without manual intervention.

Target Audience: Operations managers, automation engineers, and startup CTOs looking to automate org chart generation.

—

## What Problem Does This Solve?
– Eliminates manual, error-prone org chart updates.
– Provides up-to-date organizational structure visualizations.
– Enables easier onboarding and team planning.
– Integrates directly with canonical employee data sources via directory APIs.

—

## Tools and Services Integrated

– **n8n**: Workflow automation platform.
– **Directory API**: Microsoft Graph API (Azure AD), Google Workspace Directory API, or any custom RESTful directory API.
– **Org Chart Visualization**: Output JSON compatible with org chart libraries like [OrgChart JS](https://balkan.app/OrgChartJS/) or [Google Charts OrgChart](https://developers.google.com/chart/interactive/docs/gallery/orgchart).
– Optional: **Google Drive/Dropbox** for storing generated org chart files.

—

## Workflow Overview: From Directory API to Org Chart JSON

1. **Trigger**: Manual trigger or scheduled interval in n8n.
2. **Fetch Directory Data**: API call to retrieve employees and reporting relationships.
3. **Transform Data**: Parse and transform raw directory data into a hierarchical JSON structure.
4. **Generate Org Chart Data**: Format data for org chart libraries.
5. **Output/Store**: Save the JSON or optionally upload org chart visualization file.

—

## Detailed Step-by-Step n8n Tutorial

### Prerequisites
– Access and credentials to your directory API (e.g., Azure AD OAuth token or Google API Key).
– n8n instance setup (cloud or self-hosted).
– Basic knowledge of n8n nodes, JSON parsing, and API requests.

### Step 1: Setup the Trigger Node

– Use the **Cron** node for scheduled runs (e.g., nightly updates).
– Alternatively, use the **Webhook** node for manual triggering.

### Step 2: Fetch Employee Data from Directory API

– Add an **HTTP Request** node.
– Configure it to call the directory API endpoint that returns user information including:
– Employee ID
– Manager ID (to establish reports-to relationship)
– Name
– Title
– Department
– Email
– Example: Microsoft Graph API endpoint `GET https://graph.microsoft.com/v1.0/users?$select=id,displayName,jobTitle,manager` (note: manager often requires an additional call).

#### Tips:
– If your API does not return the manager field inline, use additional API requests to fetch it.
– Use n8n’s **HTTP Request Pagination** to handle large employee sets.

### Step 3: Construct Reporting Hierarchy

– Use a **Function** node to process raw employee data.
– The function should:
– Build a map of employeeId to employee object.
– For each employee, associate their manager’s ID.
– Build a tree structure where each employee is a node, and children arrays represent direct reports.

#### Sample Function Code (simplified):

“`javascript
const employees = items[0].json.value; // Assuming Microsoft Graph response
const employeeMap = {};

// Create map
employees.forEach(emp => {
employeeMap[emp.id] = {…emp, reports: []};
});

// Build hierarchy
let rootNodes = [];
employees.forEach(emp => {
const managerId = emp.managerId || null;
if(managerId && employeeMap[managerId]) {
employeeMap[managerId].reports.push(employeeMap[emp.id]);
} else {
rootNodes.push(employeeMap[emp.id]);
}
});

return [{ json: { hierarchy: rootNodes } }];
“`

### Step 4: Format Org Chart Data for Visualization

– Depending on your visualization tool, format the hierarchy.
– For Google Charts OrgChart, the data structure is generally a 2D array like `[ [‘Name’, ‘Manager’], [‘CEO’, ”], [‘Manager’, ‘CEO’], [‘Employee’, ‘Manager’] ]`.

– Use another **Function** node to flatten the hierarchical structure into this format.

Example:

“`javascript
const hierarchy = items[0].json.hierarchy;
const result = [[‘Name’, ‘Manager’]];

function traverse(node, parentName) {
result.push([node.displayName, parentName || ”]);
if (node.reports) {
node.reports.forEach(child => traverse(child, node.displayName));
}
}

hierarchy.forEach(rootNode => traverse(rootNode, ”));

return [{ json: { orgChartData: result } }];
“`

### Step 5: Save or Export the Org Chart Data

– Use the **Write Binary File** node to save the org chart JSON to your preferred storage or
– Use an integration node, e.g., **Google Drive**, **Dropbox**, or **Slack** to share the org chart.

—

## Common Errors and Troubleshooting Tips

– **API Authorization Failures:** Ensure your directory API tokens are valid and scopes include required permissions (e.g., `User.Read.All` in Microsoft Graph).
– **Pagination Issues:** Large directories may require handling paginated responses; enable pagination in n8n’s HTTP Request node.
– **Manager Field Missing:** Some directory APIs require separate calls to fetch manager relationships; implement additional API requests carefully to avoid rate limits.
– **Circular References:** Validate data to ensure there are no circular reporting lines, which can break tree-building logic.
– **Node Execution Errors:** Use n8n’s debug features and console logs in Function nodes to diagnose.

—

## Scaling and Adapting the Workflow

– **Multiple Directory Sources:** Extend the workflow to fetch from multiple directory APIs by duplicating fetch and transform steps.
– **Custom Attributes:** Enrich org chart nodes with custom employee metadata like office location or phone number.
– **Visual Chart Generation:** Integrate with chart libraries or services (via HTTP Request nodes) to generate SVG/PNG directly.
– **Notification Triggering:** On significant org changes, trigger Slack/Email notifications.
– **Incremental Updates:** Implement delta queries or timestamp checks to process only changed employees for performance.

—

## Summary

Automating org chart generation with n8n and directory APIs streamlines a crucial operations function—keeping employee hierarchies accurate and accessible. By fetching raw data, transforming it into hierarchical structures, and formatting for visualization, this workflow reduces manual effort and ensures real-time organizational visibility.

**Bonus Tip:** Consider building a simple front-end dashboard that consumes the generated org chart JSON for interactive viewing, enabling seamless org structure exploration for all team members.

—

Implement this workflow to empower your operations team with up-to-date organizational insight through automation—saving time, reducing errors, and improving collaboration.