Working with Local Resources

In some cases, it is necessary for GS to interact directly with files or services available on the computer running GS. Common scenarios include:

Automating file imports from a local or networked folder.
Reading data from an on-premises database.
Saving files to a mapped network drive.

Modern web browsers do not permit websites to access local files or services without user interaction. This restriction is essential for protecting user privacy and security, but it can interfere with automation or machine-to-machine communication.

To support secure local integration, GS provides a companion application: GS Local.

GS Local

GS Local is a lightweight Windows application that runs in the background and facilitates secure communication between GS and the local machine without requiring user interaction.

Installation

To start using GS Local:

Download GS Local.
Run the downloaded .exe file and complete the setup.
Launch GS Local. At the login screen:
1. Enter your Company ID and ensure that the port in the Settings matches the current device's Local App Port.
2. Check Do not ask again.
3. Click Submit.
GS Local will start and minimize to the system tray.
1. Click on the GS logo in the system tray to repoen the user interface.
2. Right-click on the GS logo and select Exit to quit the application.

Updates

GS Local keeps itself up to date by automatically downloading and installing the latest version. Updates are installed each time GS Local starts and periodically while running.

Logs Screen

For troubleshooting purposes, all communication between GS and GS Local is recorded in the Logs tab. Use the buttons in this tab to clear the log stream, copy the logs to the clipboard, or open the logs in the system's default text editor.

Settings Screen

Settings for GS Local can be controlled via the Settings tab.

To change the port GS Local listens to, update the Port field and click Save. This will immediately stop listening on the old port and start listening on the new one.

Files and Folders

GS Local can be used to access local and networked files and folders using gsApi.local.file and gsApi.local.folder.

The following examples demonstrate how to use these commands.

Read a file from a networked drive.

// Open a read handle to the file on the L:
const fileHandle = await gsApi.local.file.open('L:\\readings\\20250618.txt', 'read');

// Read and process each line in the file.
let currentLine = await fileHandle.readLine();
while (currentLine) {
    // ...process the current line

    // Advance the currentLine to the next line in the file.
    currentLine = await fileHandle.readLine();
}

// Close the file to release its handle.
await fileHandle.close();

Write a file to a networked drive.

// Create the file on the L: by opening it in `write` mode.
const fileHandle = await gsApi.local.file.open('L:\\readings\\20250618.txt', 'write');

// Write string contents to the file.
// These contents might be gathered from an Inspection Test, a Retrieval, or some other source.
await fileHandle.write('here are some text contents');

// Close the file to release its handle.
await fileHandle.close();

Copy all CSV files from a folder to a new folder.

const oldFolderName = 'L:\\readings';
const newFolderName = 'L:\\readings-new';

// Create the new folder
await gsApi.local.folder.create(newFolderName);

// Find all CSV files in the old folder
const oldCSVs = await gsApi.local.folder.search(oldFolderName, '*.csv');

// Copy each file to the new folder
for (let i = 0; i < oldCSVs.length; i++) {
    const oldFilePath = oldCSVs[i];
    const newFilePath = oldFilePath.replace(oldFolderName, newFolderName);
    await gsApi.local.file.copy(oldFilePath, newFilePath);
}

Interacting with Databases

GS can be used to accesss local 64-bit ODBC data sources using gsApi.local.database and Local Queries. This guide assumes that a 64-bit ODBC data source has been configured on the local computer.

To use an ODBC data source, first establish a connection using its DSN (Data Source Name):

const dbConnection = await gsApi.local.database.connect('my_odbc_connection');

After connecting, Local Queries can be used to access the data source. As explained in the reference, Local Queries are parameterized and can execute any type of SQL statement.

Example

The following examples assume that a specifications table has been created in a local MySQL database:

CREATE TABLE specifications (
    part varchar(255),
    rev int,
    lower_spec float,
    target_x float,
    upper_spec float
);

Creating Local Queries

To insert a record into this table, you might create a Local Query with the following SQL:

INSERT INTO specifications VALUES (?,?,?,?,?);

To retrieve specs based on a revision and multiple part numbers, you might create the following Local Query:

SELECT lower_spec, upper_spec FROM specifications WHERE part IN (?) AND rev = ?;

Assume that the Internal ID of the INSERT Local Query is 1 and the SELECT Local Query is 2. Remember that these IDs can be found when viewing a Local Query.

Using Local Queries

Local Queries are executed using the LocalDatabaseConnection.execute() method.

When executing a non-SELECT statement (like the INSERT statement above), the result of the execute() method can usually be ignored. The following code inserts two part numbers, PN-4821-A and PN-1297-A, into the table with their specs:

const dbConnection = await gsApi.local.database.connect('my_odbc_connection');
await dbConnection.execute(1, ['PN-4821-A', 1, 1.9, 2.0, 2.1]);
await dbConnection.execute(1, ['PN-1297-A', 1, 8.75, 9.0, 9.25]);

When executing a SELECT statement, the execute() method will resolve to an object containing columns and rows. The columns property contains the names of the columns returned by the query. The rows property contains a two-dimensional array with the actual contents. To retrieve the specs inserted in the previous example, the following code could be used:

const connection = await gsApi.local.database.connect('my_odbc_connection');
const specResults = await connection.execute(2, [['PN-4821-A', 'PN-1297-A'], 1]);
if (specResults && typeof specResults === 'object') {
    specResults.rows.forEach(row => {
        // Process each row...
        // row[0] contains the lower_spec, row[1] contains the upper_spec
    });
}