1 What is external data?
2 Use Cases
- 2.1 Retrieving Scenario Sessions with External Data
  - 2.1.1 Arguments
  - 2.1.2 MATCH Example
  - 2.1.3 CONTAINS Example

What is external data?

External data can be added to various data types such as ScenarioSessions, and ScenarioSessionParts. This external data is usually supplied during the creation of these data types. A good example is through our DeepLinks, where extra query params within the link are then added as external data to the new ScenarioSession that is created. For more details on adding external data parameters to sessions see : https://scopearcloud.atlassian.net/wiki/spaces/API/pages/1671987201/Using+Deeplinks#Extensibility

Why do I want to query external data?

Certain data types can be queried using external data. For example, this might be useful when trying to retrieve sessions using a work order number that was added as external data.

What data types support external data?

Currently there are a few data types that have external data:

Calls
Scenario Sessions
Scenario Steps
Scenario Session Parts

What types of queries are supported for external data?

Currently, there are two types of ways to query external data:

Match: Used to match exactly an external data key to a single external data value.
Example: X => Y and you know the value of Y and X
Contains: Used to match one of many values assigned to a single external data key.
Example: X => [ Y, Z ] and you know Y, one of the values of X.

In the following examples, both ways will be used.

Use Cases

There are numerous use cases for external data to retrieve records.

Retrieving Scenario Sessions with External Data

Sessions are created when a user follows a deep link. The extra query parameters get added to the external data of the scenario session.

Arguments

These are the minimum arguments that are needed to query for all scenario sessions if they are to be queried for external data. There are other arguments that can be added to further refine the results. Check out the GraphQL introspection schema for more information on what other arguments are available.

first: How many results are in the query. Maximum of 100 due to request size.
externalData key: A string for the key of the value.

externalData value: A string for the value that is being matched.
externalData type: Can either be “MATCH” or “CONTAINS”

MATCH Example

This query will return the first 100 scenario sessions that have an external data key that matches a single value. For example, the external data might look like this:

{"partNumber": "1234-ABCD"}

There is a single value for the part number so the MATCH type should be used.

MATCH Query

query FetchScenarioSessionsWithMatch(
  $first: Int!,
  $type: String!,
  $key: String!,
  $value: Alphanumeric!
) {
  scenarioSessions(
  first: $first, 
  externalData: {
    type: $type, 
    key: $key, 
    value: $value
  }) {
    nodes {
      nodes {
        id
        databaseId
        sessionType
        externalData
        user {
          id
        }
      }
    }
  }
}

MATCH Variables

Here are the variables to pass in with the matching query:

{
  "first": 100,
  "key": "partNumber",
  "value": "1234-ABCD",
  "type": "MATCH"
}

CONTAINS Example

This query will return for the first 100 scenario sessions that have an external data key that is one of the values in a list. For example, the external data might look like this:

When using the CONTAINS type, you can have many values for the part number. Any session that has one or more of these values for the part number field will be returned by the query.

CONTAINS Query

CONTAINS Variables