Skip to main content

Check out Port for yourself 

Ingest and map HiBob users to Port user accounts

This guide demonstrates how to ingest HiBob users into your Port software catalog and automatically map them to existing Port user accounts based on email addresses.

We will leverage on Port's custom webhook integration, self-service actions and automations to ingest data from HiBob and map them to Port user accounts.

Once implemented users will be able to:

  • Maintain a complete inventory of all HiBob users in your organization within Port.
  • Automatically link HiBob users to their corresponding Port user accounts for seamless integration.
  • Provide visibility into which HiBob users have Port accounts and which don't.

Prerequisites​

This guide assumes the following:

  • You have a Port account and have completed the onboarding process.
  • You have a HiBob instance with admin permissions to create service users and configure permissions. Learn about HiBob API Service Users.
  • You have created a HiBob service user with appropriate permissions to access employee data via the People search API.
  • You have permissions to create blueprints, self-service actions, and automations in Port.

Set up data model​

To represent HiBob users in your portal, we need to create a HiBob User blueprint that can store HiBob user data and optionally link to Port user accounts.

Create the HiBob User blueprint

  1. Go to the data model page of your portal.

  2. Click on + Blueprint.

  3. Click on the Edit JSON button in the top right corner.

  4. Copy and paste the following JSON schema:

    HiBob user blueprint (Click to expand)
    {
      "identifier": "hibob_user",
      "description": "HiBob User",
      "title": "HiBob User",
      "icon": "User",
      "schema": {
        "properties": {
          "id": {
            "type": "string",
            "title": "ID",
            "description": "The user's unique identifier"
          },
          "firstName": {
            "type": "string",
            "title": "First Name",
            "description": "The user's first name"
          },
          "email": {
            "type": "string",
            "title": "Email",
            "description": "The user's email address"
          },
          "department": {
            "type": "string",
            "title": "Department",
            "description": "The user's department"
          },
          "isManager": {
            "type": "string",
            "title": "Is Manager",
            "description": "Indicates if the user is a manager"
          },
          "work_title": {
            "type": "string",
            "title": "Job Title",
            "description": "The user's job title"
          },
          "fullName": {
            "type": "string",
            "title": "Full Name",
            "description": "The user's full name"
          },
          "displayName": {
            "type": "string",
            "title": "Display Name",
            "description": "The user's display name"
          }
        },
        "required": []
      },
      "mirrorProperties": {},
      "calculationProperties": {},
      "aggregationProperties": {},
      "relations": {}
    }

  5. Click on Save to create the blueprint.

Enhance the Port User blueprint

Now we need to enhance the Port User blueprint to add a relation to the HiBob User blueprint and mirror properties to display HiBob information.

  1. Go to the data model page of your portal.

  2. Find the User blueprint and click on it.

  3. Click on the Edit JSON button in the top right corner.

  4. Add the following relation to the relations object:

    Port User blueprint relation (Click to expand)
    "relations": {
      "hibob_user": {
        "title": "HiBob User",
        "target": "hibob_user",
        "required": false,
        "many": false
      }
    }

  5. Add the following mirror property to the mirrorProperties object to display the HiBob display name:

    Port User blueprint mirror property (Click to expand)
    "mirrorProperties": {
      "hibob_display_name": {
        "title": "HiBob display name",
        "path": "hibob_user.displayName"
      }
    }

  6. Click on Save to update the blueprint.

Additional mirror properties

You can add more mirror properties to display other HiBob user attributes like job title (hibob_user.work_title), department (hibob_user.department), manager status (hibob_user.isManager), or any other property from the HiBob User blueprint that would be useful for your organization.

Add Port secrets

Now let's add your HiBob credentials to Port's secrets:

  1. Click on the ... button in the top right corner of your Port application.

  2. Click on Credentials.

  3. Click on the Secrets tab.

  4. Click on + Secret and add the following secrets:

    • HIBOB_API_URL - Your HiBob API base URL (e.g., https://api.hibob.com/v1)
    • HIBOB_BASIC_AUTH - Your base64 encoded credentials (base64(HIBOB_SERVICE_USER_ID:HIBOB_SERVICE_USER_TOKEN))
    echo -n "HIBOB_SERVICE_USER_ID:HIBOB_SERVICE_USER_TOKEN" | base64
HiBob Authentication

HiBob uses Basic Authentication with base64 encoding. You'll need to create a service user in HiBob with appropriate permissions to access employee data, then encode the credentials as base64(service_user_id:service_user_token). Learn more about creating HiBob service users.

Set up webhook integration​

We'll create a webhook integration that can ingest multiple HiBob users at once and automatically establish relationships with existing Port users.

Follow the steps below to create the webhook integration:

  1. Go to the Data Sources page.

  2. Click on + Data Source.

  3. Select Webhook and click on Custom integration.

  4. Name it "HiBob Users Sync".

  5. Copy the webhook URL - you'll need this for the automation.

  6. Copy and paste the following mapping into the Map the data from the external system into Port field:

    HiBob users webhook mapping (Click to expand)
    [
      {
        "blueprint": "hibob_user",
        "operation": "create",
        "filter": "(.body.response | has(\"employees\")) and (.body.response.employees | type == \"array\")",
        "itemsToParse": ".body.response.employees | map(select(.email != null))",
        "entity": {
          "identifier": ".item.id | tostring",
          "title": ".item.displayName | tostring",
          "properties": {
            "id": ".item.id",
            "firstName": ".item.firstName",
            "email": ".item.email",
            "department": ".item.work.department",
            "isManager": ".item.work.isManager",
            "work_title": ".item.work.title",
            "fullName": ".item.fullName",
            "displayName": ".item.displayName"
          }
        }
      },
      {
        "blueprint": "_user",
        "operation": "create",
        "filter": "(.body.response | has(\"employees\")) and (.body.response.employees | type == \"array\")",
        "itemsToParse": ".body.response.employees | map(select(.email != null))",
        "entity": {
          "identifier": ".item.email",
          "relations": {
            "hibob_user": ".item.id | tostring"
          }
        }
      }
    ]

  7. Click on Save.

Port User creation

When the webhook processes HiBob users, it will automatically create Port User entities for any HiBob users that don't already exist in your Port organization. These newly created Port users will have a Disabled status by default, meaning they won't receive email invitations and won't be able to access Port until an admin manually activates their accounts.

Set up self-service actions​

We'll create two self-service actions in this section, one for fetching HiBob users and another for fetching a HiBob user via email for the automation and webhook to ingest data.

Sync HiBob Users self-service action

This action fetches all HiBob users and send them to the process HiBob users automation for processing. The automation will then send the response to the webhook for ingestion.

Follow the steps below to create the action:

  1. Go to the Self-service page.

  2. Click on + Action.

  3. Click on the Edit JSON button in the top right corner.

  4. Copy and paste the following action configuration:

    Sync HiBob Users action (Click to expand)
    {
      "identifier": "sync_hibob_users",
      "title": "Sync HiBob Users",
      "icon": "User",
      "description": "Fetch and sync all HiBob users to Port",
      "trigger": {
        "type": "self-service",
        "operation": "DAY-2",
        "userInputs": {
          "properties": {},
          "required": [],
          "order": []
        }
      },
      "invocationMethod": {
        "type": "WEBHOOK",
        "url": "{{ .secrets.HIBOB_API_URL }}/people/search",
        "agent": false,
        "synchronized": true,
        "method": "POST",
        "headers": {
          "RUN_ID": "{{ .run.id }}",
          "Content-Type": "application/json",
          "Authorization": "Basic {{ .secrets.HIBOB_BASIC_AUTH }}"
        },
        "body": {
          "showInactive": false,
          "fields": [
            "root.id",
            "root.firstName",
            "root.email",
            "work.department",
            "work.isManager",
            "work.title",
            "root.fullName",
            "root.displayName"
          ],
          "humanReadable": "REPLACE"
        }
      },
      "requiredApproval": false
    }

  5. Click Save to create the action.

Get HiBob user by email self-service action

This action fetches a single HiBob user by email and send the response to a process single hibob user automation for processing. The automation will then send the response to the webhook for ingestion.

Follow the steps below to create the action:

  1. Go to the Self-service page.

  2. Click on + Action.

  3. Click on the Edit JSON button in the top right corner.

  4. Copy and paste the following action configuration:

    Get HiBob user by email action (Click to expand)
    {
      "identifier": "get_single_hibob_user",
      "title": "Get HiBob User by Email",
      "icon": "User",
      "description": "Fetch a HiBob user to Port",
      "trigger": {
        "type": "self-service",
        "operation": "DAY-2",
        "userInputs": {
          "properties": {
            "email": {
              "icon": "DefaultProperty",
              "type": "string",
              "title": "Email of user",
              "description": "Email of the hibob user"
            }
          },
          "required": [],
          "order": [
            "email"
          ]
        }
      },
      "invocationMethod": {
        "type": "WEBHOOK",
        "url": "{{ .secrets.HIBOB_API_URL }}/people/search",
        "synchronized": true,
        "method": "POST",
        "headers": {
          "RUN_ID": "{{ .run.id }}",
          "Content-Type": "application/json",
          "Authorization": "Basic {{ .secrets.HIBOB_BASIC_AUTH }}"
        },
        "body": {
          "showInactive": false,
          "fields": [
            "root.id",
            "root.firstName",
            "root.email",
            "work.department",
            "work.isManager",
            "work.title",
            "root.fullName",
            "root.displayName"
          ],
          "filters": [
            {
              "fieldPath": "root.email",
              "operator": "equals",
              "values": [
                "{{ .inputs.email }}"
              ]
            }
          ]
        }
      },
      "requiredApproval": false
    }

  5. Click Save to create the action.

Set up automations​

Now we'll create the automations that process the HiBob users list and sends the response to the webhook for bulk ingestion and single user ingestion.

Create automation to bulk ingest HiBob users

This automation will trigger when the Sync HiBob Users action is executed. It will then process the HiBob users list and send the response to the webhook for bulk ingestion.

Follow the steps below to create the automation:

  1. Go to the Automations page of your portal.

  2. Click on + Automation.

  3. Click on the Edit JSON button in the top right corner.

  4. Copy and paste the following automation configuration:

    Process HiBob users automation (Click to expand)
    Replace the webhook URL

    Replace the webhook URL with the one you created in the previous step.

    {
      "identifier": "process_hibob_users",
      "title": "Process HiBob Users",
      "description": "Processes HiBob users list and sends to webhook for bulk ingestion",
      "icon": "User",
      "trigger": {
        "type": "automation",
        "event": {
          "type": "RUN_UPDATED",
          "actionIdentifier": "sync_hibob_users"
        },
        "condition": {
          "type": "JQ",
          "expressions": [
            ".diff.after.status == \"SUCCESS\""
          ],
          "combinator": "and"
        }
      },
      "invocationMethod": {
        "type": "WEBHOOK",
        "url": "<YOUR_WEBHOOK_URL>",
        "agent": false,
        "synchronized": true,
        "method": "POST",
        "headers": {
          "Content-Type": "application/json"
        },
        "body": {
          "response": "{{ .event.diff.after.response }}"
        }
      },
      "publish": true
    }

  5. Click Save to create the automation.

Create automation to process single HiBob user

This automation will trigger when the Get HiBob user by email action is executed. It will then process the HiBob user and send the response to the webhook for single user ingestion.

Follow the steps below to create the automation:

  1. Go to the Automations page of your portal.

  2. Click on + Automation.

  3. Click on the Edit JSON button in the top right corner.

  4. Copy and paste the following automation configuration:

    Process single HiBob user automation (Click to expand)
    {
      "identifier": "process_single_hibob_user",
      "title": "Process Single HiBob Users",
      "description": "Processes HiBob user and sends to webhook for ingestion",
      "icon": "User",
      "trigger": {
        "type": "automation",
        "event": {
          "type": "RUN_UPDATED",
          "actionIdentifier": "get_single_hibob_user"
        },
        "condition": {
          "type": "JQ",
          "expressions": [
            ".diff.after.status == \"SUCCESS\""
          ],
          "combinator": "and"
        }
      },
      "invocationMethod": {
        "type": "WEBHOOK",
        "url": "<YOUR_WEBHOOK_URL>",
        "agent": false,
        "synchronized": true,
        "method": "POST",
        "headers": {
          "Content-Type": "application/json"
        },
        "body": {
          "response": "{{ .event.diff.after.response }}"
        }
      },
      "publish": true
    }

  5. Click Save to create the automation.

Create automation to sync HiBob users when a new Port user is added

To ensure new Port users get mapped to HiBob users automatically, we'll create an automation that triggers when a new Port user is created. This automation will trigger the Get HiBob user by email action to fetch details of the HiBob user by email, which will then be processed by the webhook integration.

Follow the steps below to create the automation:

  1. Go to the Automations page of your portal.

  2. Click on + Automation.

  3. Click on the Edit JSON button in the top right corner.

  4. Copy and paste the following automation configuration:

    Automation to sync HiBob users when a new Port user is added (Click to expand)
    {
      "identifier": "ingest_hibob_user",
      "title": "Trigger hibob_user ingestion automation",
      "description": "This will trigger the Get HiBob user by email action to fetch and ingest a single HiBob user",
      "icon": "User",
      "trigger": {
        "type": "automation",
        "event": {
          "type": "ENTITY_CREATED",
          "blueprintIdentifier": "_user"
        },
        "condition": {
          "type": "JQ",
          "expressions": [],
          "combinator": "and"
        }
      },
      "invocationMethod": {
        "type": "WEBHOOK",
        "url": "https://api.getport.io/v1/actions/get_single_hibob_user/runs",
        "agent": false,
        "synchronized": true,
        "method": "POST",
        "headers": {
          "RUN_ID": "{{ .run.id }}",
          "Content-Type": "application/json"
        },
        "body": {
          "properties": {
            "email": "{{ .event.diff.after.identifier }}"
          }
        }
      },
      "publish": true
    }

  5. Click Save to create the automation.

Let's test it​

  1. Go to the Self-service page.

  2. Find the "Sync HiBob Users" action.

  3. Click Execute.

  4. Monitor the action execution in the Audit logs page.

  5. Verify that HiBob users are created in your catalog with proper relationships.

Conclusion​

You've successfully ingested HiBob users into your Port catalog and automatically mapped them to existing Port user accounts based on email addresses.