Gateway

Forward Node

This page lists all the forward nodes configured in Karnak and allows to edit, create and delete nodes. The forward node contains the configuration of the DICOM node’s Application Entity.

1. Creation of a forward node

After clicking on the New Forward Node button, a form will appear as illustrated below.

To create a new forward node, the “Forward AETitle” input must be filled, then click on the “Add” button. Once added, it will appear in the list of forward nodes and will be selected. The Forward AETitle must be unique.

2. Forward node list

This list displays all the forward nodes created in the Karnak instance. A forward node can be selected to view and manage its details on the right panel.

3. Forward node parameters

The value of the forward AETitle and its description can be modified after creation on the detailed view of the forward node. To save your changes, click on the “Save” button.

4. Forward node sources or destinations

In the forward node’s details, source control can be configured, checking if the received DICOM is provided from a known source. Destinations can also be created and configured to distribute received DICOM instances. These destinations can communicate with the DICOM or DICOM WEB protocol.

4.1 Navigation

Depending on the selected tab, the list of destinations or sources associated to this forward node will be displayed.

4.2 Filtering

The destination’s list filter is applied to the destination description.

The source’s list filter is applied to the AE title, hostname and description source.

4.3 List

All the destinations or sources associated to the forward node are displayed here.

Click on an element of the list will open its detailed view, also allowing its edition.

4.4 Actions

The action buttons depend on the current tab selected.

In the Destinations view, two actions are displayed, corresponding to the protocol associated to the destination being created. The available protocols are either DICOM or DICOM WEB. The Destination creation is detailed in the section Destinations.

In the Sources view, a button for creating a new Source is displayed. The Source creation is detailed in the Sources page.

5. Forward node actions

Three actions are available:

• Save: saves the changes made on the forward node parameters
• Delete: deletes the selected forward node
• Cancel: reverts the changes made on the forward node parameters

Profiles

This page lists all the profiles configured in Karnak and allows to edit, create and delete them. A profile contains a definition of actions that should be applied to a DICOM instance before being sent.

The “Dicom Basic Profile” is present by default and cannot be deleted. This profile is detailed in the section How does de-identification work?. This profile cannot be deleted or edited, except for the value of default issuer of patient ID.

1. Profile drag and drop area

A profile can only be created by importing a YAML file using the top right component of the Profiles view. The file can be selected by clicking the “Upload File” button or drag and dropped there. It will be loaded and analyzed. If there are no errors, a new profile will automatically be created with the content of the file, and added to the list of profiles.

2. Profile list

All the profiles available are listed here. A profile can evolve and be present in the list under the same name but with a different version.

By selecting a profile in the list, its details are displayed on the right.

3. Profile details

This area contains the details of a profile.

If the profile is selected in the list, its details will appear on the right panel.

Some information can be edited such as the name, version and minimum required version of Karnak, by clicking on the pen icon.

The field’s value can be edited, the changes are saved by clicking on the check mark button and reverted by clicking on the cross button.

The rest of the profile cannot be modified.

The entire profile can be downloaded as a YAML file by clicking on the button on the right or deleted by clicking on the button on the left.

If a YAML file was imported, this view will display the details of the newly created profile, if no errors occurred during the import and the creation was successful.

If some errors occurred during the profile creation, the profile won’t be created and added to the profiles’ list. The errors will be displayed in the right panel with details about the source of the error(s). An example is shown below.

Projects

This page lists all the projects configured in Karnak and allows to edit, create and delete them. A project is linked to a profile and contains a secret used for de-identification.

1. Create a project

To create a new project, the project name field and the profile select box must be filled, then click on the button “Add”. The project will be added to the list of projects and its details displayed in the right panel.

2. Project list

All the projects available are listed here. By selecting a project in the list, its details are displayed on the right.

3. Project details

In the details view, the project name and de-identification profile can be modified. The changes must then be saved using the “Update” button.

4. Project secret

The project’s secret is at the core of Karnak, more specifically for the de-identification process. It is a 32-character hexadecimal value.

The project’s secret is automatically generated when the project is created. The date and time of the secret’s creation are appended at the end of the secret in the details view.

A new secret can be generated by clicking the “Generate Secret” button. If new secrets are generated, previous secrets are saved in the database. Previous versions can be selected to be used.

A destination is associated with a project regarding the de-identification, as explained in the Destination configuration

In order to generate new values, as well as pseudonymize certain patient information, a hash function is used with the secret as seed to have a project-wise unique yet determinist generated value. When the secret is changed, it must be taken into consideration that this determinist mechanism will be broken. If a DICOM instance is de-identified twice using the same project, same secret and same profile, the resulting de-identified instances will be the equal. If the secret is changed, then the same DICOM instance de-identified twice, using the same project, same profile but a new secret will result in different de-identified instances.

Details about the algorithm and UID generation using the project’s secret can be found here.

5. Action buttons

Any change done on the project’s details must be persisted using the “Update” button.

The selected project can be deleted by clicking on the “Remove” button. If the project is associated to a destination, an error message will be displayed.

External Pseudonym

In this page, pseudonyms can be created or imported, and will then be used during de-identification by Karnak. The de-identification process and how the pseudonym is used is detailed in the Pseudonym chapter.

The activation of de-identification is done in the Destination configuration.

The created or imported pseudonyms in this page are stored in a cache that will be cleared after a maximum of 7 days. The pseudonyms saved will also be lost in case Karnak is restarted.

1. Choose a project

External pseudonyms are linked to a project. It allows Karnak to handle properly the case where a patient is participating in multiple clinical studies, as well as potential collisions.

2. Upload a CSV file

A CSV file containing external pseudonyms can be uploaded by clicking the “Upload File” button or drag and dropped there. It launches the import process.

A pop-up is displayed asking for the separator of the CSV file. By default, the value is set to “,”.

After clicking on the “Open CSV” button, a grid is displayed containing the CSV file data.

2.1 From line

This field defines the index of the first line of the CSV file to import. It allows to skip a number of lines at the beginning of the file, especially if it contains headers.

2.2 Columns assignments

In this view, the CSV columns are associated with the corresponding pseudonym attributes. All the fields are mandatory, except the Issuer of patient ID.

2.3 Upload CSV

The “Upload CSV” button will start importing the CSV data. It performs data validation on the data, such as Patient ID or Pseudonym duplication.

3. Add a new patient

It’s also possible to add an external pseudonym manually. All the fields are mandatory, except the Issuer of patient ID.

Clicking on “Add patient” will add the entered data into the external pseudonyms table.

4. Delete all patients

This button will delete all the external pseudonyms stored in the cache but linked to the selected project. The other pseudonyms linked to other projects won’t be impacted.

A popup will be displayed before the deletion is effectively done, asking for the confirmation of the user.

5. Pseudonym edition

Once stored in the cache, it is possible to edit the patient fields by clicking on the “Edit” button on the external pseudonym row that should be modified. The external pseudonym can also be deleted by clicking in the “Delete” button on the external pseudonym row that should be removed.

Multiple rows can be selected by checking the boxes on the left of each row. These rows can be deleted by clicking on the “Delete selected patients” at the top of the external pseudonyms table. Again, a confirmation is asked before the deletion is performed.

Pseudonym mapping

The pseudonym mapping is used to retrieve the mapping of pseudonyms added in the External pseudonym view.

1. Search field

In order to retrieve the original value, enter the pseudonym and click on the “Find” button. The search is case-sensitive.

2. Results

If a correspondence is found, it is displayed below. “[External]” means that the match was found in the external pseudonym table followed by the associated project. The original patient data is displayed as well.

If that pseudonym has no correspondence, an error message will be displayed as illustrated below.

Monitoring

Monitoring view is used to follow transfers in progress or recent transfers.

Currently limited to 150000 transfers, it is possible to browse the different pages via the navigation bar at the bottom center of the view

An automatic cleaning occurs on the monitoring tables, if the limit is exceeded.

The view displays the most recent transfers and is ordered with most recent first.

Filters are available to easily browse or find a transfer.

It is possible to export the list of transfers via the export functionality in csv format depending on the filters selected.

By clicking on a transfer, its details are displayed containing the de-identified and original information.

1. Filters

Filters allow to easily search and browse transfers. It is possible to filter by:

• Date/Time of transfers
• Study UID (original or de-identified)
• Serie UID (original or de-identified)
• Sop Instance UID (original or de-identified)
• Status of the transfer (not sent, sent, all, excluded and error)

The status of a transfer is defined as follows :

• if the instance was successfully sent, it appears with the label “Sent” in green
• if the instance was not sent because of the SOP filter, the destination condition or the use of ExcludeInstance() in the profile, it appears in orange with a label corresponding to the reason why it was excluded
• if the instance was not sent because an unexpected error occurred, it will appear in red with a label corresponding to the error that occurred

2. Browsing

It is possible to go through the different pages of the list of transfers by using the navigation bar.

3. Refresh

By clicking on the refresh button, the list of transfers is updated with last transfers.

4. Export

Export settings allow to customize the csv before exporting it. It is possible to change the csv delimiter and the quote character of the file.

Once customized, the export is launched by clicking on the export button.

Export will use the filters selected in the monitoring view and export only transfers matching the filters’ criteria.

DICOM tools

This page provides an overview of the utility tools available in the DICOM Tools module, designed to assist with connectivity, query, and status checks for DICOM servers. These tools enable users to:

• Test the availability of a DICOM node using DICOM Echo
• Query a DICOM Worklist and display the DICOM result
• Group and monitor DICOM nodes using DICOM Echo and WADO protocols

The different modules are accessed through the tabs at the top of the page.

Those functionalities will be presented in details below.

DICOM Echo tab

This tool tests the DICOM communication between 2 AETs.

The field “Calling AETitle” defines the identity of the calling DICOM entity. The field “Called AETitle” defines the identity of the DICOM entity to test. The field “Called Hostname” and “Called Port” define the hostname and port of the DICOM node to test.

All the fields are mandatory to execute the ECHO test.

Clicking on the button “Echo” will launch the connectivity test and DICOM Echo command. Below is an example of a successful test.

In this example, the “Called AETitle” value is purposely wrong, we can see that the network connectivity test is successful but not the DICOM Echo, displaying the reason of the failure.

Select Node Utility

The Select Node popup can be displayed by clicking on the “Select Node” button.

The type of DICOM Node is set in the “Dicom Nodes Type” field. The list of values in the “Dicom Node” field is then updated according to the selected node type. The values can be filtered in this field by typing directly a string that will be matched against the AET, hostname, port or description.

Clicking on the “Select” button will automatically fill the Called AETitle, Called Hostname and Called Port fields with the values of the selected DICOM node.

DICOM Worklist tab

This tool retrieves the content of a DICOM Worklist and tests their behavior and connectivity.

Worklist Configuration

The field “Calling AETitle” defines the identity of the calling DICOM entity. The field “Worklist AET” defines the identity of the worklist to test. The field “Worklist Hostname” and “Worklist Port” define the hostname and port of the worklist to test.

All the fields are mandatory to retrieve the worklist content.

Worklist Query

Additionally, some fields are defined to filter the results returned by the worklist. These fields are optional. If none are filled, no filters are applied and all the elements of the worklist are retrieved.

Query Results

Clicking on the button “Select Worklist” will launch the test and data retrieval. The retrieved worklist data is displayed in a table, that can be sorted by column, by clicking on its header.

Select Worklist Utility

The Select Worklist popup can be displayed by clicking on the “Select Worklist” button.

A list of available worklist will be displayed and a node can be selected. The worklists can be filtered in this field by typing directly a string that will be matched against the AET, hostname, port or description.

Clicking on the “Select” button will automatically fill the Worklist AET, Worklist Hostname and Worklist Port fields with the values of the selected DICOM worklist.

Monitor tab

This tool checks the status of DICOM nodes using both DICOM and WADO protocols.

DICOM ECHO

A DICOM node must be selected in the list, and the button “Check” can be clicked to launch the DICOM Echo test for that node. Below is an example of a successful DICOM Echo test.

WADO

A DICOM node must be selected in the list, and the button “Check” can be clicked to launch the WADO test for that node. Below is an example of a successful WADO test.

Kheops

Create a destination album

To create a Kheops album as a destination, the following values must be set:

• Protocol: STOW
• DICOM endpoint: /api/studies

To create the album destination, please refer to the official documentation. of Kheops.

Once the album is created, please follow these steps to configure the album as a destination in Karnak.

1. Create a new token

2. Give WRITE permission to the token and set the expiration date

3. Copy the authentication token value to be used in the header of your Karnak destination

The creation and configuration of a STOW Destination in Karnak is detailed here.

Switching in different Kheops albums

When a destination points to a Kheops album, the data can be propagated to underlying albums.

This is useful when a cohort of studies is sent to a research group for example, without sharing all the album studies.

Studies cannot be shared between different Kheops instances, one destination must be configured in Karnak per Kheops instance.

The purpose of this functionality is to take advantage of the Kheops API to propagate the data to different places without having to create new destinations in Karnak. At the same time, the data is split according to rules defined in Kheops to prevent data leakage and allow the authorized persons to access only the relevant data and not all the main album.

The following diagram illustrates the behavior of data being processed through Karnak and sent to multiple Kheops albums.

graph LR;
  A(DICOM Data) --> B[Karnak]
  
  subgraph Kheops
    D[Main Album] --> E[Album X]
    D --> F[Album Y]
  end
  
  B --> D

First, a DICOM instance is received by Karnak. After processing it, it sends the instance to the main Kheops album. Depending on existing rules and conditions, the instance will also be shared to the album X and Y.

Create a switching Kheops album

To share a DICOM instance in different Kheops albums, the following fields must be filled and validated by clicking on Add button.

The condition field defines a condition to enable sharing an instance to a specific album if it is evaluated to true.

The conditions syntax and usage is detailed in the Conditions page.