Versions Compared

Version Old Version 5 New Version Current
Changes made by

Aaron DeYonker

james.holloway (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Note

THIS IS A REPRESENTATIVE QUERY FOR OUR FULLY FUNCTIONAL API. IT WILL NOT WORK UNTIL WE HAVE FULLY LAUNCHED THE API.

This sample query is to help understand complex query structure and the corresponding data returned through the API.

Retrieving Single Session data

query { viewer { organization { scenarioSessions { # INSERT everything below the `... on ScenarioSession` line vvquery { node(id: "ljmnV58GM_c4AEHHiZy0qiSoP9HN3CnK7dbuPMNxx_M=") { ... on ScenarioSession {
Code Block
Info

The following queries are SAMPLES. As a consumer of the Scope GraphQL API, you can design and use any properly formed query to retrieve the data that you require.

For more information, see “Introduction to the Scope GraphQL API“.

Table of Contents
minLevel1
maxLevel1

Scenario Sessions with Quiz Data

Problem

As an analyst, I want to returns scenario sessions but also include any quiz related data.

Solution

Adding in filters into the scenario session events associated with the session will allow for only quiz data related events to be returned.

This kind of large queries are pretty expensive when getting a long list so it's recommended to use a small page size (i.e. `first: 25`) and make several paginated queries.

Code Block
query {
  scenarioSessions(first: 25) {
    nodes {
      id
      databaseId
      duration
      endedAt
      externalData
      startedAt
      finishedAtendedAt
      duration
      idleDurationsessionType
      numberOfStepsPossiblecompletedSteps {
     numberOfStepsViewed   nodes {
  percentOfStepsViewed       state id
     externalData # NOTE: this}
is where the data passed from the}
System of Record can be found parts(first:      scenarioRelease1, orderBy: { attribute: "startedAt", direction: DESC}) {
   author     nodes  {
 publishedAt         scenario {databaseId
          authorcreatedBy {
            id
            name
          }
          descriptionuserInfo {
         name   latitude
       origin_group {    longitude
        name    deviceOs
      }      deviceModel
    published_at        devicePlatform
 }         type}
        version}
      }
      eventsscenario {
        nodesid
{        name
  attachments {     organization {
      author    slug
        fileContentType}
      }
     fileDownloadCount scenarioRelease {
        version
 fileFingerprint       sdkVersion
     fileName   workInstructionType
        type
fileSize        sequences {
   fileUpdatedAt       nodes {
    fileURL        id
    fileURLExpiresAt        name
    name        scenarioSteps(first: 1000) {
  organization            nodes owner{
            type    id
     }           deviceLocationname
{             altitude   orderIndex
         device {      type
        identifier        scenarioSequence {
     model             id
 organization               os  name
          }      }
      isSindowsExe          items(first: 1000) {
 latitude             longitude    nodes {
       platform             protocolid
            version        description
  }         }       }  type
    steps {         scenario_step {   }
       name         }
 orderIndex           scenarioSequence { }
           name }
          }
        }
 
      }
      }
    }
  }
}

Retrieving all data for all Sessions

Code Block
# To pull ALL scenario sessions for the org associated with currently authenticated user
query {
  viewer {steps(first: 1000, orderBy: {attribute: "startedAt", direction: ASC}) {
        nodes {
          id
     organization {    completed
  scenarioSessions {       duration
 # INSERT everything below the `... on ScenarioSession` line vv#completedItems {
To pull the details for a scenario sessions with id = "ljmnV58GM_c4AEHHiZy0qiSoP9HN3CnK7dbuPMNxx_M="
query nodes {
  node(id: "ljmnV58GM_c4AEHHiZy0qiSoP9HN3CnK7dbuPMNxx_M=") {     ... on ScenarioSession {  id
    startedAt       finishedAt }
     duration     }
 idleDuration       numberOfStepsPossible  scenarioStep {
   numberOfStepsViewed       percentOfStepsViewed  id
    state       externalData #name
NOTE: this is where the data passed from the System of Record can be found           type
            orderIndex
            scenarioReleasescenarioSequence {
              id
              name
    author        }
publishedAt
        scenario            items(first: 1000) {
              nodes {
                id
                description
                type
              }
            }
          }
          scenarioSessionEvents(
            first: 1000
            eventTypes: [QUIZ_ITEM_COMPLETE, CHECKLIST_ITEM_COMPLETE, SCREENSHOT_CAPTURED]
            orderBy: {attribute: "startedAt", direction: DESC}
          ) {
            nodes {
              barcode
              startedAt
              type
              value
              photo {
                fileUrl
              }
              scenarioStepItem {
                id
              }
            }
          }
        }
      } 
    }
  }
}

Retrieve Scenario Sessions from Public (or Private) Scenarios

Problem

As an analyst, I only want to retrieve the sessions of a scenario that is publicly visible (or private).

Solution

Adding in the publicVisibility argument into the scenarios query allows for the scenarios to be filtered appropriately.

Code Block
query {
  scenarios(first: 100, scenariosQueryArguments: { publicVisibility: true }) {
    nodes {
      sessions(first: 10) {
        nodes {
          id
          databaseId
          startedAt
          endedAt
          organization {
            id
            databaseId
            name
          }
          scenario {
            id
            databaseId
            name
          }
          user {
            id
            databaseId
            name
            username
          }
        }
      }
    } 
  }
}

Session Data that excludes certain email domains

Problem

As an analyst, I want a list of scenario sessions that are not created by user with an email domain like public.scope.com and are sorted by the scenario ID.

Solution

Unfortunately, our current API does not offer a way to filter by exclusion. However, it does provide a way to filter by inclusion, meaning that the query can be used to grab all sessions with a particular email domain. The query is grabbing the scenarios first, so the sessions will automatically be sorted by the scenario ID. However, scenarios and sessions must be paginated due to performance reasons:

Code Block
query {
  scenarios(first: 100, afterIndex: -1) {
    nodes {
      id
      databaseId
      name
      sessions(first: 25, afterIndex: -1, fullText: "@scopear.com") {
        nodes {
          id
          databaseId
          startedAt
          endedAt
          organization {
            id
            databaseId
            name
          }
          scenario {
            id
            databaseId
            name
          }
          user {
            id
            databaseId
            name
            username
          }
        }
      }    
    }
  }
}

Scenario Session Step Data With Detailed Information

Problem

I want to retrieve scenario sessions but with lots of detailed information.

Solution

By adding to the data returned from the query, a lot of details can be shown for each scenario session. However, the results should be paginated for performance reasons.

Code Block
query {
  scenarioSessions(first: 25, afterIndex: -1, fullText: "@scopear.com") {
    nodes {
      id
      databaseId
      startedAt
      endedAt
      duration
      organization {
        id
        databaseId
        name
      }
      scenario {
        id
        databaseId
        name
      }
      steps(first: 1000) {
        nodes {
          scenarioSessionPart {
            databaseId
            id
            userInfo {
              longitude
              latitude
            }
          }
          scenarioStep {
            orderIndex
            name
          }
          
        }
      }
      user {
        id
        databaseId
        name
        email
      }
    }
  }
}

Session Data Retrieval

Problem

As an analyst, I want to know which users have completed a particular Scenario so that I can issue credit to the users relating to the associated learning module in my system-of-record.

Solution

I will use a GraphQL client to retrieve Scenario Session data from the Scope GraphQL API which is not otherwise available in the Scope CMS user interface.

Procedure

...

  1. The GraphiQL client application is installed and configured to communicate with the Scope GraphQL API (see “Exploring the Graph”)

  2. The following query is executed:

    Code Block
    query {
  node(id: "INSERT_ID_OF_SCENARIO") {
    ... on

...

  1. Scenario {
      sessions {

...

  1.     nodes

...

  1. {

...

  1.     id

...

  1.     state

...

  1.

...

  1. user {
            id

...

  1.

...

  1. name

...

  1. }
        }
      }

...

  1.    }
  }
}

  2. The JSON response is reformatted to CSV (using any relevant tool) for merge with system-of-record data and/or reporting.

Retrieving A Single Scenario Session’s Data

Code Block
query  version
SampleScenarioSessionNodeQueryDemonstratingImportantFields($id: ID!) {
  node(id: $id) {
}    ... on ScenarioSession events {
      startedAt
 nodes {    endedAt
      attachmentsduration
{      idleDuration
      authornumberOfStepsPossible
      numberOfStepsViewed
     fileContentType percentOfStepsViewed
      state
    fileDownloadCount  externalData # NOTE: this is where query params passed from the fileFingerprintSystem of Record can be found
      scenarioRelease fileName{
        author {
  fileSize        id
    fileUpdatedAt      name
      fileURL  }
        publishedAt
 fileURLExpiresAt       scenario  {
   name       author {
    organization        id
    owner        name
    type      }
   }       description
   deviceLocation {      name
      altitude    originGroup {
       device {    id
          identifier  name
          }
 model         publishedAt
     organization   }
        type
  os      version
      }
      events {
    isSindowsExe    nodes {
       latitude   id
         longitude createdAt
          receivedAt
platform          type
  protocol        externalData
    version    }
      }
      steps {
}       } nodes {
    steps {     scenarioStep {
  scenario_step {         name
 name           orderIndex
            scenarioSequence {
              name
            }
          }
        }
      }
    }
  }
}# Example response!

Retrieving All Scenario Session Data

Code Block
query SampleAllScenarioSessionsQueryDemonstratingImportantFields {
  "data":viewer {
    organization {
"startedAt": "some value"    scenarioSessions "finishedAt": "some value"{
      "duration": "some value"nodes {
   "idleDuration": "some value"     "numberOfStepsPossible": "some value"startedAt
       "numberOfStepsViewed": "some value" endedAt
   "percentOfStepsViewed": "some value"     "state": "some value"duration
      "externalData": {   idleDuration
   # NOTE: this is where the data passednumberOfStepsPossible
from the System of Record can be "found": "some value" numberOfStepsViewed
   }     "scenarioRelease": { percentOfStepsViewed
     "author": "some value"   state
   "publishedAt": "some value"     externalData # "scenario"NOTE: {this is where query params passed from the System of "author": { 
Record can be found
         "id": "some value"
  scenarioRelease {
        "name": "some value"  author {
     }         "description": "some value"id
           "name": "some value" name
       "origin_group": {    }
       "name": "some value"   publishedAt
     }       scenario {
"published_at": "some value"       }     author {
"type": "some value"       "version": "some value"     }id
    "events": {        "nodes": {  name
       "attachments": {      }
     "author": "some value"       description
   "fileContentType": "some value"         name
 "fileDownloadCount": "some value"           "fileFingerprint": "some value"originGroup {
           "fileName": "some value"   id
       "fileSize": "some value"       name
   "fileUpdatedAt": "some value"         }
 "fileURL": "some value"           "fileURLExpiresAt": "some value"publishedAt
            "name": "some value"}
            "organization": "some value"type
            "owner": "some value"version
          }
 "type": "some value"       events {
}         "deviceLocation": {  nodes {
        "altitude": "some value"    id
      "device": {       createdAt
      "identifier": "some value"      receivedAt
      "model": "some value"      type
      "organization": "some value"      externalData
      "os": "some value"    }
      }    }
      "isSindowsExe": "some value"  steps {
       "latitude": "some value"   nodes {
      "longitude": "some value"      scenarioStep {
   "platform": "some value"           "protocol": "some value"name
            "version": "some value"  orderIndex
      }       }   scenarioSequence {
}      "steps": {       scenario_step "{": "some value" name
       "name": "some value"       }
 "orderIndex": "some value"         scenarioSequence "{": "some value" }
           "name": "some value" }
          }
        }
      }
    }
  }
}