Integrating Orders From Third Party to Rx-Universe

Owned by Tony LeBlanc
Last updated: Jul 20, 2023
4 min read

Third party systems, such as a practice management system or a web site, can submit orders to Rx-Universe in two different ways. Such a system can also obtain information on orders, such as the current status of the order, calculation results, etc.

Submit an Order as a flat file

Rx-Universe can accept an order as a flat file placed into a specific folder for processing. Such an order needs to be in the format described in the section

The folder that Rx-Universe checks for these flat files is specified in the Remote, Remote Order Parameters screen:

To process flat files in this folder, the Remote Processor must be running. This can be run either from the menu, under Remote, or it can be run as a standalone screen using a station set up with the “EF” auto-command.

Placing order files in the designated folder

Actually transferring the flat files from the third party system to the Rx-Universe server can be accomplished in different ways, in whatever method is most appropriate for the lab and IT infrastructure. Please note that there is no specific method recommended nor provided by Rx-Universe; actually transferring the files to the Rx-Universe server is something that should be set up by the lab’s IT department or resource.

Some possible ways to consider would include a direct copy to the folder (if the lab server is on the same network as the third party software), or providing an ftp server on the Rx-Universe folder. If the latter is chosen, we encourage the lab to use ftp authentication (rather than allowing anonymous access).

Submit an order to an API endpoint

An alternative to providing flat files to Rx-Universe is submitting orders via an API endpoint. This requires the Rx-API module to be installed and active. A third party system can connect to the endpoint and submit a json packet containing the order. Here is a sample of a simple Flat Top 28 order, deliberately omitting the add power:
curl -X 'POST' \ 'http://localhost:5645/api/orders/add' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "customerNum": "1", "custJobID": "Patient Name", "poNumber": "123456-optional", "releaseNumber": "56789-optional", "jobType": "F", "rtLensStyle": "ST28", "ltLensStyle": "ST28", "rtLensMaterial": "P", "ltLensMaterial": "P", "rtLensColor": "", "ltLensColor": "", "rtLensTreat": "SRC", "ltLensTreat": "SRC", "rtSPH": -1.25, "ltSPH": -1.50, "rtCYL": -0.50, "ltCYL": -0.75, "rtAX": 85, "ltAX": 115, "rtIPD": 30, "ltIPD": 29.5, "rtNPD": 28.5, "ltNPD": 28.0, "rtSEGHT": 20, "ltSEGHT": 20, "rtADD": 0, "ltADD": 0, "addon1": "ARC", "REM": "Comment line", "HBOX": 52, "VBOX": 44, "FED": 53, "DBL": 16, "_ETYPE": "M", "ORIGIN": "3rdParty" }'

The endpoint will detect the missing information in the submission, and respond with an appropriate error:
{ "error12:": "373: Add power must be greater than 0", "error45:": "373: Add power must be greater than 0" }

If the order is submitted correctly, the order number will be returned to the calling program:
{ "orderNumber": "10000341" }

In order to use the API endpoints, the endpoints must be accessible to the third party system; allowing such access will be handled by the lab’s IT department or resource, to ensure compatibility with the local IT security requirements. Note that Rx-API does support SSL - if used, the lab’s IT department or resource will need to provide and keep updated the appropriate certificate to allow access via SSL.

Request order information via flat file

Similar to how there are two methods to submit orders to Rx-Universe (flat file and endpoint), there are two methods to request status of order(s) that are in Rx-Universe.

The third-party system can submit a flat file requesting the status of an order, using the _ACTION=3 tag. The options are described fully in the section, but in brief, to request the status of order 12345678, you can submit a file containing:

JOB=12345678
_ACTION=3

In response, Rx-Universe will create a file in a designated folder containing the current status of the job at the lab. Again, this is described in the same section. Retrieving the status file from Rx-Universe can be done via local folder or ftp, per the lab’s IT department or resource.

Request order information via API endpoint

Requesting information on an order is best done using the API endpoints. There are several endpoints that return information about an order; the equivalent to _ACTION=3 above would be the /orders/status endpoints. This endpoint accepts one value, the order number for which to return job status, and will return the status of the order; a sample response is:
{ "order-number": "119136", "order-status": "P", "unvalid-message": "", "order-status-station": "GEN", "order-status-desc": "GEN-LOH GENERATOR", "order-status-cust-desc": "IN SURFACING", "order-status-date": "20220921", "order-status-time": "1529" }