Data Reports - ExoSense GraphQL API

Overview

This post serves as a brief introduction to how the ExoSense GraphQL API and Reports features can be used in concert to enhance and automate interactions with your data outside of the ExoSense UI.


Note: When requesting a Signal Data Report, whether via the UI or the ExoSense GraphQL API, there is one key constraint which must be met: Any given Report of Signal data must fall within the “Signal Days” limit set for your Application Tier.

For example, with a limit of 600 Signal Days, a report targeting 10 Signals could encompass up to a 60 day period, while a report of 30 Signals would be limited up to 20 days, and so on.


General

When leveraging the ExoSense GraphQL API to request a Signal Data Report, use of system-defined identifiers for the target Asset(s) and Signal(s) will be required. To that end, we’ll start with some examples for deriving those identifiers for later use.

Note: It is recommended to always make explicit use of the Pagination input, where available.

Identify Target Asset(s)

While there are various ways to control the scope of a search for a given Asset (or set of them), in this example we’ll explore one way to find a single Asset’s ID using its name.

Using the text field of the AssetFilters input, the assets query will return a pre-filtered result set including only those Assets which contain a match for the specified string in either their name or description.

Query

query assets($pagination: Pagination, $filters: AssetFilters) {
  assets(pagination: $pagination, filters: $filters) {
    id
    name
  }
}

Variables

{
  "pagination": {
    "offset": 0,
    "limit": 100
  },
  "filters": {
    "text": "Example Asset"
  }
}

Response

{
  "data": {
    "assets": [
      {
        "name": "Example Asset",
        "id": "394a7c05-868f-41df-8b3a-7c9fe3de831c"
      }
    ]
  }
}

Identify Target Signal(s)

With a target Asset’s ID, the asset query can be used to derive the IDs, and other potentially useful context, of its Signals.

Query

query asset($id: ID!) {
  asset(id: $id) {
    id
    name
    signals {
      id
      name
      units {
        abbr
      }
    }
  }
}

Variables

{
  "id": "394a7c05-868f-41df-8b3a-7c9fe3de831c"
}

Response

{
  "data": {
    "asset": {
      "signals": [
        {
          "units": {
            "abbr": "A"
          },
          "name": "Current Draw",
          "id": "20fd773c-89fc-4a2b-88b4-de25ffad9a5a"
        },
        {
          "units": {
            "abbr": "psi"
          },
          "name": "Discharge Pressure",
          "id": "13bfab2b-4144-44a2-ba7c-0ac6bfecb67d"
        },
        {
          "units": {
            "abbr": "GPM"
          },
          "name": "Flow Rate",
          "id": "b4ab84f7-4078-4fcd-ad2d-8a841e4f7f43"
        },
        {
          "units": {
            "abbr": "°F"
          },
          "name": "Motor Bearing Temperature",
          "id": "15ad58b8-034a-40f4-909b-da050191fdb2"
        },
        {
          "units": {
            "abbr": "°F"
          },
          "name": "Pump Temperature",
          "id": "d15f3e93-8a04-4c8d-a6a1-1283b913e7b5"
        },
        {
          "units": {
            "abbr": "rpm"
          },
          "name": "Speed",
          "id": "86375d4a-b588-46f9-bc5d-a8440e291780"
        },
        {
          "units": {
            "abbr": "psi"
          },
          "name": "Suction Pressure",
          "id": "bd7aad17-391b-448d-ab3d-08fba1847c03"
        },
        {
          "units": {
            "abbr": "in/s"
          },
          "name": "Vibration RMS Peak",
          "id": "5c59c93c-2877-482d-8fa2-1bf8ded76acb"
        }
      ],
      "name": "Example Asset",
      "id": "394a7c05-868f-41df-8b3a-7c9fe3de831c"
    }
  }
}

On Demand Report

When an on demand report is requested, a job will be queued to generate it. The status of any given job can be queried and, once completed, a URL to download the resulting report can be retrieved.

Request On Demand Report

The createReport mutation takes a CreateReport input, the structure of which you can be referenced in the brief descriptions and example variables object below.

Field Descriptions:

  • start_timestamp and end_timestamp are both Unix epoch time integers (seconds).
    • In this case, they bound the request to a specific single day (2022-03-01).
    • Note: Recall the Signal Day limit mentioned at the beginning of this post.
  • timezone has two subfields of its own:
    • offset is an integer offset to be applied to the timestamps of the result data after it is pulled (e.g. -6 for GMT-06:00)
    • format is a standard date/time format string to be applied to the result data.
  • assetNames is an array of strings, providing the name(s) of any Asset(s) from which the target Signals are taken.
  • signals is an array of ExportSignal inputs, having their own subfields:
    • id is the Signal for which the column data will be generated.
    • name configures the column header for the Signal.
      • In this case, several pieces from the Signal context collected in the preceding example are combined:
        • {asset_name} - {signal_name} ({signal_unit_abbreviation})
        • Note: The inclusion of this extra context is optional.

Query

mutation createReport($report_info: CreateReport!) {
  createReport(report_info: $report_info) 
}

Variables

{
  "report_info": {
    "start_timestamp": 1646092800,
    "end_timestamp": 1646179200,
    "timezone": {
      "offset": 0,
      "format": "%Y-%m-%dT%H:%M:%S.%f%z"
    },
    "assetNames": [
      "Example Asset"
    ],
    "signals": [
      {
        "id": "20fd773c-89fc-4a2b-88b4-de25ffad9a5a",
        "name": "Example Asset - Current Draw (A)"
      },
      {
        "id": "13bfab2b-4144-44a2-ba7c-0ac6bfecb67d",
        "name": "Example Asset - Discharge Pressure (psi)"
      },
      {
        "id": "b4ab84f7-4078-4fcd-ad2d-8a841e4f7f43",
        "name": "Example Asset - Flow Rate (GPM)"
      }
    ]
  }
}

Response

{
  "data": {
    "createReport": "09124d04-a0a0-11ec-bfce-02598f76caed"
  }
}

Check Report Status

As needed, the reportStatus query can be used to understand the status of a given report. The UUID returned in response to a createReport mutation (see preceding example) serves as the job_id field value in this query.

Query

query reportStatus($job_id: ID!) {
  reportStatus(job_id: $job_id) {
    state
    length
  }
}

Variables

{
  "job_id": "09124d04-a0a0-11ec-bfce-02598f76caed"
}

Response

{
  "data": {
    "reportStatus": {
      "state": "completed",
      "length": 72486
    }
  }
}

Retrieve Report Download URL

Today, completed reports are downloaded using a pre-signed URL. A pre-signed URL for a given report can be retrieved using its job_id, with the expires_in field optionally allowing the default 600 second expiration window to be overridden if desired.

Query

query report($job_id: ID!, $expires_in: Int) {
  report(job_id: $job_id, expires_in: $expires_in)
}

Variables

{
  "job_id": "09124d04-a0a0-11ec-bfce-02598f76caed",
  "expires_in": 3600
}

Response

{
  "data": {
    "report": "https://s3.us-west-1.amazonaws.com/murano-content-service-prod/qq5jo11owdcw0000/export_1646936974.csv?response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAXP6RGEJ4JJMD2R5F%2F20220310%2Fus-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220310T183048Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=83c90ed0df66c07dc6edefe5e0009ec0b492c2276738aefb13555603addafbba"
  }
}

Download Report

For simplicity, this example makes use of the cURL command line tool to download the report, using the pre-signed URL, and store it in a local file.

curl "https://s3.us-west-1.amazonaws.com/murano-content-service-prod/qq5jo11owdcw0000/export_1646936974.csv?response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAXP6RGEJ4JJMD2R5F%2F20220310%2Fus-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220310T183048Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=83c90ed0df66c07dc6edefe5e0009ec0b492c2276738aefb13555603addafbba" > 2022-03-01-report-Example-Asset.csv
1 Like