Business Objects Configuration

Business Objects allow administrators to define structured, reusable data views that support both importing and exporting data through the Accurids platform.

They are designed for controlled, automated data exchange — ensuring that:

external systems receive validated, business-ready JSON, and
structured JSON can be imported into Accurids without interacting with RDF directly.

Administrators configure:

How RDF data is transformed into or from structured JSON
Which objects are included or created based on conditions
Where data is delivered or received (e.g., S3, API)
When exchanges are triggered (manual or automatic)

This page describes how to configure Business Objects via the UI and via the API. For information about how users interact with them, see User Guide: Business Objects.

Configuring Business Objects in the UI

Admins can configure Business Objects from the Configuration menu by opening the Business Objects tab.

The overview page lists all existing Business Object configurations in a table with the following columns:

Column	Description
Configuration Name	The name of the Business Object
Description	A short description of the configuration
Automatic Export Schedule	Whether and when exports run automatically
Push Targets	Configured export destinations (e.g., S3 bucket names)
Enabled	Whether the configuration is active
Actions	Icons to view/edit, delete, or run an export (see below)

Actions in the Action column

The Action column provides three icons:

View/Edit (eye icon) — Open the configuration to view or edit its settings.
Delete (trash icon) — Remove the configuration.
Execute Export (play icon) — Trigger an immediate manual export for that configuration. Use this when you need to push data to the configured targets without waiting for the next scheduled run.

Creating a Configuration

On the Business Objects tab, click Add Configuration (plus icon in the upper right).
The Add Configuration form opens with three collapsible sections: General Information, Import Settings, and Export Settings.
At the top right of the form, the Enabled toggle controls whether the configuration is active. New configurations are enabled by default.

General Information

In the General Information section:

Name (required) — A descriptive name for the Business Object (e.g. Person).
Description — An optional description (e.g. Business Object for Person data with nested Address).
Configuration (required) — The YAML mapping that defines how RDF data is transformed to and from structured JSON. Enter it in the built-in editor. See Defining a Business Object for the full YAML reference.

Import Settings

Expand Import Settings to configure:

Entity Change Owners — A dropdown to select users or groups who can see pending changes created by Business Object ingestions. Use this when ingestions are run by service accounts but review is done by specific people or teams. See Change Owners for details.

Export Settings

Expand Export Settings to configure:

Automatic Export Schedule — A dropdown to select a predefined schedule or Disabled for manual-only exports. When enabled, Accurids uses standard cron syntax to run exports automatically.
Push Targets — Add or remove destination names (e.g., S3 bucket names). Use Add to add a target; remove entries as needed. Adding a bucket name will require adding Conditions.
Conditions — Add or remove filter rules. Each condition is a Predicate / Value pair that controls which objects are included in the export. Add conditions to restrict exports (e.g., only objects of type Person).
Click Save to create the configuration. It will appear in the overview table.

Editing a Configuration

Click the View/Edit (eye) icon in the Actions column for the configuration. The same form opens with all sections. When editing an existing configuration, an icon near the page title (Edit Business Object configuration) lets you copy the configuration ID. Edit the fields and click Save to apply.

Deleting a Configuration

Click the Delete (trash) icon in the Actions column for the configuration you want to remove.

Executing an export from the UI

To run an export immediately without waiting for the schedule, click the Execute Export (play) icon in the Actions column for that configuration.

Accessing the API

To access and explore the Accurids Public API, navigate to https://your-accurids-domain/api.

The API provides endpoints for defining, updating, importing, and exporting Business Objects.

1. Defining a Business Object

A Business Object is defined via a configuration file (in YAML) that maps RDF data in Accurids to a structured JSON format. Each configuration specifies:

Fields to include (e.g., strings, numbers, booleans, objects, arrays)
Paths for data extraction (RDF predicates or linked objects)
Nested structures for related objects
Optional filters, conditions, or templates for customization
Push targets for defining where exports are delivered (e.g., S3, API)

Example YAML Configuration

type: object
path: Person:.
fields:
  uri:
    type: id
  type:
    type: resource
    path: <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>
  first_name:
    type: string
    path: <https://schema.org/givenName>
  last_name:
    type: string
    path: <https://schema.org/familyName>
  email:
    type: string
    path: <https://schema.org/email>
  address:
    type: object
    path: <https://schema.org/address>/Address:.
    fields:
      uri:
        type: id
      street:
        type: string
        path: <https://schema.org/streetAddress>
      city:
        type: string
        path: <https://schema.org/addressLocality>

Example with Array Fields

Arrays can be defined to handle properties with multiple values, such as emails, phone numbers, or identifiers. They are declared using type: array with an elements block describing the contained data type.

type: object
path: Person:.
fields:
  uri:
    type: id
  first_name:
    type: string
    path: <https://schema.org/givenName>
  last_name:
    type: string
    path: <https://schema.org/familyName>
  emails:
    type: array
    path: <https://schema.org/email>
    elements:
      type: string
  phone_numbers:
    type: array
    path: <https://schema.org/telephone>
    elements:
      type: string

Arrays can also contain nested objects for more complex relationships.

2. Ingestion Prerequisites

Before ingesting JSON data into Accurids:

The PID Generator module must be active for URI minting.
All referenced namespaces must exist and match the configuration.
The Business Object must be enabled.
Input JSON must strictly follow the configured field structure.

Note: Skipping the Pending Changes workflow is a platform-level setting.
See Platform Configuration for details.

Workflow and immediate publishing

Business Object ingestion normally creates Pending Changes that must go through the workflow before data is published.

If the Accurids instance is configured to skip Pending Changes (direct publish mode):

objects are published immediately,
PIDs are generated, and
the ingestion API response includes the mirrored Business Object data with the generated PIDs.

Ingestion Modes

When importing data into a Business Object, Accurids supports two ingestion modes that define how existing data is handled and updated.

Mode	Description	Typical Use Case
ADD	Adds new objects and merges new data into existing ones. Existing information is preserved — Accurids appends any additional fields or values from the incoming payload.	Incremental enrichment or non-destructive updates where existing data should remain intact.
REPLACE	Replaces all existing data for matching objects (based on URI). The previous statements for these objects are deleted and fully replaced with the new payload content.	Controlled synchronization or complete data refresh scenarios.

Example Behavior

Existing object:

{
  "uri": "https://id.accurids.com/person/1",
  "name": "Alice"
}

Incoming payload:

{
  "uri": "https://id.accurids.com/person/1",
  "name": "Bob"
}

With mode=ADD: → result = name: ["Alice", "Bob"]
With mode=REPLACE: → result = name: "Bob"

Example Endpoints

POST /api/v1/business-objects/{id}?mode=ADD

or

POST /api/v1/business-objects/{id}?mode=REPLACE

If no mode is specified, ADD is used by default.

Ingest Business Object Data (API)

To ingest Business Object JSON into Accurids, use:

POST /api/v1/business-objects/{businessObjectId}

Query parameter: `mode`

The ingestion mode defines how existing data is handled:

ADD (default): merges new values into existing objects (non-destructive)
REPLACE: replaces all existing values for matching objects (based on URI)

Examples:

POST /api/v1/business-objects/{businessObjectId}?mode=ADD

POST /api/v1/business-objects/{businessObjectId}?mode=REPLACE

Response fields

The ingestion response contains:

status: lifecycle stage of the ingested changes (DRAFT, SUBMITTED, or PUBLISHED)
entityChangeCount: number of created changes
workflowSkipped: whether workflow was skipped (direct publish mode)
releaseId: release ID (only present when status is PUBLISHED)
data: mirrored Business Object including generated PIDs (only present when workflow is skipped)

When workflowSkipped is true and publishing succeeds, data is returned in the response so integrators can immediately use the created resource identifiers.

3. Change Owners

Business Objects can optionally define change owners. Change owners are users and/or groups that should also be able to access the pending changes created by Business Object ingestions, even if they did not execute the ingestion API call themselves.

This is useful when Business Objects are executed by service accounts, but review and stewardship should be handled by specific people or teams.

Configuration

Add entityChangeOwners to the Business Object definition:

{
  "entityChangeOwners": {
    "groups": [
      "Group Name"
    ],
    "users": [
      "reviewer1@accurids.com",
      "reviewer2@accurids.com"
    ]
  }
}

Effect

When accurids.pending-changes.skip=false (pending review enabled):

the API user that triggered ingestion can access the created pending changes, and
the configured change owners can also access the same pending changes (additional visibility).

Because change owners gain access to the pending changes, they can also perform the same workflow actions that their role permits — for example moving changes forward (approval) or moving changes backward (rejection / send back to a previous stage).
See Pending Changes for details on lifecycle stages and forward/backward transitions.

If no owners are configured, access is limited to the ingestion user.

4. Filtering Included Objects

The conditions block defines which objects are processed during export.

"conditions": [
  {
    "predicate": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
    "value": "https://schema.org/Person"
  }
]

Only objects matching the condition will be included.

5. Creating or Updating a Business Object

Endpoint

PUT /api/v1/business-objects

Example request:

{
  "name": "Person",
  "description": "Business Object for Person data with nested Address",
  "enabled": true,
  "config": "type: object\npath: Person:.\nfields:\n  uri:\n    type: id\n  first_name:\n    type: string\n    path: <https://schema.org/givenName>\n  last_name:\n    type: string\n    path: <https://schema.org/familyName>\n  email:\n    type: string\n    path: <https://schema.org/email>",
  "conditions": [
    {
      "predicate": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
      "value": "https://schema.org/Person"
    }
  ],
  "pushTargets": [
    {
      "bucketName": "company-businessobject"
    }
  ]
}

6. Updating Configuration Only

PUT /api/v1/business-objects/{id}/config

Replaces the configuration while keeping existing metadata.

7. Automation and Scheduling

Business Objects can be processed automatically:

On schedule — via a cronExpression
On data changes — incremental updates
After ingestion — trigger exports automatically

Example schedule:

"cronExpression": "0 0 * * *"

Runs daily at midnight (UTC). Accurids uses standard cron syntax.

8. Metadata and Integrity

Every Business Object export includes metadata for verification and traceability.

Field	Description
`object_type`	Business Object name
`export_date`	Timestamp (UTC)
`object_count`	Number of exported objects
`data_checksum`	SHA-256 checksum for file integrity
`checksum_algorithm`	Hashing algorithm used

Accurids uses a FIFO queue to ensure stable, ordered exports — even in case of retries or temporary interruptions.

9. Troubleshooting

Problem	Cause	Solution
Ingestion failed: null	Invalid YAML or namespace mismatch	Verify YAML structure and dataset tags
No objects exported	Condition mismatch	Ensure predicate and value match dataset
Export missing	Push configuration issue	Check bucket name and permissions
Nested data missing	Incorrect paths or namespace	Ensure nested fields are valid and linked correctly

When to Use Business Objects

Use Business Objects to:

Automate data imports and exports
Standardize external data interfaces
Keep business logic consistent across systems
Maintain full traceability of changes and identifiers