Example Web Service And User Application
This guide provides basic instructions for getting started with the demonstration web service and user application that comes with the GS1 Barcode Syntax Engine ("Syntax Engine").
A description of the Syntax Engine is provided on the project homepage.
The source code for the example web service is provided here.
The source code for the example web service user application is provided here.
The example web service and demonstration user application can be co-installed as seperate processes on the same host, or installed on seperate connected hosts.
The desktop application that uses the web service runs only on Windows. The web service itself may run on any platform that supports Node.js.
For simplicity, for the rest of this tutorial we shall assume that the web service and user application are to be run on a single Windows 10 or Windows 11 host.
The example web service is a Node.js application that uses the WASM build of the Syntax Engine to present some of its functionality via a set of HTTP endpoints.
You must first install the Node.js execution environment for your platform by following the instructions provided here.
We recommend using the prebuilt version via the official MSI installer. This
will ensure that the node.exe command is available in your PATH.
The example web service is included in each of the two pre-built assets that are included in the latest GitHub Release that you may choose between:
- Web Assembly:
gs1encoders-wasm-app.zip - Pure JavaScript:
gs1encoders-jsonly-app.zip
One of these ZIP files should be downloaded and extracted to the local filesystem in a suitable location.
To start up the web service you should run the following in a terminal within the extracted directory:
node.exe example-web-service.node.mjs
When getting started you will likely want to observe in detail what the service is
doing by using the verbose option.
node.exe example-web-service.node.mjs /verbose
By default, the web service listens only for local connections via the IPv4 localhost interface (127.0.0.1) on port TCP/3030. This can be changed by specifying the bind and port options:
node.exe example-web-service.node.mjs /verbose /bind=0.0.0.0 /port=8080
Depending upon your configured interface and port, the output will be something like:
Web service is running on 0.0.0.0:8080
Verbose logging enabled (output to stdout)
You can redirect verbose output to a file of your choice with the /logfile option:
node.exe example-web-service.node.mjs /verbose /logfile=C:\syntaxengine.log
To observe the behaviour of the service in real time you will now need to "follow" the output file using the following PowerShell command:
Get-Content -Wait C:\syntaxengine.log
In order to test a local install of the web service running on port 3030 you can make a HTTP call to the
dataStr endpoint as follows:
curl.exe -i 'http://127.0.0.1:3030/dataStr?input=HTTPS://ID.EXAMPLE.ORG/01/12312312312319?99=ASDFEE'
This should provide the following output:
HTTP/1.1 200 OK
Content-Type: text/plain
Date: <Date and time or request>
Connection: keep-alive
Keep-Alive: timeout=5
Transfer-Encoding: chunked
Barcode message: HTTPS://ID.EXAMPLE.ORG/01/12312312312319?99=ASDFEE
AI element string: (01)12312312312319(99)ASDFEE
GS1 Digital Link URI: https://id.gs1.org/01/12312312312319?99=ASDFEE
HRI:
(01) 12312312312319
(99) ASDFEE
If you are running the web service with verbose output then you should also see the corresponding activity:
... Request #1: GET /scanData?input=%5DQ1http%3A%2F%2Fid.gs1.org%2F01%2F12312312312319%3F99%3DT ...
... Pathname: /scanData
... Query params: {"input":"]Q1http://id.gs1.org/01/12312312312319?99=TESTING"}
... Setting GS1encoder options:
... includeDataTitlesInHRI: false
... permitUnknownAIs: false
... permitZeroSuppressedGTINinDLuris: false
... validateRequisiteAIs: true
... Calling gs1encoder.scanData = "]Q1http://id.gs1.org/01/12312312312319?99=TESTING"
... GS1encoder results:
... dataStr: http://id.gs1.org/01/12312312312319?99=TESTING
... aiDataStr: (01)12312312312319(99)TESTING
... dlURI: https://id.gs1.org/01/12312312312319?99=TESTING
... hri: ["(01) 12312312312319","(99) TESTING"]
... Response: 200 OK (application/json)
... Response body:
... {"dataStr":"http://id.gs1.org/01/12312312312319?99=TESTING","aiDataStr":"(01)12312312312319 ...
... Request completed in 0.828ms
If you are running the web service on a Windows platform and you are running as a privileged user you may be able to install it as a background service.
Before attempting to install the web service as a background service, first ensure that it is working correctly from a terminal, as described above.
Once you are satisfied that it is working, run the following in a terminal within the extracted directory to install the background service:
node.exe example-web-service.node.mjs /verbose /logfile=C:\syntaxengine.log /installservice
After a short time, you should see an entry "GS1 Barcode Syntax Engine" appear
in your Windows services lists, which you can view by pressing Windows+R,
typing "services.msc" and pressing Enter.
The service should remain in "started" state and service any HTTP requests that you send it.
Note that you need to configure the service to write verbose output to a log file (as above) if you want to observe its behaviour.
If you wish to later remove the background service you can run:
node.exe example-web-service.node.mjs /uninstallservice
If service installation or uninstallation fails then this is likely because your current user does not have sufficient privileges to install background services. You might try again as a user with administrator-level rights.
The example web service is provided in a pre-built asset that is included in the latest GitHub Release:
windows-web-service-user-app.zip
The asset should be downloaded and extracted to a suitable location on your local filesystem, or alternatively built from source.
You can launch it by double-clicking on the program icon. Upon launch, the main window will be displayed:
Note: The first time that you attempt to run the application your antivirus software may block the attempt because the application or publisher isn't recognised. You should be able to click "more info" (or similar), read the information provided, and you may then decide to "run anyway". If you are in a managed environment and are unable to proceed with running the application then it is likely that a local policy is deliberately blocking all unrecognised applications and you may then need to ask your system administrator to whitelist the application.
The "Endpoint URL" field contains the location of the web service. It defaults to connecting to a locally installed service on port 3030. If you are running the web service remotely and/or have changed the port then you must update the URL accordingly.
The "Scan data" field is where you can manually enter valid barcode scan data,
starting with an AIM Symbology Identifier and replacing GS characters with a
printable character sequence defined in the "FNC1/GS indicator" field,
typically "^".
When the Endpoint URL and Scan data fields are changed, the contents of the "HTTP request to send" field will be updated to reflect what should be sent to the web server to identify the endpoint and specify the payload.
Clicking "Send HTTP request" will cause the application to attempt to deliver the HTTP request and await a HTTP response.
If the data is valid then a HTTP 200 OK response will be received together
with a JSON payload that is the result of processing the input data using the
GS1 Barcode Syntax Engine.
The application will then proceed to extract the information from the JSON response and render this in the subsequent data fields.
If a field is not populated, a reason will normally be given -- for example, that no valid GS1 Digital Link URI exists for the input provided.
If an error is returned then this should indicate the reason for the failure. Errors may relate to connectivity issues or bad input data.
In the event of connectivity issues, confirm that the web service is running
and accepting local requests sent with curl.exe (described above).
If the web service is running remotely, confirm that it is configured to listen
on a network interface (e.g. bind to 0.0.0.0), and that network filters and
firewalls do not block connectivity.
The application monitors keyboard input for a rapid succession of four or more
characters beginning with ]. After a pause, such a sequence of characters
will replace the input field.
If the "Auto submit scans" checkbox is ticked, then any scan data is automatically submitted to the web service endpoint. Otherwise you will need to click the "Send HTTP request" button after scanning the data.
The scanner must be configured to:
- Deliver an AIM Symbology Identifier as part of the data.
- Convert GS characters that represent Application Identifier separators
into a printable character such as "
^". - Transmit characters using keyboard emulation (i.e. HID keyboard mode, not RS232), delivering keystrokes with an inter-character delay of no more than 50ms.
The "FNC1/GS indicator" field must align with the printable character (or character sequence) that the scanner actually sends. It causes the denoted characters to be converted to GS when the input is sent to the web service endpoint.