Destination Adapter: beqom Platform Authorization

Description

The beqom Platform Authorization destination adapter sets subject-attribute values for workers in the beqom Platform by posting to POST /integrationapi/v1/auth/subject-attribute-values.

Each input row maps to one worker. The adapter sends every configured attribute for every worker in the Data Frame, in chunks. Per-row outcomes are reported in the pipeline results file. See Pipeline results.

Authentication

The adapter authenticates using Client Credentials — a client ID and a client secret are required.

Input data shape

One row per worker. The Data Frame has:

• A column with the worker identifier (worker_id_field).
• One column per attribute you want to write. Multi-valued cells are encoded as a single string with values separated by value_separator (default ;). For example, a roles column cell value of admin;reviewer is sent to the API as ["admin", "reviewer"].

An empty cell sends an empty array, which clears that attribute for the worker. To leave a worker's existing values untouched for some attribute, do not list that attribute in the configuration at all (the adapter only writes attributes it is configured for).

Configuration

Required Parameters

To use this adapter, set the adapter configuration attribute to beqom_platform_authorization.

client_id (string)

Your beqom Platform client ID.

client_secret_name (string)

Alias of the secret containing your client secret.

base_domain (string)

The base domain for your beqom Platform instance.

data_frame (string)

Name of the Data Frame containing the per-worker attribute rows.

worker_id_field (string)

Name of the column containing each worker's identifier (workerId).

Optional Parameters

attribute_fields (object)

Mapping of API attribute name to Data Frame column name. Attribute names must match the casing used by the API.

Standard attribute names:

• SecurityGroupsNames
• Roles
• OrgItemsIds
• ExcludedEmployeeIds
• ExcludedOrgItemIds
• IncludeEmployeeIds
• WorkerCountry
• WorkerPerformanceEligibility (boolean — send as "true" / "false")
• EmploymentHomeCountry
• EmploymentLegalEntity
• EmploymentStatus
• EmploymentCostCenter
• EmploymentMaterialRiskTaker (boolean — send as "true" / "false")
• EmploymentGlobalMobilityFlag (boolean — send as "true" / "false")
• EmploymentHostCountry
• EmploymentHostCountryLegalEntity
• EmploymentHostCountryCostCenter
• EmploymentJobLevel
• EmploymentJobTitle
• EmploymentJobFamily
• EmploymentJobCategory
• EmploymentJobFunction
• LocalGrade
• GlobalGrade
• WorkRegion
• GrantFullAccess (boolean — send as "true" / "false")

Boolean-style attributes are still string arrays on the wire — a cell value of true becomes ["true"].

custom_attribute_fields (object)

Mapping of custom-attribute name to Data Frame column name. Each entry is written as a custom attribute on the worker. Same value-parsing rules as attribute_fields.

dry_run (boolean, default: false)

When true, the adapter records what it would have sent but does not modify any data on the server. The pipeline results file is still produced. If full_sync is also enabled, the adapter still reads current server-side state so the result's cleared_worker_ids preview reflects what a real run would do. Useful for verifying configuration and previewing impact before running for real.

full_sync (boolean, default: false)

Treats the input Data Frame as the authoritative set of workers for the configured attributes.

When false (default): the configured attributes are written only for workers in the input Data Frame; other workers are left untouched.

When true: the configured attributes are cleared for any worker not in the input Data Frame.

WARNING

A partial input combined with full_sync: true will clear configured attributes for every worker missing from that input. Enable only when the upstream Data Frame is genuinely the source of truth for those attributes.

exempt_worker_ids (array of strings, default: [])

Worker IDs that the adapter never touches. Workers in this list are not updated even when present in the input Data Frame, and they are not cleared even when full_sync: true would otherwise clear them. Useful for protecting specific workers — for example, administrative accounts whose authorization is managed outside this pipeline.

Worker IDs not present in either the input Data Frame or the server-side data are silently ignored.

value_separator (string, default: ";")

Character (or substring) used to split cell values into a list. Whitespace around each value is trimmed; empty entries are discarded.

chunk_size (integer, default: 5000)

Number of rows sent per API request. Must be greater than 0.

Example configuration

Assigning roles, security groups, employment home country, the global mobility flag, and a Department custom attribute:

{
  "version": 1,
  "destination_adapters": [
    {
      "adapter": "beqom_platform_authorization",
      "configuration": {
        "client_id": "my.client.id",
        "client_secret_name": "my-client-secret",
        "base_domain": "<your-tenant>.beqom.io",
        "data_frame": "worker_authorization",
        "worker_id_field": "workerId",
        "attribute_fields": {
          "Roles": "roles",
          "SecurityGroupsNames": "security_groups",
          "EmploymentHomeCountry": "home_country",
          "EmploymentGlobalMobilityFlag": "global_mobility"
        },
        "custom_attribute_fields": {
          "Department": "department"
        }
      }
    }
  ]
}

Example data

Two rows from the worker_authorization Data Frame referenced above. Worker 1 is assigned two roles and two security groups plus a home country and a department; worker 2 carries a single role, single security group, the global-mobility boolean set to true, and a multi-value department.

workerId	roles	security_groups	home_country	global_mobility	department
1	CompensationManager;HRBP	SG-CompAdmin-Global;SG-HRBP-France	FRA		Engineering
2	Reviews	SG-HRBP-France		true	Finance;Operations

Results format and Error Handling

The adapter reports per-row outcomes in the pipeline results file under destination_adapter_results[].result.metadata:

• total_rows — number of input rows.
• succeeded_count, failed_count — aggregate counts.
• succeeded — list of WorkerId values the API accepted.
• failed — list of { WorkerId, Result, ValidationErrors } objects for rows the API rejected, plus rows skipped because worker_id_field was empty (Result: "MissingWorkerId").
• cleared_worker_ids — list of WorkerId values whose configured attributes were cleared by the full_sync pass. Empty when full_sync is false.
• dry_run — the effective value of the dry_run configuration option for this run. true indicates no server-side changes were issued and the per-row outcomes are a preview of what a non-dry run would have done.

The adapter still reports success: true when individual rows fail server-side validation — row-level failures do not fail the pipeline. The adapter only fails when authentication fails or when the API rejects the request as a whole.

An example destination_adapter_results entry with a mix of successful and failed rows:

{
  "result": {
    "success": true,
    "metadata": {
      "total_rows": 3,
      "succeeded_count": 2,
      "failed_count": 1,
      "succeeded": ["1", "2"],
      "failed": [
        {
          "WorkerId": "3",
          "Result": "Error",
          "ValidationErrors": [
            { "Key": "SecurityGroupsNames", "Value": "InvalidSecurityGroupName" }
          ]
        }
      ],
      "cleared_worker_ids": [],
      "dry_run": false
    },
    "error": null
  },
  "adapter": "beqom_platform_authorization",
  "started_at": "2026-05-21T12:00:00+00:00",
  "completed_at": "2026-05-21T12:00:02+00:00"
}