Ataccama ONE Agentic Cloud Portal ONE Desktop ONE DQ&C ONE MDM ONE RDM ONE Runtime Server
User Community Service Desk Downloads

Transformation Plans API

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.

The Transformation Plans API allows you to programmatically trigger execution of published transformation plans in Ataccama ONE. This enables you to integrate data transformations into your automated workflows and orchestration systems.

Before using the Transformation Plans API, configure authentication as described in API Authentication.

API base URL

All Transformation Plans API endpoints are accessed through the following base URL:

https://{your-environment}.ataccama.one/api/transformations/v1

Replace {your-environment} with your environment identifier from the Ataccama Cloud Portal.

Trigger plan execution

Initiate an asynchronous execution of a published transformation plan.

Request
curl -X POST "https://{your-environment}.ataccama.one/api/transformations/v1/plans/{planUrn}/executions" \
  -H "Authorization: Bearer {access_token}"
Path parameters
Parameter Type Required Description

planUrn

string

Yes

URN identifier of the transformation plan. For example: urn:ata:{your-tenant}:transformations:plan:01924b84-6f7e-7c0c-8f9d-3a2b4c5d6e7f.
Response 202 Accepted
{
  "workflowUrn": "urn:ata:acme-corp:processing:workflow:123e4567-e89b-12d3-a456-426614174000"
}
Response fields
Field Type Description

workflowUrn

string

URN of the processing workflow. You can use this to track execution status in the Processing Center in the Ataccama ONE platform.

The execution runs asynchronously: the transformation plan starts executing in the background.

Monitor its progress in the Processing Center in Ataccama ONE.

Find transformation plan URNs

You can find transformation plan URNs in the Ataccama ONE platform:

  1. Go to Manage reference data > Data transformation > Plans.

  2. Select the transformation plan you want to execute.

  3. The plan URN is displayed in the plan details or can be found in the URL.

Alternatively, you can use the web application to copy the plan URN directly from the plan’s properties.

Complete example

Here’s a complete example of executing a transformation plan:

#!/bin/bash

# Configuration
ENVIRONMENT="your-environment"
REALM="your-realm"
CLIENT_ID="your-client-id"
CLIENT_SECRET="your-client-secret"
PLAN_URN="urn:ata:your-tenant:transformations:plan:01924b84-6f7e-7c0c-8f9d-3a2b4c5d6e7f"

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

# 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. Trigger transformation plan execution
echo "Triggering transformation plan execution..."
EXECUTION_RESPONSE=$(curl -s -X POST "${BASE_URL}/api/transformations/v1/plans/${PLAN_URN}/executions" \
  -H "Authorization: Bearer $TOKEN")

echo "Execution response:"
echo "$EXECUTION_RESPONSE" | jq '.'

WORKFLOW_URN=$(echo "$EXECUTION_RESPONSE" | jq -r '.workflowUrn')
echo "Workflow URN: $WORKFLOW_URN"
echo "Monitor execution progress in the Processing Center in the Ataccama ONE user interface."

Example: Schedule transformation via external orchestrator

Integrate transformation plan execution into external orchestration tools like Apache Airflow, Azure Data Factory, or AWS Step Functions:

Airflow DAG example (Python)
from airflow import DAG
from airflow.operators.http_operator import SimpleHttpOperator
from datetime import datetime, timedelta

default_args = {
    'owner': 'data-team',
    'depends_on_past': False,
    'start_date': datetime(2025, 1, 1),
    'retries': 1,
    'retry_delay': timedelta(minutes=5),
}

dag = DAG(
    'ataccama_transformation',
    default_args=default_args,
    schedule_interval='0 2 * * *',  # Daily at 2 AM
    catchup=False,
)

# Trigger transformation plan
trigger_transformation = SimpleHttpOperator(
    task_id='trigger_transformation',
    http_conn_id='ataccama_one',
    endpoint='/api/transformations/v1/plans/{{ var.value.plan_urn }}/executions',
    method='POST',
    headers={"Authorization": "Bearer {{ var.value.api_token }}"},
    response_check=lambda response: response.status_code == 202,
    dag=dag,
)

Use cases

Automated data pipeline

Trigger transformation plans as part of your data pipeline:

  1. Extract data from source systems.

  2. Trigger Ataccama transformation plan to cleanse and standardize data.

  3. Load transformed data into the target system.

Event-driven transformation

Execute transformations in response to events:

  1. File arrives to cloud storage.

  2. Event triggers transformation plan via API.

  3. Transformed data is exported to its destination.

Scheduled batch processing

Replace or supplement scheduled executions with external orchestration:

  1. External scheduler (cron, Airflow, etc.) triggers API call.

  2. Transformation plan executes.

  3. Results can be monitored in the Processing Center.

Cross-system integration

Coordinate transformations with other systems:

  1. System A completes processing.

  2. API call triggers Ataccama transformation.

  3. System B can be notified via external orchestration tool.

Error handling

The API returns standard HTTP status codes and problem details for errors:

Status code Description

202 Accepted

Execution initiated successfully.

400 Bad Request

Invalid plan URN format or request parameters.

401 Unauthorized

Missing or invalid authentication token.

403 Forbidden

Insufficient permissions. User does not have permission to execute the plan.

404 Not Found

Transformation plan not found.

500 Internal Server Error

Unexpected server error during execution.
Error response example
{
  "type": "RESOURCE_NOT_FOUND",
  "title": "Resource Not Found",
  "detail": "Transformation plan with URN 'urn:ata:acme:transformations:plan:01924b84-6f7e-7c0c-8f9d-3a2b4c5d6e7f' was not found"
}

Permissions

To execute transformation plans via API, you need:

  • Valid API client credentials.

  • Permission to execute the specific transformation plan.

  • Access to the catalog items and resources used by the transformation plan.

Configure permissions in the Ataccama Cloud Portal under user and group settings.

Best practices

  • Monitor execution status: Track workflow progress in the Processing Center in Ataccama ONE.

  • Implement retries: Add retry logic for transient failures (network issues, temporary service unavailability).

  • Use idempotent designs: Design transformation plans so they can be be safely re-run in case of failures.

  • Log execution details: Store workflow URNs and execution details for troubleshooting and auditing.

  • Handle concurrent executions: Be aware that triggering multiple executions of the same plan might run them concurrently unless the plan has built-in locking.

  • Set up alerts: Configure monitoring alerts for failed executions in your orchestration system.

Limitations

  • Plans must be in PUBLISHED state to be executed via API.

  • Some plan types might not be executable via API (such as embedded plans).

  • Concurrent executions are subject to system resource limits.

  • Long-running transformations might timeout in external orchestration systems. Adjust timeout settings accordingly.

Next steps

Was this page useful?