NAV
shell python

Introduction

Welcome to the Advance API! You can use our API to access Advance API endpoints, which can get information on various measures, tasks, and teams.

We have language bindings in Shell, Ruby, Python, and JavaScript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

Get Access Token

# With shell, you can just pass the correct header with each request
subscriptionKey='...insert your subscription key here...'

response=$(curl 'https://api.advancedashboard.com/auth/v1/getToken' -H "Advance-Subscription-Key: $subscriptionKey")
expires_in=$(echo $response | json expires_in)
token=$(echo $response | json access_token)
echo $expires_in
echo $token

r = requests.post('https://api.advancedashboard.com/auth/v1/getToken', headers={
  'Advance-Subscription-Key': "subscription-key"
})

if r.status_code == 200:
  json_contents = r.json()
  token = json_contents['access_token']
else:
  raise Exception('There was a problem obtaining a token')

Make sure to replace "subscription-key" with your API key.

Advance uses API keys to allow access to the API. Please contact support@mckinneyrogers.com to get your API key. You must be an existing Advance Dashboard client in order to use the API.

Authorization: subscription-key

The token you receive will be valid for approximately 20 minutes. After this, you will need to renew the token by getting a new token.

Send Token Along With Requests

  curl "https://api.advancedashboard.com/data" -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" \
  -d $graphql


def get_headers(token):
    return {
        'Content-Type': 'application/json',
        'Cache-Control': 'no-cache',
        'Authorization': f'Bearer {token}',
        'Version': '2022-08-02'
    }

host = 'https://api.advancedashboard.com/data'
headers = get_headers(token)
r = requests.post(host, headers=headers, json=query)
json_response = r.json()

Advance expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer {token}

GraphQL Query Example

gql='{
    "query": "query {
        queryName {
          field1
          field2
          field3
        }
    }"
}'

# Remove all new line characters in order to make this a valid GraphQL query:
graphql=$(echo $gql | tr -d '\n')
echo $graphql


graphql_query = {
    "query": """query {
        queryName {
          field1
          field2
          field3
        }
    }"""
}

headers = get_headers(token)
r = requests.post(host, headers=headers, json=graphql_query)
response_json = response.json()
if 'errors' in response_json:
  raise Exception(response_json['errors'])
data = response_json['data']['queryName']

This is what a typical GraphQL query looks like. Also shown is how to check for errors in the query.

Query Name Description
ping Test if the endpoint is responding
version Check the version of the endpoint
tasks Get a list of tasks
task Get a single task
measures Get a list of measures
measure Get a single measure

Ping

GraphQL:

  query {
      ping
      version
  }

graphql='{"query":"query {ping version }"}'

curl "https://api.advancedashboard.com/data" -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" \
  -d $graphql



graphql = {
    "query": """query {
        ping
        version
        }
    }""",
}

headers = get_headers(token)
r = requests.post(host, headers=headers, json=graphql)
response_json = r.json()
if 'errors' in response_json:
    raise Exception(response_json['errors'])

print(response_json)

The above command returns JSON structured like this:

{
    "data": {
        "ping": "OK",
        "version": "This is version 2022-08-01. You requested version 2022-08-02."
    }
}

Makes a test query to see if you are able to connect, and get a response.

GraphQL:

query { ping version }

Tasks

Get All Tasks

query='{
    "query": "query ($tenantId: ID!, $missionId: ID, $onlySpecified: Boolean) {
        ping
        version
        tasks(tenantId: $tenantId, missionId: $missionId, onlySpecified: $onlySpecified) {
            id
            missionId
            name
            description
            taskCategoryId
            taskCategory { name colourHex }
            parentTaskId
            parentTask { id name }
            subTasks { id name }
            resourcedFromTask { id name }
            resourceId
            resourcedTasks { id name resource { id }}
            utcAccepted
            percentComplete
            start
            due
            done
            isPercentageCompleteFromResources
            isPercentageCompleteFromSubTasks
            sequence
            utcCreated
            utcUpdated
            version
            tags { name }
        }
    }",
    "variables": {
        "tenantId": "{guid}",
        "missionId": "{guid}",
        "onlySpecified": true
    }
}'
graphql=$(echo $query | tr -d '\n')
echo $graphql
curl "https://api.advancedashboard.com/data" -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" \
  -d $graphql

def getTasks(host, token, tenantId, missionId, onlySpecified=True):

    query = {
        "query": """query ($tenantId: ID!, $missionId: ID, $onlySpecified: Boolean) {
            ping
            version
            tasks(tenantId: $tenantId, missionId: $missionId, onlySpecified: $onlySpecified) {
                id
                missionId
                name
                description
                taskCategoryId
                taskCategory { name colourHex }
                parentTaskId
                parentTask { id name }
                subTasks { id name }
                resourcedFromTask { id name }
                resourceId
                resourcedTasks { id name resource { id }}
                utcAccepted
                percentComplete
                start
                due
                done
                isPercentageCompleteFromResources
                isPercentageCompleteFromSubTasks
                sequence
                utcCreated
                utcUpdated
                version
                tags { name }
            }
        }""",
        "variables": {
            "tenantId": tenantId,
            "missionId": missionId,
            "onlySpecified": onlySpecified
        }
    }

    headers = get_headers(token)
    response = requests.post(host, headers=headers, json=query)
    response_json = response.json()
    if 'errors' in response_json:
      raise Exception(response_json['errors'])
    tasks = response_json['data']['tasks']

The above command returns JSON structured like this:

{
    "data": {
        "tasks": [
          {
              "id": "4b6d8921-5714-4899-9f2a-304511f7ce50",
              "name": "Task text",
              "tags": [
                  {
                      "name": "Main Effort"
                  },
                  {
                      "name": "Jira:Story"
                  },
                  ...
              ]
          },
          {
              "id": "55778785-b169-467a-888c-c3be1d2e041b",
              "name": "Task text",
              "tags": [
                  {
                      "name": "Main Effort"
                  },
                  {
                      "name": "Jira:Story"
                  },
                  ...
              ]
          },
        ]
    }
}

This endpoint retrieves all tasks.

HTTP Request

POST https://api.advancedashboard.com/data

Query Parameters

Parameter Description
tenantId The tenant your data resides in
missionId Filter the tasks for this mission
onlySpecified If true then only include specified tasks, if false, then include all tasks

Get a Specific Task

query='{
    "query": "query ($tenantId: ID!, $id: ID!) {
        task(tenantId: $tenantId, id: $id) {
            id
            missionId
            name
            description
            taskCategoryId
            taskCategory { name colourHex }
            parentTaskId
            parentTask { id name }
            subTasks { id name }
            resourcedFromTask { id name }
            resourceId
            resourcedTasks { id name resource { id }}
            utcAccepted
            percentComplete
            start
            due
            done
            isPercentageCompleteFromResources
            isPercentageCompleteFromSubTasks
            sequence
            utcCreated
            utcUpdated
            version
            tags { name }
        }
    }",
    "variables": {
        "tenantId": "{guid}",
        "id": "{guid}",
    }
}'
graphql=$(echo $query | tr -d '\n')
echo $graphql
curl "https://api.advancedashboard.com/data" -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" \
  -d $graphql

def getTask(host, token, tenantId, taskId):

    query = {
        "query": """query ($tenantId: ID!, $id: ID!) {
            task(tenantId: $tenantId, id: $id) {
                id
                missionId
                name
                description
                taskCategoryId
                taskCategory { name colourHex }
                parentTaskId
                parentTask { id name }
                subTasks { id name }
                resourcedFromTask { id name }
                resourceId
                resourcedTasks { id name resource { id }}
                utcAccepted
                percentComplete
                start
                due
                done
                isPercentageCompleteFromResources
                isPercentageCompleteFromSubTasks
                sequence
                utcCreated
                utcUpdated
                version
                tags { name }
            }
        }""",
        "variables": {
            "tenantId": tenantId,
            "id": taskId
        }
    }

    headers = get_headers(token)
    response = requests.post(host, headers=headers, json=query)
    response_json = response.json()
    if 'errors' in response_json:
      raise Exception(response_json['errors'])
    task = response_json['data']['task']

The above command returns JSON structured like this:

{
    "data": {
        "task": {
            "id": "44ba0e35-9427-43f6-ae1f-143ebe5bae28",
            "name": "Task text",
            "tags": [
                {
                    "name": "Main Effort"
                },
                {
                    "name": "Jira:Story"
                }
            ],
            ...
        }
    }
}

This endpoint retrieves a specific task.

HTTP Request

POST https://api.advancedashboard.com/data

Query Parameters

Parameter Description
tenantId The tenant your data resides in
taskId The Id of the task you want to retrieve

Errors

The Advance API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The resource requested is hidden for administrators only.
404 Not Found -- The specified object could not be found.
405 Method Not Allowed -- You tried to access an object with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The requested object has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're making too many requests! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
shell python