Task Integration Guide

Developer & ISV

This guide explains how to build an HTTP endpoint that receives data from DataCentral's Action Tasks feature. When a user clicks a configured Power BI visual, DataCentral sends the visual's data and session context to your endpoint.

See the Action Tasks admin guide for how tasks are created and configured in the UI.

1. How It Works

An administrator creates an Action Task that links a Power BI visual to your endpoint URL.
A user views the report and clicks the configured visual.
DataCentral captures the visual's data and the user's session context.
DataCentral sends an HTTP request (GET or POST) to your endpoint with the captured data.

Delivery Modes

Action Tasks operate in one of two modes, configured by the administrator:

Interactive ("Load URL on top of report") — Your endpoint URL is opened in an iframe overlay on top of the report. Your endpoint should return HTML that the user can see and interact with. The overlay closes when the user dismisses it, and the report data is refreshed.
Non-interactive — DataCentral calls your endpoint server-side. The user sees no overlay. Use this for fire-and-forget integrations such as creating tickets, sending notifications, or updating external systems.

2. GET Requests

When the administrator selects the GET method, DataCentral appends data as URL query parameters.

Query Parameters

Parameter	Included when	Description
`sessionMetaData`	"Add session metadata" is enabled	Base64-encoded JSON containing the user's session context.
`sessionMetaDataSig`	"Add session metadata" is enabled	MD5 signature of the `sessionMetaData` value (see Verifying Signatures).
`visualPayload`	"Add visual payload" is enabled	Base64-encoded JSON containing the data exported from the clicked visual.
`visualPayloadSig`	"Add visual payload" is enabled	MD5 signature of the `visualPayload` value.

Example URL

https://your-endpoint.com/task?sessionMetaData=eyJyZXBvcnRJZCI6Li4ufQ%3D%3D&sessionMetaDataSig=a1b2c3d4...&visualPayload=eyJkYXRhIjpbLi4uXX0%3D&visualPayloadSig=e5f6a7b8...

3. POST Requests

When the administrator selects the POST method, DataCentral sends data as a JSON body with Content-Type: application/json.

Request Body Fields

Field	Included when	Description
`sessionMetaData`	"Add session metadata" is enabled	Base64-encoded JSON containing the user's session context.
`sessionMetaDataSig`	"Add session metadata" is enabled	MD5 signature of the `sessionMetaData` value (see Verifying Signatures).
`visualPayload`	"Add visual payload" is enabled	Base64-encoded JSON containing the data exported from the clicked visual.
`visualPayloadSig`	"Add visual payload" is enabled	MD5 signature of the `visualPayload` value.
`customMessage`	"Add custom message" is enabled	A static string configured by the administrator.

Example Request Body

{
  "sessionMetaData": "eyJyZXBvcnRJZCI6IjEyMzQiLCJ1c2VyTmFtZSI6ImFkbWluIn0=",
  "sessionMetaDataSig": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "visualPayload": "eyJkYXRhIjpbeyJDYXRlZ29yeSI6IkVsZWN0cm9uaWNzIn1dfQ==",
  "visualPayloadSig": "d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1",
  "customMessage": "Created from DataCentral report"
}

4. Session Metadata Structure

After Base64-decoding the sessionMetaData value, you get a JSON object with the following fields:

Field	Type	Description
`reportId`	`string`	The Power BI report ID.
`reportName`	`string`	Display name of the report.
`visualName`	`string`	Name of the visual that was clicked.
`userId`	`number`	DataCentral user ID.
`userName`	`string`	Login username.
`userDisplayName`	`string`	User's display name.
`tenancyName`	`string`	Tenant name.
`tenantId`	`number`	Numeric tenant ID.
`roleDisplayNames`	`string[]`	Role names assigned to the user.
`roleIds`	`number[]`	Role IDs assigned to the user.
`clientUrl`	`string`	The DataCentral frontend URL.
`timeStamp`	`string`	ISO 8601 timestamp of when the request was generated.

Example Decoded Metadata

{
  "reportId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reportName": "Sales Dashboard",
  "visualName": "chart1",
  "userId": 3,
  "userName": "admin",
  "userDisplayName": "John Doe",
  "tenancyName": "acme",
  "tenantId": 1,
  "roleDisplayNames": ["Admin", "Viewer"],
  "roleIds": [2, 8],
  "clientUrl": "https://acme.datacentral.ai",
  "timeStamp": "2026-06-22T12:00:00Z"
}

5. Visual Payload Structure

After Base64-decoding the visualPayload value, you get a JSON object containing the data exported from the clicked visual. The structure depends on the visual type and the export mode configured by the administrator.

Export Modes

The administrator controls the export mode by how they configure the visual name in the task settings:

Summarized data (default) — The aggregated values displayed in the visual.
Underlying data (visual name prefixed with +) — The detail-level, row-level data behind the visual.

info

The export mode is configured by the administrator when creating the task. The + prefix on the visual name controls whether summarized or underlying data is exported. As a developer, you receive whichever mode was configured — your endpoint should handle both formats.

Example: Summarized Data

{
  "data": [
    { "Category": "Electronics", "Total Sales": 45000 },
    { "Category": "Clothing", "Total Sales": 32000 }
  ]
}

Example: Underlying Data

{
  "data": [
    { "OrderId": 1001, "Product": "Laptop", "Category": "Electronics", "Price": 1200, "Date": "2026-06-01" },
    { "OrderId": 1002, "Product": "Phone", "Category": "Electronics", "Price": 800, "Date": "2026-06-02" },
    { "OrderId": 1003, "Product": "T-Shirt", "Category": "Clothing", "Price": 25, "Date": "2026-06-03" }
  ]
}

6. Verifying Signatures

Both the session metadata and visual payload include MD5 signatures for tamper detection. The signatures are computed using the tenant's passphrase — a shared secret configured in the tenant's security settings (Administration -> Security -> Encryption). Your administrator must share this passphrase with you out-of-band.

How Signatures Are Computed

DataCentral concatenates the raw Base64-encoded data with the tenant passphrase, then computes an MD5 hash of the combined string. The result is a lowercase hexadecimal string.

signature = MD5(base64Data + passPhrase)

Verification

To verify, reconstruct the same concatenation and compare the MD5 hash against the received signature.

const crypto = require('crypto');

function verifySignature(data, signature, passPhrase) {
  const expected = crypto
    .createHash('md5')
    .update(data + passPhrase)
    .digest('hex');
  return expected === signature;
}

GET Request Example

const url = new URL(request.url, `https://${request.headers.host}`);
const sessionMetaData = url.searchParams.get('sessionMetaData');
const sessionMetaDataSig = url.searchParams.get('sessionMetaDataSig');

if (!verifySignature(sessionMetaData, sessionMetaDataSig, YOUR_PASSPHRASE)) {
  return res.status(401).send('Invalid signature');
}

POST Request Example

const { sessionMetaData, sessionMetaDataSig } = req.body;

if (!verifySignature(sessionMetaData, sessionMetaDataSig, YOUR_PASSPHRASE)) {
  return res.status(401).send('Invalid signature');
}

Decoding After Verification

const metadata = JSON.parse(Buffer.from(sessionMetaData, 'base64').toString('utf8'));
const payload = JSON.parse(Buffer.from(visualPayload, 'base64').toString('utf8'));

warning

Always verify signatures before processing the payload. Reject requests with invalid signatures with a 401 response.

7. Responding to Requests

Interactive Mode

Your endpoint should return HTML (Content-Type: text/html). The response is rendered inside an iframe overlay on top of the report. Return a confirmation page, form, or status display.

DataCentral provides a built-in close button on the overlay. When the overlay is closed, DataCentral automatically refreshes the report data.

Closing the Overlay Programmatically

You can also close the overlay from your own code (e.g. after a form submission or a countdown) by sending a postMessage to the parent window:

window.parent.postMessage('close', '*');

This has the same effect as the built-in close button — it closes the iframe overlay and triggers a report data refresh.

Non-Interactive Mode

DataCentral calls your endpoint from the backend. Return an appropriate HTTP status code (200 for success, 4xx/5xx for errors). The response body is not shown to the user.

8. Security Considerations

Always verify signatures — Never trust payload contents without verifying the signature.
Timestamp validation — Check the timeStamp field in the session metadata. Reject requests older than a reasonable window (e.g., 5 minutes) to prevent replay attacks.
HTTPS only — Ensure your endpoint uses HTTPS. Requests contain user identity and potentially sensitive business data.
Passphrase management — Store the tenant passphrase securely using environment variables or a secret manager. Do not hard-code it in your application.
Input validation — Validate and sanitize all decoded payload data before using it in database queries, API calls, or HTML output.

1. How It Works​

Delivery Modes​

2. GET Requests​

Query Parameters​

Example URL​

3. POST Requests​

Request Body Fields​

Example Request Body​

4. Session Metadata Structure​

Example Decoded Metadata​

5. Visual Payload Structure​

Export Modes​

Example: Summarized Data​

Example: Underlying Data​

6. Verifying Signatures​

How Signatures Are Computed​

Verification​

GET Request Example​

POST Request Example​

Decoding After Verification​

7. Responding to Requests​

Interactive Mode​

Closing the Overlay Programmatically​

Non-Interactive Mode​

8. Security Considerations​