Skip to content

Inspection Scripting

Subscription Tier Required

This feature requires the Premier subscription tier or higher.

Scripting Principles

In order to effectively make use of scripting in GS, you should be familiar with the following topics:

Scripts in GS run inside of a Web Worker, which allows access to a subset of available browser APIs. Scripts executed in GS will never be able to directly access the DOM.

Scripts in GS will execute once, from top to bottom, in the order which they are listed. Selected Library Scripts will be executed before any Inspection or Dashboard scripts.

GS makes heavy use of the async / await pattern. Prefer using async and await over .then(...) when writing code for GS to ensure the expected order of execution.

Scripts may be managed using the Scripts action in the Inspection Editor, or by pressing Ctrl+Alt+C.

An image showing the location of the Script action in the Inspection Editor

Inspection API

All Inspection-specific functions and objects are under gsApi.inspection. This API contains a variety of events, functions, and access to other APIs.

For a full reference, see the Inspection API.

Sub-Inspection API

In order to access the properties and functions for a Sub-Inspection, a Sub-Inspection API must be constructed. This is done by passing the Script ID of a Sub-Inspection into the subInspection function:

gsApi.inspection.subInspection('myScriptId');

The result of this may be stored for later use, in order to reduce typing and code complexity. For example, the following code:

const properties = await gsApi.inspection.subInspection('myScriptId').getProperties();
await gsApi.inspection.subInspection('myScriptId').updateProperties({
    showSubmitButton: properties.name === 'Final Checks'
});

Is equivalent to:

const mySubInspection = gsApi.inspection.subInspection('myScriptId');
const properties = await mySubInspection.getProperties();
await mySubInspection.updateProperties({
    showSubmitButton: properties.name === 'Final Checks'
});

Test APIs

In order to interact with Tests on a Sub-Inspection, a Test API must be constructed. This is done by passing the Script ID of the test into the appropriate SubInspectionApi or GlobalTagAreaApi:

gsApi.inspection.subInspection('myScriptId').passFail('myPassFail');
gsApi.inspection.globalTagArea().traceability('myTraceabilityTest');

As with Sub-Inspections, Test APIs may be stored for later use in order to reduce code complexity and improve readability.

const spcTest = gsApi.inspection.subInspection('mySubInspection').spc('mySPCTest');
spcTest.updateProperties({
    //...
});

React To Events

Most functionality in Inspection Scripts will happen in response to events. These events allow binding a function which will be executed whenever the event occurs. For example, to execute code whenever a Button Test is clicked, bind to the onClick event:

gsApi.inspection.subInspection('mySubInspection').button('myButton').onClick(async () => {
    console.log('This will be logged whenever the button is clicked');
});

To wait for the Inspection to be fully loaded, use the onReady event:

gsApi.inspection.onReady(async () => {
    // It is now safe to interact with sub-inspection and test properties
});

To perform an action after a Sub-Inspection has started, use the onAfterStart event:

gsApi.inspection.subInspection('mySubInspection').onAfterStart(async () => {
    // The sub-inspection is now fully loaded and running
});

Offline Considerations

Some Users may run Inspections without an active internet connection. When an Inspection is executed offline, Inspection Scripts will still run, but any script that relies on network connectivity might fail.

If an Inspection may be used offline, pay close attention to code that depends on external data sources. You will likely want to employ defensive code strategies in these areas, such as:

  • Wrapping fetch calls in a try-catch block.
  • Providing meaningful fallback behavior when data cannot be loaded.
  • Avoiding script errors that would block Users from continuing their work offline. However, if critical steps in an Inspection might be missed while offline, consider preventing the User from continuing until they are back online.

Built-In Caching

GS automatically caches all GET requests made to GS servers for Users who are permitted to run Inspections offline. GS will automatically replay these cached responses when offline.

You do not need to implement your own caching for GS GET requests.

Next Steps

Now that you're familiar with basic principles of Inspection Scripting in GS, you are ready to walk through some specific scripting tasks: