Skip to main content

Creating Coginiti Actions

This guide explains how to create automated data workflows using Coginiti Actions to streamline your data processing tasks.

info

For technical details: Coginiti Actions Reference

Prerequisites​

  • SQL assets saved in your catalog

  • Database connections configured

  • Understanding of your workflow dependencies

Create a Basic Coginiti Action​

Step 1: Create the TOML File​

  1. Navigate to your catalog
  2. Navigate to the .actions folder
  3. Create a new file

creating_action_file.gif

  1. Add the basic structure:
[general]
    name = "retail_workflow"
    description = "Retail data pipeline: loads landing data, builds base layer, publishes mart and reports"

action_file_general.png

Step 2: Configure the Environment (optional)​

Add an [environment] section to specify which project environment to use for database connections.
The environment ID must match one defined in your project.toml:

[environment]
    id = "prod"
info

More about Coginiti Environments

action_file_environment.png

Step 3: Configure a Schedule (optional)​

Add a [schedule] section to run your action automatically.
When the [schedule] section is present, cron and misfire_policy are required.
timezone is optional but recommended for clarity:

[schedule]
    cron = "0 15 20 * * ?" 
    misfire_policy = "RUN_IMMEDIATELY"
    timezone = "Europe/Helsinki"

Cron format: sec min hour day month dayOfWeek

info

More about Cron format

misfire_policy options:

  • RUN_IMMEDIATELY — execute as soon as possible if the scheduled time was missed
  • SKIP — skip the missed execution and wait for the next scheduled time

Timezone: Use IANA timezone identifiers (DST rules applied). Common examples:

  • Americas: America/New_York, America/Chicago, America/Los_Angeles
  • Europe: Europe/London, Europe/Paris, Europe/Helsinki
  • Asia: Asia/Tokyo, Asia/Singapore, Asia/Dubai
  • UTC offsets: GMT+1, UTC-5, +05:30

action_file_schedule.png

Step 4: Define Your Jobs​

Add jobs for each logical unit of work:

[job.landing]
    steps = ["landing"]
    landing = { command = "run_asset", asset = "/run_scripts/landing" }

[job.base]
    depends_on = ["landing"]
    steps = ["base"]
    base = { command = "run_asset", asset = "/run_scripts/base" }

[job.mart]
    depends_on = ["base"]
    steps = ["mart"]
    mart = { command = "run_asset", asset = "/run_scripts/mart" }

action_file_jobs.png

Add Parameters to Your Workflow​

Define Parameters in Steps​

Pass runtime parameters to your assets using the parameters key. Parameter names must match the $parameter placeholders defined in your SQL asset.

[job.reports]
    depends_on = ["mart"]
    steps = ["report_daily_snapshot", "report_store_rankings", "report_customer_export"]
    report_daily_snapshot = { command = "run_asset", asset = "/run_scripts/report_daily_snapshot", parameters = { "$snapshot_date" = "2023-10-01", "$lookback_days" = "30", "$snapshot_type" = "monthly" } }
    report_store_rankings = { command = "run_asset", asset = "/run_scripts/report_store_rankings", parameters = { "$start_date" = "2022-01-01", "$end_date" = "2022-12-31", "$ranking_metric" = "sales_amount", "$top_n" = "50" } }
    report_customer_export = { command = "run_asset", asset = "/run_scripts/report_customer_export", parameters = { "$export_type" = "high_value", "$min_orders" = "10", "$min_sales" = "5000", "$include_contact_info" = "true" } }

action_file_jobs_parameters.png

Configure Job Dependencies​

Simple Dependencies​

[job.base]
    depends_on = ["landing"]

Multiple Dependencies​

[job.reports]
    depends_on = ["landing", "base", "mart"]

Complex Dependency Chains​

[job.landing]
    steps = ["landing"]
    landing = { command = "run_asset", asset = "/run_scripts/landing" }

[job.base]
    depends_on = ["landing"]
    steps = ["base"]
    base = { command = "run_asset", asset = "/run_scripts/base" }

[job.mart]
    depends_on = ["base"]
    steps = ["mart"]
    mart = { command = "run_asset", asset = "/run_scripts/mart" }

[job.reports]
    depends_on = ["mart"]
    steps = ["report_daily_snapshot", "report_store_rankings", "report_customer_export"]
    report_daily_snapshot = { command = "run_asset", asset = "/run_scripts/report_daily_snapshot", parameters = { "$snapshot_date" = "2023-10-01", "$lookback_days" = "30", "$snapshot_type" = "monthly" } }
    report_store_rankings = { command = "run_asset", asset = "/run_scripts/report_store_rankings", parameters = { "$start_date" = "2022-01-01", "$end_date" = "2022-12-31", "$ranking_metric" = "sales_amount", "$top_n" = "50" } }
    report_customer_export = { command = "run_asset", asset = "/run_scripts/report_customer_export", parameters = { "$export_type" = "high_value", "$min_orders" = "10", "$min_sales" = "5000", "$include_contact_info" = "true" } }

Organize Multiple Steps​

Sequential Steps in a Job​

Steps within a job execute in the order listed in the steps array. Use this to run multiple assets as a single logical unit:

[job.reports]
    depends_on = ["mart"]
    steps = ["report_daily_snapshot", "report_store_rankings", "report_customer_export"]
    report_daily_snapshot = { command = "run_asset", asset = "/run_scripts/report_daily_snapshot", parameters = { "$snapshot_date" = "2023-10-01", "$lookback_days" = "30", "$snapshot_type" = "monthly" } }
    report_store_rankings = { command = "run_asset", asset = "/run_scripts/report_store_rankings", parameters = { "$start_date" = "2022-01-01", "$end_date" = "2022-12-31", "$ranking_metric" = "sales_amount", "$top_n" = "50" } }
    report_customer_export = { command = "run_asset", asset = "/run_scripts/report_customer_export", parameters = { "$export_type" = "high_value", "$min_orders" = "10", "$min_sales" = "5000", "$include_contact_info" = "true" } }

Handle Different Scenarios​

Data Quality Workflow​

Embed data quality tests directly inside your run scripts alongside the publication steps. This ensures tests run immediately after each layer is loaded:

[general]
    name = "retail_workflow"
    description = "Retail data pipeline with integrated data quality checks"

[job.landing]
    steps = ["landing"]
    landing = { command = "run_asset", asset = "/run_scripts/landing" }

[job.base]
    depends_on = ["landing"]
    steps = ["base"]
    base = { command = "run_asset", asset = "/run_scripts/base" }

The landing run script publishes landing tables and immediately tests source data:

landing_file.png

The base run script publishes all base dimensions and runs consistency tests:

base_file.png

Parallel Processing Workflow​

Jobs may run in parallel. To run multiple reports simultaneously, split them into separate jobs instead of sequential steps within one job:

[general]
    name = "retail_reports_parallel"
    description = "Run all reports in parallel"

[job.report_daily_snapshot]
    depends_on = ["mart"]
    steps = ["report_daily_snapshot"]
    report_daily_snapshot = { command = "run_asset", asset = "/run_scripts/report_daily_snapshot", parameters = { "$snapshot_date" = "2023-10-01", "$lookback_days" = "30", "$snapshot_type" = "monthly" } }

[job.report_store_rankings]
    depends_on = ["mart"]
    steps = ["report_store_rankings"]
    report_store_rankings = { command = "run_asset", asset = "/run_scripts/report_store_rankings", parameters = { "$start_date" = "2022-01-01", "$end_date" = "2022-12-31", "$ranking_metric" = "sales_amount", "$top_n" = "50" } }

[job.report_customer_export]
    depends_on = ["mart"]
    steps = ["report_customer_export"]
    report_customer_export = { command = "run_asset", asset = "/run_scripts/report_customer_export", parameters = { "$export_type" = "high_value", "$min_orders" = "10", "$min_sales" = "5000", "$include_contact_info" = "true" } }

action_file_reports_parallel.png

Test Your Project Action​

Validate Configuration​

  1. Save your TOML file
  2. Verify syntax and asset references are correct
  3. Check that all dependencies are properly defined
warning

If required fields are missing or there are structural inconsistencies, the action file will be highlighted in red, and an error message will be available on hover.
action_file_error.png

Schedule for Testing​

  1. Schedule your project action like any other catalog asset
  2. Set an immediate or near-future execution time
  3. Monitor execution through the notification panel

scheduling_action_file.gif

Troubleshooting​

Common Issues​

Syntax Errors

  • Verify TOML syntax is correct
  • Ensure all strings are properly quoted
  • Check array formatting for depends_on and steps

Asset Path Errors

  • Verify asset paths match catalog structure
  • Ensure assets exist and are accessible
  • Use forward slashes in paths

Dependency Loops

  • Check that dependencies don't create circular references
  • Use dependency visualization if available

Parameter Errors

  • Ensure parameter names match SQL script placeholders
  • Verify parameter values are properly formatted
  • Check that required parameters are provided

Best Practices​

  • Use descriptive job and step names
  • Add meaningful descriptions to your workflows
  • Test with small datasets first
  • Keep jobs focused on single responsibilities
  • Document complex dependency relationships

See Coginiti Retail Project Complete Workflow Tutorial for real example.


tip

For more information about other exciting Coginiti features visit our documentation

Thank you for choosing us!​