Versions Compared

Version Old Version 4 New Version Current
Changes made by

Aaron DeYonker

james.holloway

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.

Single Session

query { viewer { organization { scenarioSessions { # INSERT everything below the `... on ScenarioSession` line vvquery { node(id: "ljmnV58GM_c4AEHHiZy0qiSoP9HN3CnK7dbuPMNxx_M="
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 on{
ScenarioSession {     id
 startedAt     databaseId
 finishedAt       duration
      idleDurationendedAt
      numberOfStepsPossibleexternalData
      numberOfStepsViewedstartedAt
      percentOfStepsViewedendedAt
      stateduration
      externalDatasessionType
# NOTE: this is where the datacompletedSteps passed{
from the System of Record can be found nodes {
    scenarioRelease {     id
   author     }
   publishedAt   }
     scenario {
          author parts(first: 1, orderBy: { attribute: "startedAt", direction: DESC}) {
        nodes {
  id        databaseId
    name      createdBy {
   }         id
 description           name
          origin_group}
{          userInfo {
 name           }latitude
          published_at  longitude
      }      deviceOs
  type         version deviceModel
     }       eventsdevicePlatform
{         nodes {}
        }
 attachments {    }
      scenario {
author        id
    fileContentType    name
        fileDownloadCountorganization {
          slug
fileFingerprint        }
    fileName  }
      scenarioRelease {
  fileSize      version
      fileUpdatedAt  sdkVersion
        workInstructionType
 fileURL       type
     fileURLExpiresAt   sequences {
        name  nodes {
         organization   id
         owner   name
         type   scenarioSteps(first: 1000) {
    }           deviceLocationnodes {
            altitude    id
        device {       name
       identifier         orderIndex
     model           type
   organization             scenarioSequence {
os             }     id
       isSindowsExe           name
 latitude             longitude  }
          platform      items(first: 1000) {
    protocol             version nodes {
        }         }   id
   }       steps {         scenario_stepdescription
{           name         type
 orderIndex           scenarioSequence {     }
       name         }
           }   }
     }       }
    }   } }

All Sessions

Code Block
# To pull}
ALL scenario sessions for the org associated with currently}
authenticated user query {   viewer}
{     organization {
      scenarioSessions steps(first: 1000, orderBy: {attribute: "startedAt", direction: ASC}) {
        #nodes INSERT{
everything below the `... on ScenarioSession` line vv# To pull theid
details for a scenario sessions with id = "ljmnV58GM_c4AEHHiZy0qiSoP9HN3CnK7dbuPMNxx_M=" query {completed
  node(id: "ljmnV58GM_c4AEHHiZy0qiSoP9HN3CnK7dbuPMNxx_M=") {     ... onduration
ScenarioSession {          completedItems {
           startedAt nodes {
           finishedAt   id
   duration       idleDuration  }
    numberOfStepsPossible      }
numberOfStepsViewed        percentOfStepsViewed  scenarioStep {
   state       externalData # NOTE:id
this is where the data passed from the System of Record can bename
found       scenarioRelease {    type
    author        orderIndex
publishedAt
        scenario            scenarioSequence {
              id
              name
            }
            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" }
          }
        }
      }
    }
  }
}