Example 2 - Retrieving laboratory data

Description of the scenario

This example describes how you can use a REST call action to automatically retrieve data in one Intrexx instance from another Intrexx instance at a defined time interval. The REST call action calls an endpoint that was created using the Intrexx Application API.

In the example, it is assumed that there is a laboratory and a clinic that both use Intrexx. The laboratory is a service provider for the clinic and regularly receives patient samples from the clinic. These are examined by the laboratory. The result is either positive or negative.

The decisive factor now is how the clinic receives the laboratory results. The clinic does not want the laboratory results to be sent by post or email. Instead, the results are to be transmitted automatically. The results from the laboratory are automatically assigned to the corresponding patients in the clinic patient directory.

Solution - Overview

The laboratory saves the results in a database. At the same time, the lab grants access to the database via an application or an application API endpoint.

The clinic creates a process with a REST call action that automatically queries the lab's API endpoint every 30 minutes to check for new results. If this is the case, the result for the corresponding patient is automatically set in the clinic's own patient management.

Portal view

In the portal view, this could look something like this:

Please note that the example does not describe a "fully-fledged" solution for data exchange between a laboratory and a clinic. Instead, it is intended to illustrate the basic possible uses of the REST call action. At the same time, you can use the example as a starting point for your own extended levels of configuration.

Main actions

To create the example described here, you must perform the following main actions in Intrexx:

Laboratory

1. Create an application to record the results

You need an application ("laboratory application") to record the results together with the associated patient data. You must create the required data fields for these. In our example, the patient data and the result are entered via an input form, or fieldset.

2. Create an API endpoint that allows the results to be queried

In order for the results to be queried or retrieved by the clinic, you must create an API endpoint that allows access to the data group in which the patient data and the results are stored. We will use the Intrexx Application API for this.

Clinic

3. Create an application to record patient data including the results from the laboratory

You need an application ("clinic application") to be able to save the results from the laboratory. The data fields correspond (essentially) to the data fields in the laboratory app.

In our example, the entries in the data fields are used to match the patients so that the correct results are assigned to the respective patients.

4. Create a process that executes a REST call action at regular intervals

Finally, you must create a process that is started automatically at a specific time interval. The process contains a REST call action that accesses the API endpoint of the lab app. If data has been updated there, it will be transmitted to the clinic. The process saves the collected data in the clinic app.

1. Create laboratory application

There are no special features to consider when creating the laboratory application.

Portal view

This is how the laboratory application appears in the portal view:

It consists of an overview page on which the recorded patient data, including the test result, can be displayed and edited.

The input dialog looks like this:

Portal Manager

Data group

The laboratory application requires a data group with the following data fields:

First name (string), last name (string)

The patient's first name and last name must be entered here.

The first name and last name are used to match the data records between the laboratory and the clinic.

Reference ID (integer)

A unique ID must be stored here.

In the example described here, the clinic must also know this ID, as it is used in addition to the first name and last name to identify the patient or for correct data synchronization.

Result (Boolean)

The result of the test must be recorded here.

In the example described here, a checkbox (Boolean) is used for the result. The result can be either positive or negative. In an expansion stage, further "statuses" such as "Result still pending" etc. would be conceivable here.

Edit page

Create an edit page for the data fields.

Overview page

Create an overview page with a view table that displays the entries.

2. Create API endpoint

Detailed information on creating API endpoints based on the Intrexx Application API can be found in the Intrexx Application API section.

The main steps required to implement our example are described below.

  1. Activate the "API endpoints" checkbox in the "View" menu.

  2. Go to the "API endpoints" tab.

  3. Click on the icon.

    The "General" dialog is opened.

  4. Enter a name and select the "Data group end point" button under "Type".

  5. Click on "Next".

    The "Data group selection" dialog box is displayed.

    "GET" is already preset for "End point". Leave this setting as it is.

    Action

    Under "Action", select the value "Read multiple data records". This is necessary because all patient data is checked for changes to existing data records and for the existence of new data records during an API query.

    Application

    Select the value "(current application)" here.

    Data group

    Select the "Tests" data group here.

    Return values of the query

    Add the following data fields here:

    • first name

    • last name

    • number

    • results

    • created

  6. Click on "Next".

    The "Path parameters" dialog appears.

    Enter the following path parameters:

    • query

    • reference id

    • first name

    • last name

  7. Click on "Next".

    The "Query parameters" dialog box is displayed.

    No entries or settings are required in this dialog box.

  8. Click on "Next".

    The "Filter and sort" dialog box is displayed.

    Enter the following filters:

    • First name

    • Last name

    • Reference ID

  9. Click on "Finish".

Create API key

We must create an API key so that the clinic or clinic application can access the laboratory's API endpoint. This is used later by the clinic for authentication at the API endpoint.

Detailed information on this can be found in the section Create and manage API keys.

3. Create clinic application

There are no special features to consider when creating the clinic application.

Portal view

This is how the clinic application appears in the portal view:

It consists of an overview page on which the recorded patient data, including the test result, can be displayed and edited.

The input dialog looks like this:

Portal Manager

Data group

The clinic application requires a data group with the following data fields:

First name (string), last name (string)

The patient's first name and last name must be entered here.

The first name and last name are used to match the data records between the laboratory and the clinic.

Reference ID (integer)

A unique ID must be stored here.

In the example described here, the clinic must also know this ID, as it is used in addition to the first name and last name to identify the patient or for correct data synchronization.

Result (Boolean)

The result is set automatically here using the REST call action.

Picked up

This is automatically marked when a result has been picked up from the laboratory using the REST call action. Activating the checkbox prevents results for the corresponding patient from being picked up more than once.

Edit page

Create an edit page for the data fields.

Overview page

Create an overview page with a view table that displays the entries.

4. Create process with REST call action

Trigger workflow - Global timer (1)

The process is started in a time-controlled manner.

Add a global timer to the process.

Set the desired execution time. In our example, the process or REST call action is executed every 30 minutes.

Under Data group, select the "Clinic" application and the "Patients" data group.

In the next step, we create a filter so that the REST call action is only carried out for those patients for whom no result has yet been retrieved.

Click on the icon.

The "Filter" dialog box is displayed.

Click on the icon.

The "Filter Expression Properties" dialog box appears.

Data group

Select the "Patients" data group.

Data field

Select the data field "Retrieved <boolean>".

Operation

Select the value "Equal".

Custom

Boolean (logical value)

Select the value "False" here.

Trigger workflow - Timer event handler (2)

Add a timer event handler to the process.

Under Timer event handler, select the previously added global timer.

Set up REST call - Retrieve lab results (3)

General Enter an alias for the REST call action.

Parse JSON Activate the checkbox, as the API endpoint of the lab application responds in JSON format and this must be parsed.

Authentication and header

In this dialog box, you must enter the information required for authentication at the API endpoint of the lab application (Create API endpoint).

Select the "API key" authentication type.

In the "Token" field, enter the API key that you have generated for the API endpoint of the lab application (Create API key).

You also have the option of managing the API key via resource mapping ().

Request The request must be defined in this dialog.

Detailed information on this can be found in the Configure request section.

Method GET

Schema https

Port (optional) In our example, this is port 1342.

If you do not enter a value, the following default values are used:

  • Port 443 (for HTTPS)

  • Port 80 (for HTTP)

Hostname Enter the hostname under which the REST API endpoint can be reached.

Path Enter the path here.

In our example, the path is structured as follows:

api/app/40AD456DF58779GGG4273F123456789/query/${first name}/${last name}/${reference id}

The following table gives you an overview of the general structure of the API URL.

Method

Base path

Parameter
variable fix fix variable variable variable
GET /api

/app/

 /GUID of the application /path parameter ?/query parameter

Detailed information on this can be found in the section Structure of the API URL.

You also have the option of managing the path parameters via resource mapping ().

Body Select "None" as the body type.

Click on "OK".

Process response data (4)

This process step is about processing the JSON received and placing the results in the processing context. A Groovy script action is used for this.

JSON

The response data is as follows:

[
	information:[                <-- "information" kommt aus der App-API und behandelt, was geliefert wird.
		limit:150, 
		offset:0, 
		orderBy:[
			[
				field:1234B7DFE7A0D74FD2318E540D9AF3B72EF789, 
				order:asc
			]
		]
	],
	data:[                      <-- Das ist der abgeholte Datensatz.
		[
			ergebnis:true, 
			reference-id:1234, 
			vorname:John,
			nachname: Doe, 
			created:2024-07-24T11:24:46Z
		]
	]
]

The following Groovy script is used in our example to process the response data.

g_syslog.info("\nAbgeholtes Ergebnis: \n" + g_sharedState.abholen.body.json + "\n");
g_syslog.info("\nBefund: \n" + g_sharedState.abholen.body.json.data.ergebnis + "\n");

if (g_sharedState.abholen.body.json.data.ergebnis[0] == null) {
	g_syslog.info("Kein Befund vorhanden")
} else {
	boolean befund = g_sharedState.abholen.body.json.data.ergebnis[0];
	if (befund == false) {
		g_syslog.info("Befund ist negativ");
	} else {
		g_syslog.info("Befund ist positiv");
	}
}

Determine whether a result exists (5)

This process step determines whether a (new) result has been transmitted in the response data. A Groovy condition is used for this.

To determine whether a (new) result is available, the following Groovy script is used in our example.

if (g_sharedState.abholen.body.json.data.ergebnis[0] == null) {
	return [foundNoResult]
} else {
	return [foundResult]
}

There are no new results - Logging(6)

In our example, an entry is to be written to a log file if there are no new results.

Logging is for information purposes only. It has no relevance for the functionality of the process.

For logging, we use a Groovy script action that uses the following Groovy script.

g_syslog.info("Kein Befund");

Prepare results for writing to the patient data group (7)

If new results have been transmitted in the response data, these should be written to the patient data group. To make this possible, these are first written to the processing context. The following Groovy script is used for this.

g_sharedState.befund = g_sharedState.abholen.body.json.data.ergebnis[0];

Write results to the patient data group (8)

The final process step is to write the following to the patient data group:

  • the test result itself

  • the fact that a test result has been collected (this is filtered for)

A data group action is used for this.

General Enter a title for the action. Make sure that the "Change data record" option is activated.

Target data group Select the "Clinic" application. Since this application only contains the "Patients" data group, this is selected automatically.

Manipulation quantity Activate the "Simple filter" option. Select the file field "(PK)(S)ID <integer> " for both the target data group and the source data group.

Field assignment When assigning fields, the "findings" parameter from the processing context must be added to the source.

  1. Click on the icon.

    The "User-defined value" dialog box is displayed.

  2. Activate the "System value" option.

  3. Click on the icon.

    The "System value" dialog box is displayed.

    Type Select the "Processing context" value here.

    Value Enter the text "findings" here.

  4. Click on "OK".

    You are returned to the "Field assignment" dialog box.

  5. Click on the icon again.

    The "User-defined value" dialog box is displayed.

  6. Activate the "Static value" option.

  7. Click on the icon.

  8. The "Static value" dialog box is displayed.

    Data type Select the value "Boolean (logical value)" here.

  9. Click on "OK".

    The "Field assignment" tab now looks like this:

  10. Click on "OK".

You have now fully set up the process.