Destination Adapter: beqom Platform Security Groups

Description

The beqom Platform Security Groups destination adapter synchronises security-group definitions to the beqom Platform. Each input row defines one security group — its name, the roles associated with it, and a set of named attributes (e.g. OrgItemsIds, WorkerCountry) that together form an access profile.

The adapter looks up each input row against the existing server-side groups by name (case-insensitive). New groups are created and existing groups are updated; nothing is ever deleted. 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 security group. The Data Frame has:

• A column with the group name (name_field). This is the matching key used to decide whether to create a new group or update an existing one.
• A column with the roles to associate with the group (roles_field). Encoded as a single string with values separated by value_separator (default ;). For example, a cell value of HRBP;Reviewer is sent as ["HRBP", "Reviewer"].
• One column per attribute declared in attribute_fields. Same separator-encoding rules as roles.

An empty, NULL, or whitespace-only attribute cell omits that attribute from the request for that row (rather than sending an empty array). To leave an attribute out for every row, omit it from attribute_fields.

Configuration

Required Parameters

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

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-group rows.

name_field (string)

Name of the column containing each security group's name. Used as the matching key against existing groups (case-insensitive).

roles_field (string)

Name of the column containing the roles assigned to each group, encoded as a value_separator- separated string.

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:

• 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

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

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: 25)

Number of new groups sent per bulk-create request. Must be greater than 0. The default is kept small because a group can carry a large attribute payload (e.g. many OrgItemsIds), and an oversized request can exceed the server-side gateway timeout. Raise it when your payloads are small; lower it if you still see timeouts. Updates are sent one at a time and are not affected by this setting.

Example configuration

Synchronising a worker-roles security model with OrgItemsIds and WorkerCountry attributes:

{
  "version": 1,
  "destination_adapters": [
    {
      "adapter": "beqom_platform_security_groups",
      "configuration": {
        "client_id": "my.client.id",
        "client_secret_name": "my-client-secret",
        "base_domain": "<your-tenant>.beqom.io",
        "data_frame": "security_groups",
        "name_field": "name",
        "roles_field": "roles",
        "attribute_fields": {
          "OrgItemsIds": "org_items",
          "WorkerCountry": "country"
        }
      }
    }
  ]
}

Example data

Two rows from the security_groups Data Frame referenced above. The first row is a single-role, single-country group; the second row carries two roles and an empty country, so the WorkerCountry attribute is omitted from that row's request.

name	roles	org_items	country
SG-HRBP-FR	HRBP	All Company	FR
SG-Comp-Global	CompensationManager;CompensationAdmin	All Company

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.
• created_count, updated_count, failed_count — aggregate counts.
• created — list of {name, id} for groups created by this run.
• updated — list of {name, id} for groups updated by this run.
• failed — list of {name, operation, errors, trace_id} for rows the API rejected, plus rows skipped because name_field was empty (operation: "skipped"). operation is one of "create", "update", or "skipped". errors carries the validation errors returned by the API for that row. trace_id is the X-Trace-Id response header for failures caused by a whole-request error (otherwise null); use it when reporting issues.

The adapter still reports success: true when individual rows fail server-side validation — row-level failures do not fail the pipeline.

The adapter fails the pipeline (top-level error, is_success: false) when a bulk-create request either times out client-side or returns a server error (HTTP 5xx). Both leave the server-side state unknown — some groups in the request may have been committed before the failure — so the upload is aborted rather than reporting groups as created or failed on a guess. The error message states whether the server returned an error or never responded, and records how many groups were created in earlier chunks. Re-running the pipeline creates the groups that did not commit (already-committed groups are matched by name and take the update path). If you hit this repeatedly, lower chunk_size. The adapter also fails when authentication fails or when fetching the existing groups list fails.

An example destination_adapter_results entry with a mix of created, updated, and failed rows:

{
  "result": {
    "success": true,
    "metadata": {
      "total_rows": 3,
      "created_count": 1,
      "updated_count": 1,
      "failed_count": 1,
      "created": [
        { "name": "SG-Comp-Global", "id": "550e8400-e29b-41d4-a716-446655440000" }
      ],
      "updated": [
        { "name": "SG-HRBP-FR", "id": "0a8b4c27-3e9c-4a7a-a0d6-0f6c2b8fb111" }
      ],
      "failed": [
        {
          "name": "SG-HRBP-EMEA",
          "operation": "create",
          "errors": [
            { "key": "409", "value": "Security group with name 'SG-HRBP-EMEA' already exists." }
          ],
          "trace_id": null
        }
      ]
    },
    "error": null
  },
  "adapter": "beqom_platform_security_groups",
  "started_at": "2026-05-22T12:00:00+00:00",
  "completed_at": "2026-05-22T12:00:02+00:00"
}