This article will try to explain DevOps “branching” & “merging” using dashboard API calls.

Before we begin we need…

A dashboard that has some content targeted as needing “development” or changed in some way
Postman - a free utility for running API calls.

Dashboard

Currently, we need to “enable” Organisations in the dashboard repository. This article assumes this has been done.

We also need some existing content that we are going to branch to a new Organisation

In my example dashboard I have some Artist categories that are all built against a single data source that are in need of a revamp. I need to find the ID of the data connection.

In dashboard configuration → Data Connections, hover over that data connection that you want to export and make a note of the Data Source ID

Alternatively, simply double click on a data source, the Data Source ID is shown in the top right…

We have noted the Data Connection ID of the content we want to edit.

Appreciate that if we wanted to do the next steps manually we could but we want to create a repeatable process via the API.

Postman

Postman is a free utility that works with API calls. You can download & install or use the online version. Register and you’re away.

Our dashboard contains an API which we will utilise.

We will be creating a structure in Postman that will end up looking like this:

Start Postman

Create a New Collection - Call it DevOpsDemo
Create Sub Folders - Create Branch, Merge Branch & Delete Branch (as above)
- Hover over the DevOpsDemo folder, then click the 3 dots and select Add Folder
Set the Collection Authorisation:
- You can authenticate in many ways via Postman, this example simply sets the authorisation in the collection (highlighted in blue)
- Click the Authorisation tab, set Auth Type to Basic Auth and enter the appropriate values.
Setup Collection Variables
- Click the variable tab and add the following variables:
- MAIN_DC_ID with the value set to the ID of the Data Connection you want to “Branch”
- MAIN_ORG_ID with the value of your main organisation ID
- BRANCH_NAME with the value of your New Branch Name

We have a successfully created a collection and set it’s authentication and added some variables. Now we need to create some Postman Requests.

Create Postman Requests

Create Branch

We will need to create 4 postman requests within the folder “Create Branch”.

Postman Create Branch Requests.png

Authenicate-GetToken
- Hover over the folder called Create Branch, click the 3 dots and select Add Request which will create a request stub. Immediately rename it by hovering over the New Request, again click the 3 dots then click Rename and give it a name of Authenicate-GetToken
- Change it to be a POST request
- Enter the URL - this is where the variables become useful, simply enter:
  - {{DASHBOARD_URL}}{{DASHBOARD_API_PATH}}/tokens
  - Set the Authentication Type to Basic and enter references to the variables in Username and Password.
  - Add a little magic ! In the Scripts tab enter the code below which in simple terms grabs the dashboard token from the response of this POST request, which if we have supplied valid credentials, will have a value that we will capture and re-use in all subsequent API requests.
    - const jsonResponse = pm.response.json(); pm.collectionVariables.set("DASHBOARD_TOKEN", jsonResponse.token);

Test by clicking the Send button (Top-Right) - this needs to respond with a status code of 200 and show the returned token.

Export Main Data Connection
- As before, hover over the folder called Create Branch, click the 3 dots and select Add Request which will create a request stub. Immediately rename it by hovering over the New Request, again click the 3 dots then click Rename and give it a name of Export Main Data Connection
- Enter the URL - this is where the variables super useful, simply enter:
  - {{DASHBOARD_URL}}{{DASHBOARD_API_PATH}}/exportImportConnections/{{MAIN_DC_ID}}?orgId={{MAIN_ORG_ID}}
  - Set the Authentication Type to Bearer Token and enter the bearer token reference variable name.
  - Again, add a little magic to capture the exported output into a variable by way of a script. Click the script tab and enter the text below.
    let response = pm.response.json(); pm.collectionVariables.set("MAIN_DC_EXPORT_JSON", JSON.stringify(response));
Create Branch-Org
- As before, hover over the folder called Create Branch, click the 3 dots and select Add Request which will create a request stub. Immediately rename it by hovering over the New Request, again click the 3 dots then click Rename and give it a name of Create Branch-Org
- Change it to be a POST request (Image above if required)
- Enter the URL
  - {{DASHBOARD_URL}}{{DASHBOARD_API_PATH}}/organisations
  - Set the Authentication Type to Bearer Token and enter the bearer token reference variable name. (as above)
  - In the Body (tab) enter the following:
    { "name":{{BRANCH_NAME}}, "parentId": 1, "detachFromParent": false, "position": 1 }
  - In the Scripts (tab) enter the following :
    const jsonResponse = pm.response.json(); pm.collectionVariables.set("BRANCH_ID", jsonResponse.id);
    - This simply captures the id of the newly create branch and stores it in the Postman variable BRANCH_ID for later use.
Import Exported DC to Branch
- As before, hover over the folder called Create Branch, click the 3 dots and select Add Request which will create a request stub. Immediately rename it by hovering over the New Request, again click the 3 dots then click Rename and give it a name of Import Exported DC To Branch
- Change it to be a POST request (Image above if required)
- Enter the URL
  - {{DASHBOARD_URL}}{{DASHBOARD_API_PATH}}/exportImportConnections?orgid={{BRANCH_ID}}
  - Set the Authentication Type to Bearer Token and enter the bearer token reference variable name. (as above)
  - In the Body (tab) enter the following:
    { "json": {{MAIN_DC_EXPORT_JSON}} }

Execute each one of the Create Branch requests in turn.

Then check you dashboard has a NEW_BRANCH with the exported content.

You may need to re-apply the password to the imported Data Connection.

At this point you would now go to the newly imported branch content and make some changes, like editing charts, create new categories and charts etc. Keep the changes simple and make a note of what you did.

Once done we are ready to “Merge” the changes back into the Main “parent“

Merge Branch

We will need to create 3 postman requests within the folder “Merge Branch”.

Get Branch DC ID
- Hover over the folder called Merge Branch, click the 3 dots and select Add Request which will create a request stub. Immediately rename it by hovering over the New Request, again click the 3 dots then click Rename and give it a name of Get Branch ID
- Enter the URL
  - {{DASHBOARD_URL}}{{DASHBOARD_API_PATH}}/dataConnections?orgId={{BRANCH_ID}}
  - Set the Authentication Type to Bearer Token and enter the bearer token reference variable name.
  - Script - Click the script tab and enter the text below.
    let response = pm.response.json(); pm.collectionVariables.set("BRANCH_DC_ID", response[0].id);
Export Branch DC
- Hover over the folder called Merge Branch, click the 3 dots and select Add Request which will create a request stub. Immediately rename it by hovering over the New Request, again click the 3 dots then click Rename and give it a name of Merge Branch DC
- Enter the URL
  - {{DASHBOARD_URL}}{{DASHBOARD_API_PATH}}/exportImportConnections/{{BRANCH_DC_ID}}?orgid={{BRANCH_ID}}
  - Set the Authentication Type to Bearer Token and enter the bearer token reference variable name.
  - Script - Click the script tab and enter the text below which populates the variable BRANCH_DC_EXPORT_JSON with our edited content.
    let response = pm.response.json(); pm.collectionVariables.set("BRANCH_DC_EXPORT_JSON", JSON.stringify(response));
Export Branch DC
- Hover over the folder called Merge Branch, click the 3 dots and select Add Request which will create a request stub. Immediately rename it by hovering over the New Request, again click the 3 dots then click Rename and give it a name of Import Branch DC to Main
- Enter the URL
  - {{DASHBOARD_URL}}{{DASHBOARD_API_PATH}}/exportImportConnections/?orgid={{BRANCH_ID}}
  - Set the Authentication Type to Bearer Token and enter the bearer token reference variable name.
  - Body - The body of this request will pass the content via a variable. Enter the text as below:
    { "json": {{MAIN_DC_EXPORT_JSON}} }

Execute each one of the Merge Branch requests in turn.

Now, check you dashboard has the “updated” content in the “main” or top level organisation.

Delete Branch

At this point it would be typical to describe the steps to remove or delete the branch we created BUT…..

There is an ENHANCEMENT on the horizon to Delete an Organisation. It employs the use of “cascading deletes” which will ensure that all dependant objects “downstream” are deleted first, making the steps below obsolete.

Deletion of an organisation requires the use of recursion.

Delete all charts - Get all chart id’s and recursively delete.
Delete all Category Objects
Delete all Categories
Delete all Data Connection Objects (Columns)
Delete All Data Connections
Delete the branch

Below is an export of all the folders and requests from above. Simply download and Import into Postman, set the variables and give it a whirl.