Auto Publish (with Publish API)

Introduction

The Publish API enables you to publish your project externally from Holistics, facilitating seamless integration with CI/CD workflows. By doing so, it leverages the full potential of an as-code approach, enhancing both automation and scalability.

This capability is particularly beneficial in scenarios such as below:

• Publish the latest update after merging PR into the master branch by integrating Publish API with the CI/CD workflow.
• Publish the latest update after new changes are pushed to master branch.

Setting up

Prerequisite - Set up the Holistics API

To use our Publish API or GitHub Action, you need to set up the Holistics API first. See Holistics API to set up the API correctly.

info

• For a simple and straightforward integration with your Git workflow, use the GitHub Action.
• For more customization and programmatic control over your publishing flow, use the Publish and Job API.

Using GitHub Action

In addition to the Publish API, we offer a GitHub Action that simplifies the integration of publishing process into your workflow.

The setup is quite simple, use the @holistics/publish-aml action in your GitHub Action config.

Here is an example:

name: Publish AML

on:
  push:
    branches:
      - master
  pull_request:
    branches:
      - master
    types:
      - closed

jobs:
  publish-aml:
    if: github.event.pull_request.merged == true || github.event_name == 'push'
    runs-on: ubuntu-latest

    env:
      HOLISTICS_API_KEY: ${{ secrets.HOLISTICS_API_KEY }}
      HOLISTICS_HOST: 'https://secure.holistics.io'
      # https://eu.holistics.io
      # https://us.holistics.io

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Publish AML
        uses: holistics/publish-[email protected]

This GitHub Action use the Publish API. See the Publishing Result for more details.

Using Publish API

To submit and retrieve the result of the Publish API

1. Submit the Publish API and receive a Job.
2. Poll the Job result using Job API until finished.

See our example of publish script to have a detailed look.

Publish API

Start the Publishing Flow by submitting this API

info

POST <holistics domain>/api/v2/aml_studio/projects/submit_deploy

This API triggers the publishing process in Holistics at the latest commit on your master branch - the default production branch in Holistics - and returns a Job.

{
  "job_id": number,
  "status": "string"
}

See API doc

Retrieve Publishing Results

The publishing results can be retrieved via Job API. Keep polling until you receive the result.

info

GET jobs/<job_id>/result

See API doc

• If the publishing process hasn’t been finished, it returns the status

  {
      "status": "running"
  }
• If the publishing process is complete, it returns the publishing result

Publishing Results

Publish Success

The publishing process is successful, you can go to the Reporting page to see your latest changes.

example

{
    "status": "success", // job status
    "error": null,
    "result": { // result of the publishing process
        "type": "Deploy",
        "data": {
            "status": "success", // publish status
            "data": {
                "preparing_production_job": {
                "job_id": 1445236,
                "status": "created"
                },
                "objects_status": [
                    {
                        "id": 27711,
                        "type": "Dashboard",
                        "uname": "ecommerce_dashboard",
                        "title": "Ecommerce",
                        "status": "updated"
                    }
                ]
            },
            "target_commit": "78ad9632735f8be605d71f6da4ccc762dc501efa"
        }
    }
}

• object_status: indicate objects that are updated or created in this publishing process. Currently, Holistics only supports status for the Canvas Dashboard.
• target_commit: target version of the publishing process.

Error - Syntax Error

There is a syntax error in your project. Please correct it and try publishing again.

example

{
    "status": "success", // job status
    "error": null,
    "result": { // result of the publishing process
        "type": "Deploy",
        "data": {
            "status": "error",  // publish status
            "error_type": "syntax_error",
            "error_details": {
                "diagnostics": [
                    {
                        "category": "Error",
                        "code": 1000,
                        "message": "Unexpected ';'",
                        "filePath": "/ecommerce_dashboard.page.aml", // file path contain the error
                        "start": 1469, // offset of the error in the code
                        "end": 1470 // offset of the error in the code
                    }
                ]
            },
            "target_commit": "0bf1e7421b78eea7d9ce4ac9d07db9584e5c5d76"
        }
    }
}

Error - Dashboard Mapping Error

This error occurs when attempting to delete a Dashboard with dependencies (such as Shareable Links or Embedded Analytics). Please review the code or remove the Dashboard’s dependencies before proceeding.

example

{
    "status": "success",  // job status
    "error": null,
    "result": { // result of the publishing process
        "type": "Deploy",
        "data": {
            "status": "error", // publish status
            "error_type": "dashboard_mapping",
            "error_details": {
                "dependants": [
                    {
                        "type": "Dashboard",
                        "id": 27711,
                        "uname": "ecommerce_dashboard", // the dashboard that is being deleted
                        "title": "Ecommerce",
                        "dependencies": [
                            {
                                "type": "ShareableLink",
                                "id": 27700
                            }
                        ]
                    }
                ],
                "message": "Failed to delete objects with dependencies"
            },
            "target_commit": "8ca2bad5fb0e7a9f1c37e92b42f29ddcf5c022d3"
        }
    }
}

Error - Dataset Mapping error

This error occurs when attempting to delete a dataset that is currently in use by a Report or Dashboard. Please review the code or perform Dataset Mapping to proceed.

example

{
    "status": "success", // job status
    "error": null,
    "result": { // result of the publishing process
        "type": "Deploy",
        "data": {
            "status": "error", // publish status
            "error_type": "dataset_mapping",
            "error_details": {
                "message": "Failed to deploy: Need to map production dataset to deploying dataset",
                "is_orphaned": true,
                "orphaned_dataset": [
                    {
                        "id": 27678,
                        "uname": "ecommerce", // being deleted dataset
                        "title": "Ecommerce Dataset",
                        "reports": [ // this dataset is being consumed in some reports
                            {
                                "id": 28943,
                                "title": "Email",
                            }
                        ],
                    }
                ],
                "deploying_datasets": [
                    // list of publishing dataset
                    "ecommerce_rename"
                ]
            },
            "target_commit": "c3901ea88f86c7293bced31452a88e19a22b8731"
        }
    }
}

To perform Dataset Mapping, it’s easier to use the:

• Reporting Validation
• or Dataset Mapping UI in Holistics App.

Other Errors

Error in Dashboard

{
    "status": "failure",
    "error": "Dashboard \"ecommerce_dashboard\": Block \"v1\": Field !fields[0]: Referencing to an invalid field (email_error) of data model ecommerce_users in dataset ecommerce",
    "result": {
        "type": "Deploy",
        "data": null
    }
}