Automation Setup Guide

Configure automated workflows, actions, webhooks, and navigation in the DataMagik platform.

Overview

DataMagik automations allow you to trigger actions based on events in your application. Common use cases include:

Document generation triggered by form submissions
Navigation to specific pages after actions complete
Webhooks to external systems (CRM, email, notifications)
Multi-step workflows with chained actions
Conditional logic based on data values

Key Concepts

Automation: A trigger that watches for specific events Action: A response executed when automation triggers Navigation Action: Redirects user to a URL Webhook Action: Sends HTTP request to external endpoint

Automations

Automations define when actions should execute.

Automation Types

TypeTriggerUse CaseForm SubmitUser submits formGenerate document, send notificationButton ClickUser clicks buttonNavigate to page, trigger webhookDocument GeneratedDocument completesSend email, update CRMStatus ChangeRecord status changesNotification, workflow stepScheduleTime-basedReports, reminders

Automation Structure

{
  "automation_id": 123,
  "name": "Generate Invoice on Order",
  "trigger_type": "form_submit",
  "trigger_config": {
    "form_id": "order_form",
    "conditions": [
      {
        "field": "status",
        "operator": "equals",
        "value": "confirmed"
      }
    ]
  },
  "actions": [
    {
      "action_id": 1,
      "action_type": "webhook",
      "sort_order": 1
    },
    {
      "action_id": 2,
      "action_type": "navigation",
      "sort_order": 2
    }
  ],
  "is_active": true
}

Actions

Actions are steps executed when an automation triggers.

Action Types

1. Navigation Actions

Redirect users to a specific URL, optionally passing data from the current screen.

Properties:

nav_url: Target URL (can include parameters)
new_window: Open in new browser window
new_tab: Open in new tab
required_url_params: Parameters that must be provided
url_params_to_pass: Screen data to pass as URL parameters
static_values: Fixed values to include in URL

2. Webhook Actions

Send HTTP requests to external endpoints.

Properties:

webhook_url: Target endpoint URL
http_method: GET, POST, PUT, DELETE
auth_type: None, API Key, Bearer Token, Basic Auth
headers: Custom HTTP headers
body_template: Request body (for POST/PUT)
timeout_seconds: Request timeout
retry_config: Retry logic for failures

Creating Automations

Step 1: Define the Automation

Create an automation in the platform UI or via API:

POST /api/automations
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "name": "Order Confirmation Flow",
  "description": "Generate invoice and navigate to confirmation page",
  "trigger_type": "form_submit",
  "trigger_config": {
    "form_id": "checkout_form"
  },
  "is_active": true
}

Step 2: Add Actions

Attach actions to the automation:

POST /api/automations/{automation_id}/actions
Content-Type: application/json

{
  "action_type": "webhook",
  "action_name": "Generate Invoice",
  "sort_order": 1,
  "webhook_config": {
    "webhook_url": "https://data-magik.com/api/document-designer/generate",
    "http_method": "POST",
    "auth_type": "bearer",
    "headers": {
      "Content-Type": "application/json"
    },
    "body_template": {
      "template_id": "{{template_id}}",
      "data": {
        "order_id": "{{screen.order_id}}",
        "customer_name": "{{screen.customer_name}}",
        "total": "{{screen.total}}"
      }
    }
  }
}

Step 3: Configure Navigation

Add navigation action to redirect after webhook:

POST /api/automations/{automation_id}/actions
Content-Type: application/json

{
  "action_type": "navigation",
  "action_name": "Go to Confirmation",
  "sort_order": 2,
  "navigation_config": {
    "nav_url": "/order/confirmation",
    "new_tab": false,
    "url_params_to_pass": ["order_id", "customer_email"],
    "static_values": {
      "status": "success"
    }
  }
}

Action Configuration

Navigation Actions

Basic Navigation

Redirect to a fixed URL:

{
  "nav_url": "/dashboard",
  "new_window": false,
  "new_tab": false
}

Navigation with Parameters

Pass data from current screen:

{
  "nav_url": "/orders/details",
  "url_params_to_pass": ["order_id", "customer_id"],
  "static_values": {
    "view": "full",
    "tab": "details"
  }
}

Resulting URL:

/orders/details?order_id=12345&customer_id=67890&view=full&tab=details

External Navigation

Open external URL in new tab:

{
  "nav_url": "https://external-system.com/tracking/{{tracking_number}}",
  "new_tab": true,
  "url_params_to_pass": ["tracking_number"]
}

Required Parameters

Ensure required data is available:

{
  "nav_url": "/invoice/view",
  "required_url_params": ["invoice_id", "company_id"],
  "url_params_to_pass": ["invoice_id", "company_id"]
}

If required parameters are missing, navigation will fail with an error.

Webhook Actions

Simple Webhook

POST to endpoint with static data:

{
  "webhook_url": "https://api.example.com/notifications",
  "http_method": "POST",
  "auth_type": "none",
  "headers": {
    "Content-Type": "application/json"
  },
  "body_template": {
    "event": "order_created",
    "timestamp": "{{now}}"
  }
}

Authenticated Webhook

Use API key authentication:

{
  "webhook_url": "https://api.example.com/orders",
  "http_method": "POST",
  "auth_type": "api_key",
  "auth_config": {
    "header_name": "X-API-Key",
    "api_key": "your_api_key_here"
  },
  "headers": {
    "Content-Type": "application/json"
  },
  "body_template": {
    "order_id": "{{screen.order_id}}",
    "customer": {
      "name": "{{screen.customer_name}}",
      "email": "{{screen.customer_email}}"
    },
    "items": "{{screen.items}}",
    "total": "{{screen.total}}"
  }
}

Bearer Token Authentication

{
  "auth_type": "bearer",
  "auth_config": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Basic Authentication

{
  "auth_type": "basic",
  "auth_config": {
    "username": "api_user",
    "password": "api_password"
  }
}

Dynamic Body Template

Use template variables to include screen data:

{
  "body_template": {
    "event_type": "document_generated",
    "document": {
      "template_id": "{{template_id}}",
      "document_id": "{{document_id}}",
      "download_url": "{{download_url}}"
    },
    "user": {
      "id": "{{screen.user_id}}",
      "name": "{{screen.user_name}}"
    },
    "metadata": {
      "generated_at": "{{now}}",
      "company_id": "{{screen.company_id}}"
    }
  }
}

Retry Configuration

Configure retry logic for failed requests:

{
  "retry_config": {
    "max_retries": 3,
    "initial_delay_seconds": 1,
    "max_delay_seconds": 60,
    "backoff_multiplier": 2,
    "retry_on_status_codes": [500, 502, 503, 504]
  }
}

Retry Behavior:

Attempt 1: Immediate
Attempt 2: After 1 second
Attempt 3: After 2 seconds
Attempt 4: After 4 seconds

Webhook Setup

Testing Webhooks

Use tools like webhook.site or RequestBin to test:

Go to https://webhook.site
Copy the unique URL
Use as webhook_url in configuration
Trigger automation
View received request in webhook.site

Webhook Security

Validate Webhook Signatures

Include signature in headers:

{
  "headers": {
    "X-Webhook-Signature": "{{signature}}"
  }
}

Calculate signature in your endpoint:

const crypto = require('crypto');

function validateSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return signature === expectedSignature;
}

IP Whitelisting

Restrict webhook receivers to specific IPs:

DataMagik Platform IPs: 
- 52.1.2.3
- 52.1.2.4

Navigation Configuration

URL Parameter Mapping

Map screen data to URL parameters:

{
  "nav_url": "/records/edit",
  "url_params_to_pass": {
    "id": "record_id",        // screen.record_id -> ?id=...
    "type": "record_type",     // screen.record_type -> ?type=...
    "view": "default_view"     // screen.default_view -> ?view=...
  },
  "static_values": {
    "mode": "edit",
    "source": "automation"
  }
}

Input Screen Data:

{
  "record_id": "12345",
  "record_type": "invoice",
  "default_view": "details"
}

Output URL:

/records/edit?id=12345&type=invoice&view=details&mode=edit&source=automation

Conditional Navigation

Use different URLs based on conditions:

{
  "nav_url": "{{screen.status === 'approved' ? '/approved' : '/pending'}}",
  "url_params_to_pass": ["request_id"]
}

Navigation Targets

Control where navigation opens:

{
  "new_window": true,    // Opens in new browser window
  "new_tab": false       // Opens in current window/tab
}

{
  "new_window": false,
  "new_tab": true        // Opens in new tab (same window)
}

Examples

Example 1: Invoice Generation Workflow

Scenario: User submits order form → Generate invoice → Email customer → Show confirmation

Automation Configuration:

{
  "name": "Order to Invoice",
  "trigger_type": "form_submit",
  "trigger_config": {
    "form_id": "order_form"
  },
  "actions": [
    {
      "sort_order": 1,
      "action_type": "webhook",
      "action_name": "Generate Invoice",
      "webhook_config": {
        "webhook_url": "https://data-magik.com/api/document-designer/generate",
        "http_method": "POST",
        "auth_type": "bearer",
        "body_template": {
          "template_id": "1097823044285431810",
          "format": "pdf",
          "data": {
            "order_id": "{{screen.order_id}}",
            "customer_name": "{{screen.customer_name}}",
            "items": "{{screen.items}}",
            "total": "{{screen.total}}"
          },
          "return_type": "url",
          "priority": "high"
        }
      }
    },
    {
      "sort_order": 2,
      "action_type": "webhook",
      "action_name": "Send Email",
      "webhook_config": {
        "webhook_url": "https://api.sendgrid.com/v3/mail/send",
        "http_method": "POST",
        "auth_type": "bearer",
        "body_template": {
          "personalizations": [{
            "to": [{"email": "{{screen.customer_email}}"}]
          }],
          "from": {"email": "billing@company.com"},
          "subject": "Your Invoice #{{screen.order_id}}",
          "content": [{
            "type": "text/plain",
            "value": "Thank you for your order. Invoice attached."
          }]
        }
      }
    },
    {
      "sort_order": 3,
      "action_type": "navigation",
      "action_name": "Show Confirmation",
      "navigation_config": {
        "nav_url": "/order/confirmation",
        "url_params_to_pass": ["order_id"],
        "static_values": {
          "status": "success"
        }
      }
    }
  ]
}

Example 2: Document Approval Workflow

Scenario: Manager approves document → Update status → Notify submitter → Redirect to dashboard

{
  "name": "Document Approval Flow",
  "trigger_type": "button_click",
  "trigger_config": {
    "button_id": "approve_button"
  },
  "actions": [
    {
      "sort_order": 1,
      "action_type": "webhook",
      "action_name": "Update Status",
      "webhook_config": {
        "webhook_url": "https://your-api.com/documents/{{screen.document_id}}/status",
        "http_method": "PUT",
        "body_template": {
          "status": "approved",
          "approved_by": "{{screen.approver_id}}",
          "approved_at": "{{now}}"
        }
      }
    },
    {
      "sort_order": 2,
      "action_type": "webhook",
      "action_name": "Notify Submitter",
      "webhook_config": {
        "webhook_url": "https://your-api.com/notifications",
        "http_method": "POST",
        "body_template": {
          "user_id": "{{screen.submitter_id}}",
          "type": "approval",
          "message": "Your document has been approved by {{screen.approver_name}}"
        }
      }
    },
    {
      "sort_order": 3,
      "action_type": "navigation",
      "action_name": "Return to Dashboard",
      "navigation_config": {
        "nav_url": "/dashboard",
        "static_values": {
          "notification": "Document approved successfully"
        }
      }
    }
  ]
}

Example 3: Multi-System Integration

Scenario: Customer places order → Create in CRM → Generate invoice → Update inventory → Send confirmation

{
  "name": "Complete Order Flow",
  "actions": [
    {
      "sort_order": 1,
      "action_type": "webhook",
      "action_name": "Create CRM Record",
      "webhook_config": {
        "webhook_url": "https://crm.example.com/api/orders",
        "http_method": "POST",
        "auth_type": "api_key",
        "body_template": {
          "customer_id": "{{screen.customer_id}}",
          "order_data": "{{screen.order_data}}",
          "source": "web_form"
        }
      }
    },
    {
      "sort_order": 2,
      "action_type": "webhook",
      "action_name": "Generate Invoice",
      "webhook_config": {
        "webhook_url": "https://data-magik.com/api/document-designer/generate",
        "http_method": "POST",
        "body_template": {
          "template_id": "invoice_template",
          "data": "{{screen}}"
        }
      }
    },
    {
      "sort_order": 3,
      "action_type": "webhook",
      "action_name": "Update Inventory",
      "webhook_config": {
        "webhook_url": "https://inventory.example.com/api/update",
        "http_method": "POST",
        "body_template": {
          "items": "{{screen.items}}",
          "action": "decrement"
        }
      }
    },
    {
      "sort_order": 4,
      "action_type": "navigation",
      "action_name": "Show Confirmation",
      "navigation_config": {
        "nav_url": "/order/success",
        "url_params_to_pass": ["order_id", "invoice_url"]
      }
    }
  ]
}

Best Practices

1. Action Ordering

Put critical actions first (data creation/updates)
Place notifications after data operations
Navigation should be last

2. Error Handling

Configure retry logic for webhooks
Set appropriate timeouts
Handle failures gracefully
Log errors for debugging

3. Security

Use authentication for webhooks
Validate webhook signatures
Encrypt sensitive data in transit
Use HTTPS for all webhook URLs

4. Performance

Keep action chains short (< 5 actions)
Use async processing for slow operations
Set reasonable timeouts
Monitor execution times

5. Testing

Test each action individually
Test complete automation flow
Verify error scenarios
Check navigation paths

6. Documentation

Name actions clearly
Document expected data structure
Note any dependencies
Record webhook endpoints

Troubleshooting

Action Not Executing

Problem: Automation triggers but action doesn't run

Solutions:

Check action is enabled
Verify sort_order is correct
Check previous action didn't fail
Review automation logs

Webhook Timeout

Problem: Webhook request times out

Solutions:

Increase timeout setting
Check endpoint is accessible
Verify network connectivity
Test endpoint independently

Navigation Not Working

Problem: User not redirected after action

Solutions:

Verify nav_url is correct
Check required params are provided
Test URL manually
Check for JavaScript errors

Missing URL Parameters

Problem: Parameters not passed to navigation URL

Solutions:

Verify field names match screen data
Check url_params_to_pass configuration
Ensure data exists on screen
Test with static values first

Webhook Authentication Fails

Problem: Webhook returns 401/403

Solutions:

Verify auth_type is correct
Check credentials are valid
Test authentication separately
Review API documentation

Next Steps

Review API Reference for detailed endpoint documentation
Check N8N Integration for workflow automation
Explore Starter Templates for template examples

Need Help? Contact support or review the automation logs in the platform for debugging information.

Automation Setup Guide

Table of Contents

Overview

Key Concepts

Automations

Automation Types

Automation Structure

Actions

Action Types

1. Navigation Actions

2. Webhook Actions

Creating Automations

Step 1: Define the Automation

Step 2: Add Actions

Step 3: Configure Navigation

Action Configuration

Navigation Actions

Basic Navigation

Navigation with Parameters

External Navigation

Required Parameters

Webhook Actions

Simple Webhook

Authenticated Webhook

Bearer Token Authentication

Basic Authentication

Dynamic Body Template

Retry Configuration

Webhook Setup

Testing Webhooks

Webhook Security

Validate Webhook Signatures

IP Whitelisting

Navigation Configuration

URL Parameter Mapping

Conditional Navigation

Navigation Targets

Examples

Example 1: Invoice Generation Workflow

Example 2: Document Approval Workflow

Example 3: Multi-System Integration

Best Practices

1. Action Ordering

2. Error Handling

3. Security

4. Performance

5. Testing

6. Documentation

Troubleshooting

Action Not Executing

Webhook Timeout

Navigation Not Working

Missing URL Parameters

Webhook Authentication Fails

Next Steps