SFG20 Extractor

This is an ISC licensed utility to access the SFG20 maintenance regime data. You must have the appropriate share link and access tokens in order to successfully use this tool, the share link code is available from a licensed SFG20 user, and the access token is available from SFG20 for approved API partners.

Installation

npm i -g sfg20-api-extractor

This will install the sfg20 CLI tool as globally available.

Usage

To get the up-to-date help type the following into a terminal

sfg20 --help

You may also get help for specific commands:

sfg20 xml --help

Extracting Data

The utility enables you to extract data in either XML or JSON formats using the commands sfg20 xml and sfg20 json. The extraction commands require two keys and the type of query to run to extract the data.

Template:

sfg20 xml A_SHARE_LINK YOUR_ACCESS_TOKEN BUILT_IN_QUERY

You can get a list of the current built in queries by typing:

sfg20 list 

This will list the available queries, e.g.: tasks, schedules and frequencies

You may also supply your own query file instead of using a built in query using the --query (-q) option:

sfg20 xml ABCD12345678 XYZ12345678 --query ./my-query.txt

Output to a file

By default, the utility writes the output to the terminal, you can direct it to a file with the --file (-f) option:

sfg20 json ABCD12345678 XYZ12345678 tasks --file ./tasks.json

Override API URL

If you want to use a different URL for the API, you can use the --url (-u) option

sfg20 xml ABCD12345678 XYZ12345678 tasks --url http://localhost:3000/v3.0

Output Changes

The tool allows you to output only changes to the shared data since a date using the --since (-s) option:

sfg20 json ABCD12345678 XYZ12345678 tasks --since 2023-08-30

When requesting changes you can see a status (_status in JSON) attribute indicating Changed or Added.

Deleted records will have a type (__typename in JSON) attribute set to DeletedRecord.

Changes with custom queries

In order that custom queries correctly return changes they should return the _status and __typename attributes.

Custom Queries

You can supply your own custom query as a GraphQL fragment stored in a file and passed with the --query option.

e.g.

   tasks{
      ... on APITask {
        __typename
        _status
        intervalInHours
        title
        id
        url
        linkId
        frequency {
          interval
          period
        }
        skill {
          Skilling
          SkillingCode
          CoreSkillingID
        }
        schedule {
          title
          code
        }
        content
        classification
        minutes
        steps
      }
      ... on DeletedRecord {
        __typename
        id
      }
    }

The API provides a GraphQL playground available on its URL, you can use this to build regime queries and then copy the return data specification into the file.

(c) 2023 BESA Publications Limited

Author: Mike Talbot (et al)