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.
npm i -g sfg20-api-extractor
This will install the sfg20
CLI tool as globally available.
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
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
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
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
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
.
In order that custom queries correctly return changes they should return the _status
and __typename
attributes.
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)