STARS Implementation Guide
0.3.0 - ci-build

STARS Implementation Guide - Local Development build (v0.3.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

STARS Client

STARS Client Overview

The STARS Client provides a wrapper to communicate with the FHIR server using a simpler file system. This allows a basic integration for non-FHIR based systems to be able to send and receive messages using a simple interface based simple data structure models such as CSV.

The client is built to match the release of the FHIR server and profiles.

File Formats

  • CSV - flat column and row structure. Templates created in Root Data Folder path (template_servicerequest.csv, template_diagnosticreport.csv).
  • basic model - intermediary format during conversion.
  • FHIR+XML - xml file, complete fhir message, ready to send.
  • FHIR+JSON - json file, complete fhir message, ready to send.

Setup Pre-requisites

Requires .NET Desktop Runtime 6.0. The installer will prompt you or you can navigate here and download the .NET Desktop Runtime 6.0 for your OS version.

Download

Access the latest copy of the Stars.Client.Installer.msi over on the Downloads page.

Installation

Follow these steps to install the client.

  1. Welcome screen.

    Welcome

  2. Select the installation path

    Select Installation Folder

  3. Confirm installation settings

    Confirm Installation

  4. Installation has completed

    Installation Complete

Initial Setup

The application will require some setup to be completed before it can communicate to the Stars server.

NB: If you require a proxy server, opening the Stars.Client.UI will automatically create the `settings.json` file in `C:\ProgramData\Stars.Client`, if missing, in preparation for manually editing the proxySettings as required.

    "proxySettings": {
    "proxyEnabled": true,
    "address": http://proxy.com:8080,
    "username": "user",
    "password": "pass"
    }

Reopen the Stars.Client.UI and continue configuration.

  1. Authenticate using a STARS account (as delegated from starsapi.csiro.au, not acdp.csiro.au as these are different services). If the node has already been configured then you must be a member of the same organisation as the node to login and make changes.

    Logon

  2. Ensure you are running the latest verison of the client by checking Help -> About and checking for updates.

    Config Endpoint

  3. On the Endpoint tab click Get Token.

    Config Endpoint

  4. Type the node Username and Password followed by Authenticate to retrieve a node authentication token. This will configure the node to the organisation.

    Get Token

  5. Click Close. Remember to save your settings. You may have to reload the application for the node to reload correctly on first configure.
  6. Choose your Check Type (Polling and interval in minutes).
  7. Click Save to commit the settigs to file.

  8. Your node endpoint connection is now configured.

  9. Click Client tab.

    Config Client

  10. Browse to select your root data path. Sub-folders will be created automatically as per the preview when the Service is restarted.

  11. Select the Incoming and Outgoing file types (see File Formats above):

    • files added to the incoming folder have been received from the STARS server.
    • files added to the outgoing folder will be sent to the STARS server.
  12. Configure email notifications as desired and test.
  13. Click Save.

  14. Your client is now fully configured.

  15. Click Service tab.

    Config Service

  16. Click Install button to install the service to the machine.
  17. Make any modifications to the service as required, such as 'run as another account' using the services snapin (botton right shortcut to open services.msc).

  18. Click Start for the Stars.Client.sandbox service when ready. This will allow you to test your settings are working as expected. Once working you can start the Stars.Client.production service. Both services can run side by side but you may wish to run the sandbox service on your testing infrastructure.

  19. To check the status logs click the Status tab

    Status

Folders and Paths

Both services can run side-by-side as separate instances, separated by the sandbox\production folder tree.

  • Default installation location is C:\Program Files\CSIRO\Stars.Client.
  • Settings are stored in C:\ProgramData\Stars.Client\settings.json.

  • Default Root Data Path is located in C:\ProgramData\Stars.Client and is expected to be changed as required.

    STARS Client Root Data PathSTARS Client Root Data Path"C:\ProgramData\Stars.Client"sandboxincomingarchivedarchived_errorfrom_starsoutgoingarchivedarchived_errorattachmentsto_starsproductionincomingarchivedarchived_errorfrom_starsoutgoingarchivedarchived_errorattachmentsto_stars
    Default path and structure created when the service starts.

When the Stars.Client is executed it will create the latest copy of the CSV templates in the Root Data Path based off the internal models.

Sending files using the client

Process of sending a message through the client to the server.

STARS Client Interaction to Send MessagesSTARS Client Interaction to Send MessagesLocalFolderStarsClientServerLocalFolderLocalFolderStarsClientStarsClientServerServerRead CSV from 'outgoing'Stars.ClientConvert CSV to basic modelConvert basic model to FHIR messageRead attachments from 'outgoing/attachments'Stars.ClientInject attachments to FHIR messageSave FHIR message to 'outgoing/to_stars'Move CSV to 'outgoing/archived'Move attachments to 'outgoing/archived'Uponerror, Move CSV and attachments to 'outgoing/archived_error'Uponerror, Save CSV.log to 'outgoing/archived_error'Read FHIR message from 'outgoing/to_stars'Send FHIR message bundle to serverMove FHIR message to 'outgoing/archived'Uponerror, move FHIR message to 'outgoing/archived_error'Uponerror, save FHIR message.log to 'outgoing/archived_error'
Sequence of converting CSV to FHIR bundle and sending to server
  1. Export CSV file from LIMS.
  2. Save in outgoing folder.
  3. Client will convert CSV to FHIR message bundle.
  4. FHIR message will be sent to the FHIR server.
  5. Destination client endpoint will receive and process the message.
  6. Message.OK (should) be sent back to the server or sender.

Receiving files using the client

Process of receiving messages from the server through the client.

STARS Client Interaction to Receive MessagesSTARS Client Interaction to Receive MessagesLocalFolderStarsClientServerLocalFolderLocalFolderStarsClientStarsClientServerServerReceive FHIR message bundle from serverSave FHIR message to 'incoming/from_stars'Read FHIR message from 'incoming/from_stars'Stars.ClientConvert FHIR message to basic modelConvert basic model to CSVSave CSV to 'incoming'Stars.ClientExtract attachments from FHIR messageSave attachments to 'incoming'Move FHIR message to 'incoming/archived'Uponerror, move FHIR message to 'incoming/archived_error'Uponerror, save FHIR message.log to 'incoming/archived_error'
Sequence of receiving from server and converting FHIR bundle to CSV
  1. Client will check for new messages either on a polling interval or via subscription (not yet implemented).
  2. New messages are downloaded to incoming\from_stars folder
  3. Message.OK (should) be sent back to server or sender.
  4. Client will convert the FHIR message to desired format (CSV, FHIR+JSON or FHIR+XML)
  5. File saved to the incoming folder.