> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/playbooks/playbooks/automated-joiner-mover-leaver-playbook-with-zoho-people-and-entraid.md).

# Automated Joiner-Mover-Leaver Playbook with Zoho People and EntraID

### Overview

This document provides a step-by-step, walkthrough for configuring and using Joiner–Mover–Leaver (JML) Playbooks in BalkanID. It covers the complete setup flow from integrating your HRIS and Microsoft Entra ID, to configuring webhooks with HRIS and n8n, and finally executing playbook actions that automatically create, route, and approve access requests based on defined policies.

While this guide is specific to Zoho People and EntraID, the same concepts apply to other HR systems and applications for which provisioning & de-provisioning are supported by BalkanID.

### What Are JML Playbooks?

JML Playbooks in BalkanID allow you to automate identity and access workflows triggered by employee lifecycle events such as:

* **Joiner**: A new employee starts
* **Mover**: An employee changes role, department, or title
* **Leaver**: An employee exits the organization

Playbooks can automatically:

* Create access requests
* Route requests for approval or auto-approval based on policy
* Trigger provisioning and deprovisioning workflows
* Maintain a complete audit trail within your BalkanID tenant

Playbooks can be triggered in real time via webhooks or run automatically based on defined conditions, providing consistency, speed, and governance across identity workflows.

### Pre-requisites

Before you begin, ensure the following are in place:

* An active BalkanID tenant accessible at `https://<yourdomain>.balkanid.app`
* Administrator access in Zoho People (or your HRIS) to configure API keys and webhooks
* Global Administrator access in Microsoft Entra ID for integration setup
* An active n8n instance (cloud-hosted or self-hosted)

> This guide uses n8n-based workflows as an example, BalkanID playbooks supports multiple workflows. If you use a different workflow orchestration platform or custom scripts, please contact BalkanID Support: <support@balkan.id>

### Integration Setup

#### 1. Configure HRIS - Zoho People Integration

1. Log in to `<yourdomain>.balkanid.app`
2. Navigate to Configure → Integrations
3. Click Add Integration<br>

   <figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FOmmT5gK5i2iF4Gflr5Bu%2Fimage.png?alt=media&#x26;token=5187e089-7408-439c-a86b-c358d1668f36" alt=""><figcaption></figcaption></figure>
4. Search for and select 'Zoho People'
5. Provide a description and assign an owner<br>

   <figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FNwTSF8e2ptOPFIuqfcEC%2Fimage.png?alt=media&#x26;token=e5e02cfd-693c-4ac0-83d0-8327a9fbf6e5" alt=""><figcaption></figcaption></figure>
6. Click on 'Get Access Token'
7. Complete the setup using either:
   * API Key authentication, or
   * Credential-based authentication (as supported by your HRIS)
8. Click on next to move onto *Optional Configuration.*
   1. Fill Optional configuration, if required.

      <figure><img src="https://docs.balkan.id/~gitbook/image?url=https%3A%2F%2F2975852473-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FbVGYwk8aSk5yI1GDPEW9%252Fuploads%252FvgCgyt5C48JaG9QxevOS%252Fimage.png%3Falt%3Dmedia%26token%3D84c48d74-f15d-4ccf-816f-eb7e5433b467&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=5d536fed&#x26;sv=2" alt=""><figcaption></figcaption></figure>
   2. Once you filled in the information, click Save. Your integration is now configured and you will see the status of the integration displayed alongside other integrations on the *Integrations* page. When data is available, the integration Status will read Connected and the integration Message will read Data available.

#### 2. Configure Microsoft Entra ID Integration

BalkanID recommends using a **dedicated service account** for Entra ID integrations instead of a personal user account.

Follow the official setup guide here:

* [Microsoft Entra ID Integration Setup](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integration/microsoft-azure-and-entra-id-integration-setup)

This integration enables BalkanID to evaluate identity attributes, roles, and group memberships required for access decisions.

### Webhook Configuration: Zoho People ↔ n8n

### n8n Playbook Setup

1. Download the playbook JSON file provided by the BalkanID team. If you have not yet received the file, please contact <support@balkan.id> to request it.
2. Import the workflow into your n8n instance
3. Configure credentials:

   * Create a new BalkanID API Key from `<yourdomain>.balkanid.app → Account → API Keys`\
     and use it in playbook configuration

   <figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FIYIU1kNMPu4sFtPqAJ7Y%2Fimage.png?alt=media&#x26;token=2aa44574-4328-40f5-a3cc-f210f81ee147" alt=""><figcaption></figcaption></figure>

   * Zoho People credential using the API key created in the next step
4. Initialize configuration variables in the workflow nodes
5. Activate the workflow

Once active, the n8n workflow listens for HRIS events and triggers the appropriate BalkanID playbook.

### Zoho People API and Workflow/Webhook setup

To enable real-time JML automation, Zoho People events must be forwarded to n8n using webhooks.

#### Step 1: Create a Zoho People API Key

1. Log in to Zoho People as an administrator
2. Navigate to your organization's <https://api-console.zoho.com><br>

   <figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FmFJKAIXDOSB1i7jDSdHv%2Fimage.png?alt=media&#x26;token=057a0365-6b5b-489a-a8ef-7c41b0fbd4c5" alt=""><figcaption></figcaption></figure>
3. Click Add Client
4. Name the key (for example: `BalkanID-Playbooks-API`)
5. Save the API key securely

#### Step 2: Create Zoho People Webhooks

\
Navigate to Settings--> Employee Information --> Automation --> Actions --> Webhooks(Add Webhook)

**Joiner Webhook**

* Enter a meaningful name for the webhook (for example, Leaver *Webhook*)
* Choose 'Post' under Method
* In 'URL to Notify?', enter the production webhook URL generated from n8n
  * Example: `https://balkanid.app.n8n.cloud/webhook/<webhook-id>`
* Save the webhook configuration<br>

  <figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FSiyXfJka86BEM8fIb03B%2Fimage.png?alt=media&#x26;token=9b039aa5-d6a5-4d96-ae33-62527e611a54" alt=""><figcaption></figcaption></figure>

**Mover Webhook**

* Enter a meaningful name for the webhook (for example, *Mover Webhook*)
* Choose 'Post' under Method
* In 'URL to Notify?', enter the production webhook URL generated from n8n
  * Example: `https://balkanid.app.n8n.cloud/webhook/<webhook-id>`
* Save the webhook configuration

**Leaver Webhook**

* Enter a meaningful name for the webhook (for example, Leaver *Webhook*)
* Choose 'Post' under Method
* In 'URL to Notify?', enter the production webhook URL generated from n8n
  * Example: `https://balkanid.app.n8n.cloud/webhook/<webhook-id>`
* Save the webhook configuration

#### Step 3: Create Zoho People Workflows

Navigate to Settings--> Employee Information --> Automation --> Workflows (Add Workflow)

**Joiner Workflow**

* Enter a meaningful name for the workflow (for example, *JML* - *Joiner Workflow*)
* Form - 'Employee'
* Trigger Events - 'New record created'
* In 'Actions', choose the Joiner Webhook created in Step 2
* Save the workflow configuration<br>

  <figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FQmL2DSgZP11VqkCWsAqh%2Fimage.png?alt=media&#x26;token=3002c508-1bde-4ac0-9452-c4b7aa119f82" alt=""><figcaption></figcaption></figure>

**Mover Workflow**

* Enter a meaningful name for the workflow (for example, *JML* - *Joiner Workflow*)
* Form - 'Employee'
* Trigger Events - 'Existing record id edited'
* In 'Actions', choose the Mover Webhook created in Step 2
* Save the workflow configuration<br>

  <figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FMyyPIhuy3nl8Nm0m7WpF%2Fimage.png?alt=media&#x26;token=43e727af-e21b-4818-b1a3-be1c16926e60" alt=""><figcaption></figcaption></figure>

**Leaver Workflow**

* Enter a meaningful name for the workflow (for example, *JML* - *Joiner Workflow*)
* Form - 'Employee'
* Trigger Events - 'Existing record id edited'
* Criteria - 'Employee Status' contains 'Terminated'
* In 'Actions', choose the Leaver Webhook created in Step 2
* Save the workflow configuration<br>

  <figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FbwoOCmNYWIZQ8aSeqmC6%2Fimage.png?alt=media&#x26;token=709f32ad-2cc9-4f75-8f50-939703470da1" alt=""><figcaption></figcaption></figure>

### Playbooks in Action

#### Joiner Playbook Flow

The Joiner playbook automates identity creation and access provisioning when a new employee joins the organization.<br>

<figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2F9POw4IbjwNeXRedxQPTF%2Fimage.png?alt=media&#x26;token=88fce7aa-8fa4-4bc0-b85a-9ed49cb22ef7" alt="" width="375"><figcaption></figcaption></figure>

1. A new employee record is created in Zoho People
2. A Webhook or scheduled sync sends the event to BalkanID
3. The Joiner playbook is triggered
4. A user account is created in Entra ID on the employee’s start date
5. The playbook:
   * Applies preferred email formats
   * Detects and resolves name or email conflicts
6. Birthright access is determined using peer analysis based on attributes such as:
   * Job title
   * Department
   * Manager
   * Employment type
7. BalkanID generates access grant requests
8. Requests are:
   * Auto-approved via policies(see how to create policies [here](https://docs.balkan.id/~/revisions/mC3o0sGSsz3AIawh8Hk1/lifecycle-management/policies), or
   * Manually approved by designated approvers
9. Approved access is provisioned in Entra ID
10. The newly created corporate email address is written back to Zoho People
11. Login credentials are securely shared with the employee’s manager

#### Leaver Playbook Flow

The Leaver playbook ensures timely deprovisioning when an employee is terminated.<br>

<figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2Fgch4UaKgA9LW6ub0uKKp%2Fimage.png?alt=media&#x26;token=2d99b1d5-ed90-4dfa-8fc6-307f3159779f" alt="" width="375"><figcaption></figcaption></figure>

1. An employee is marked as terminated in Zoho People
2. The termination event is sent to BalkanID Leaver playbook and is triggered
3. BalkanID generates access revoke requests
4. Requests are:

Auto-approved through [policy](https://docs.balkan.id/~/revisions/mC3o0sGSsz3AIawh8Hk1/lifecycle-management/policies), or

Routed for manual approval

5. Upon approval, the user is suspended in Entra ID, preventing further access

#### Mover Playbook Flow

The Mover playbook manages access changes when an employee’s attributes change.<br>

<figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2Ff8ElIDYqnnHei3LfytJL%2Fimage.png?alt=media&#x26;token=6b809974-8dfd-48d7-8cef-b2475d8b1fb1" alt="" width="375"><figcaption></figcaption></figure>

1. An employee’s attributes (job title, department, manager, employment type, etc.) are updated in Zoho People
2. The change is detected and the Mover playbook is triggered
3. BalkanID recalculates the employee’s required access
4. Access grant and revoke requests are generated
5. Requests are:

Auto-approved using [policies](https://docs.balkan.id/~/revisions/mC3o0sGSsz3AIawh8Hk1/lifecycle-management/policies), or

Sent for manual approval

6. Approved changes are provisioned in Entra ID


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.balkan.id/playbooks/playbooks/automated-joiner-mover-leaver-playbook-with-zoho-people-and-entraid.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.