Reference Data Lifecycle Management

The REST API is currently in Early Access Preview. The API specification and endpoints might change before being marked as stable.

We recommend testing thoroughly and being prepared to adapt to potential changes in future releases.

This guide demonstrates how to manage the complete lifecycle of reference data through the API, including creating draft records, updating data, and publishing changes either directly or through a review workflow.

Before you start

Make sure you have:

Configured API authentication and obtained an access token.
Identified the URN of the reference data table you want to work with.
Appropriate permissions to modify reference data.

Lifecycle overview

The reference data lifecycle follows these stages:

Draft: Create or modify records in a working copy.
Review (optional): Submit changes for approval.
Approval (optional): Review and approve submitted changes.
Publish: Make changes visible in the published dataset.

There are two primary workflows:

Direct Publish: Create or update records in draft and publish immediately.
Review Workflow: Create or update records, submit for review, get approval, then publish.

Direct publish workflow

This workflow is suitable for automated integrations or when changes don’t require approval.

Step 1: Create records in draft

Create new records in the draft dataset.

The response includes the URN for each created record. Save these URNs if you need to update or delete the records later.

Request

POST /reference-data/v1/tables/{tableUrn}/draft/records
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "records": [
    {
      "values": [
        {
          "name": "country_code",
          "value": "XK"
        },
        {
          "name": "country_name",
          "value": "Kosovo"
        },
        {
          "name": "population",
          "value": 1800000
        }
      ]
    },
    {
      "values": [
        {
          "name": "country_code",
          "value": "TW"
        },
        {
          "name": "country_name",
          "value": "Taiwan"
        },
        {
          "name": "population",
          "value": 23800000
        }
      ]
    }
  ]
}

Response

{
  "meta": {
    "prev": null,
    "next": null,
    "total": 2
  },
  "data": [
    {
      "id": "urn:ata:{your-tenant}:reference-data:record:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "values": [
        {
          "name": "country_code",
          "value": "XK"
        },
        {
          "name": "country_name",
          "value": "Kosovo"
        },
        {
          "name": "population",
          "value": 1800000
        }
      ],
      "state": "NEW"
    },
    {
      "id": "urn:ata:{your-tenant}:reference-data:record:b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "values": [
        {
          "name": "country_code",
          "value": "TW"
        },
        {
          "name": "country_name",
          "value": "Taiwan"
        },
        {
          "name": "population",
          "value": 23800000
        }
      ],
      "state": "NEW"
    }
  ]
}

Step 2: Update records (optional)

Update existing draft records by their URN.

When updating records, you only need to specify the attributes you want to change. Other attributes remain unchanged.

Request

POST /reference-data/v1/tables/{tableUrn}/draft/records/batch
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "records": [
    {
      "id": "urn:ata:{your-tenant}:reference-data:record:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "values": [
        {
          "name": "population",
          "value": 1850000
        }
      ]
    }
  ]
}

Step 3: Publish changes

Publish all draft changes to make them available in the published dataset.

Publishing creates an immutable snapshot of the data. After publishing:

Records remain in draft with state UNCHANGED.
The published dataset contains the new immutable version.

Request - Publish all changes

POST /reference-data/v1/tables/{tableUrn}/draft/publish
Content-Type: application/json
Authorization: Bearer {access_token}

{}

Request - Publish specific records

POST /reference-data/v1/tables/{tableUrn}/draft/publish
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "filter": {
    "recordUrn": {
      "in": [
        "urn:ata:{your-tenant}:reference-data:record:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "urn:ata:{your-tenant}:reference-data:record:b2c3d4e5-f6a7-8901-bcde-f12345678901"
      ]
    }
  }
}

Response

{
  "publishedDatasetUrn": "urn:ata:{your-tenant}:reference-data:published:323e4567-e89b-12d3-a456-426614174002",
  "publishedAt": "2024-12-16T14:30:00Z"
}

Step 4: Verify published data

Confirm that your changes are visible in the published dataset.

Request

POST /reference-data/v1/tables/{tableUrn}/records/filter
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "filter": {
    "attribute": {
      "attributeName": {"equals": "country_code"},
      "string": {"in": ["XK", "TW"]}
    }
  }
}

Review and approval workflow

This workflow adds a review step before publishing, making it suitable for governed data or changes requiring approval.

Step 1: Create and update records

Follow the steps described in Direct publish workflow to create and update records in draft.

Step 2: Submit for review

Submit draft changes for review by creating a review task.

Save the reviewDatasetUrn obtained in the response as you’ll need it to approve or reject the review.

Request

POST /reference-data/v1/tables/{tableUrn}/draft/review
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "name": "Add new countries - December 2024",
  "priority": "MEDIUM",
  "description": "Adding Kosovo and Taiwan to the countries reference table",
  "filter": {
    "state": {
      "in": ["NEW", "CHANGED"]
    }
  }
}

Table 1. Request body parameters
Parameter	Type	Required	Description
`name`	string	Yes	Review task name. Max 255 characters.
`priority`	enum	Yes	Priority level: `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.
`description`	string	No	Detailed description of changes. Max 4000 characters.
`filter`	object	No	Filter to submit only specific records. If omitted, all eligible draft records are submitted.

Response

{
  "reviewDatasetUrn": "urn:ata:{your-tenant}:reference-data:review:423e4567-e89b-12d3-a456-426614174003",
  "taskMetadata": {
    "name": "Add new countries - December 2024",
    "priority": "MEDIUM",
    "description": "Adding Kosovo and Taiwan to the countries reference table"
  },
  "createdAt": "2024-12-16T14:15:00Z"
}

Step 3: List records under review

Reviewers can inspect the records submitted for review.

Request

GET /reference-data/v1/tables/{tableUrn}/reviews/{reviewDatasetUrn}/records
Authorization: Bearer {access_token}

Response

{
  "meta": {
    "prev": null,
    "next": null,
    "total": 2
  },
  "data": [
    {
      "id": "urn:ata:{your-tenant}:reference-data:record:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "values": [
        {
          "name": "country_code",
          "value": "XK"
        },
        {
          "name": "country_name",
          "value": "Kosovo"
        }
      ],
      "state": "REVIEW"
    },
    {
      "id": "urn:ata:{your-tenant}:reference-data:record:b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "values": [
        {
          "name": "country_code",
          "value": "TW"
        },
        {
          "name": "country_name",
          "value": "Taiwan"
        }
      ],
      "state": "REVIEW"
    }
  ]
}

Step 4: Approve changes

After review, approve the changes to move them back to draft for publishing.

To reject changes instead of approving them, use the reject endpoint:

POST /reference-data/v1/tables/{tableUrn}/reviews/{reviewDatasetUrn}/reject

Request - Approve all records

POST /reference-data/v1/tables/{tableUrn}/reviews/{reviewDatasetUrn}/approve
Content-Type: application/json
Authorization: Bearer {access_token}

{}

Request - Approve specific records

POST /reference-data/v1/tables/{tableUrn}/reviews/{reviewDatasetUrn}/approve
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "filter": {
    "recordUrn": {
      "in": ["urn:ata:{your-tenant}:reference-data:record:a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
    }
  }
}

Response

{
  "affectedRecordCount": 2
}

Step 5: Publish approved changes

After approval, publish the changes using the same publish endpoint as in Direct publish workflow:

Request

POST /reference-data/v1/tables/{tableUrn}/draft/publish
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "filter": {
    "recordUrn": {
      "in": [
        "urn:ata:{your-tenant}:reference-data:record:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "urn:ata:{your-tenant}:reference-data:record:b2c3d4e5-f6a7-8901-bcde-f12345678901"
      ]
    }
  }
}

Delete records

To delete records from the published dataset, mark them as deleted in draft and then publish the deletion.

Step 1: Delete from draft

Deleting a record from draft marks it with state DELETED but doesn’t remove it immediately. The record is removed from the published dataset when you publish the deletion.

Request

DELETE /reference-data/v1/tables/{tableUrn}/draft/records/{recordUrn}
Authorization: Bearer {access_token}

Step 2: Publish deletion

Request

POST /reference-data/v1/tables/{tableUrn}/draft/publish
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "filter": {
    "state": {
      "in": ["DELETED"]
    }
  }
}

Complete end-to-end example

Here’s a complete script demonstrating the direct publish workflow:

#!/bin/bash

# Configuration
ENVIRONMENT="your-environment"
REALM="your-realm"
CLIENT_ID="your-client-id"
CLIENT_SECRET="your-client-secret"
TABLE_URN="urn:ata:your-tenant:reference-data:table:123e4567-e89b-12d3-a456-426614174000"

BASE_URL="https://${ENVIRONMENT}.ataccama.one"
AUTH_URL="${BASE_URL}/auth/realms/${REALM}/protocol/openid-connect/token"
API_URL="${BASE_URL}/api/reference-data/v1"

# 1. Obtain access token
echo "Obtaining access token..."
TOKEN=$(curl -s -X POST "$AUTH_URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  | jq -r '.access_token')

# 2. Create draft records
echo "Creating draft records..."
CREATE_RESPONSE=$(curl -s -X POST "${API_URL}/tables/${TABLE_URN}/draft/records" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "values": [
          {"name": "country_code", "value": "XK"},
          {"name": "country_name", "value": "Kosovo"},
          {"name": "population", "value": 1800000}
        ]
      }
    ]
  }')

echo "$CREATE_RESPONSE" | jq '.'

# Extract record URN for updates
RECORD_URN=$(echo "$CREATE_RESPONSE" | jq -r '.data[0].id')
echo "Created record: $RECORD_URN"

# 3. Update the record
echo "Updating record..."
curl -s -X POST "${API_URL}/tables/${TABLE_URN}/draft/records/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"records\": [
      {
        \"id\": \"$RECORD_URN\",
        \"values\": [
          {\"name\": \"population\", \"value\": 1850000}
        ]
      }
    ]
  }" | jq '.'

# 4. Publish changes
echo "Publishing changes..."
PUBLISH_RESPONSE=$(curl -s -X POST "${API_URL}/tables/${TABLE_URN}/draft/publish" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}')

echo "$PUBLISH_RESPONSE" | jq '.'

# 5. Verify in published dataset
echo "Verifying published data..."
curl -s -X POST "${API_URL}/tables/${TABLE_URN}/records/filter" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "attribute": {
        "attributeName": {"equals": "country_code"},
        "string": {"equals": "XK"}
      }
    }
  }' | jq '.'

echo "Workflow complete!"

Example: Automated updates

Automate reference data updates through scheduled jobs or event-driven workflows:

# Create new records from external source
curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/{tableUrn}/draft/records" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @new_records.json

# Publish changes
curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/{tableUrn}/draft/publish" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Best practices

Use filters when publishing: Instead of publishing all changes at once, use filters to publish specific records or changes. This provides better control over what gets published.
Use review workflows for critical data: Implement review and approval workflows for sensitive or business-critical reference data.
Handle async publishing: Publishing is an asynchronous operation that might take a few seconds. Implement polling or verification logic to confirm publication before proceeding.
Batch updates: Use the batch update endpoint to modify multiple records in a single request for better performance.
Error handling: Implement proper error handling for conflict errors (409) which can occur if concurrent changes are made to the same records.

Troubleshooting

409 Conflict Error

A conflict error occurs when:

Trying to publish when no changes exist in draft.
Making concurrent modifications to the same records.
Attempting to create a review when one already exists.

Solution: Verify the current state of draft records and ensure no conflicting operations are in progress.

Records not appearing in published dataset

Publishing is asynchronous and might take a few seconds to complete.

Solution: Wait a moment and retry fetching published records, or implement polling with a short delay.

Permission errors

Solution: Verify that your API client has the necessary permissions to modify reference data and publish changes.

Next steps

Download the complete OpenAPI specification for all available endpoints.
Return to REST API Overview for an overview of all available APIs.
Explore Reference Data Management in the UI.

Was this page useful?