Gateway

The Gateway page allows you to configure Forward Nodes in Karnak. A Forward Node represents a DICOM Application Entity (AE) that receives DICOM instances and routes them to one or more destinations.

Forward Node

This page lists all the forward nodes configured in Karnak and allows you to create, edit, and delete them.

1. Create a Forward Node

Click the New forward node button. A form will appear:

1. Enter a unique value in the Forward AETitle field. AE Titles must not exceed 16 characters.
2. Click the Add button

The new forward node appears in the list and is automatically selected. Optionally, add a description and save your changes.

2. Forward Node List

All configured forward nodes are displayed in the left panel.

Select a forward node from the list to view and manage its configuration in the right panel.

3. Forward Node Parameters

In the details view, you can modify:

• Forward AETitle: The Application Entity Title of the forward node
• Description: An optional description to help identify the node’s purpose

Click the Save button to apply your changes.

4. Sources and Destinations

Each forward node can be configured with:

• Sources: Control which DICOM nodes are authorized to send data to this forward node
• Destinations: Define where received DICOM instances should be forwarded

4.1 Navigation

Use the tabs to switch between the Destinations and Sources views for the selected forward node.

4.2 Filtering

Destinations tab: Filter by destination description

Sources tab: Filter by AE Title and hostname

4.3 List

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

Click any item in the list to open its detailed view and edit its configuration.

4.4 Actions

The available action buttons depend on the active tab.

Destinations tab:

Create a new destination using either the DICOM or DICOM WEB (STOW) protocol. See the Destinations page for detailed configuration instructions.

Sources tab:

Create a new source to control which DICOM nodes can send data to this forward node. See the Sources page for detailed configuration instructions.

5. Forward Node Actions

Three action buttons are available:

Profiles

This page lists all profiles configured in Karnak and allows you to create, edit, and delete them. A profile defines the actions to apply to a DICOM instance before it is sent.

The Dicom Basic Profile is available by default and cannot be deleted. It is the reference de-identification profile based on the DICOM standard. For more details, see How does de-identification work?

1. Profile drag and drop area

Profiles can only be created by importing a YAML file using the top-right component of the Profiles view. You can select a file by clicking the Upload file... button or by dragging and dropping it into the area. The file is then loaded and analyzed. If no errors are found, a new profile is automatically created from the file and added to the profile list.

2. Profile list

All available profiles are listed here. A profile can evolve over time and appear multiple times in the list under the same name but with different versions.

When you select a profile in the list, its details are displayed on the right.

3. Profile details

This area shows the details of the selected profile.

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

Edit the field value, then click the checkmark button to save the changes or the cross button to discard them.

4. Profile actions

You can download the entire profile as a YAML file by clicking the button on the right or delete it by clicking the trash icon.

Download: Export the profile configuration as a YAML file for backup or sharing with other Karnak instances.

Delete: Remove the profile from Karnak. If the profile is in use by one or more projects, a warning message appears to prevent accidental deletion.

5. Profile upload feedback

When a YAML file is imported successfully, this view shows the details of the newly created profile.

If errors occur during profile creation, the profile is not added to the list. The errors are shown in the right panel with details about their cause, as illustrated below.

Projects

This page lists all projects configured in Karnak and lets you create, edit, 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:

1. Enter a name.
2. Select a profile.
3. Click Add.

The project is added to the list and its details appear in the right panel.

2. Project list

All available projects are listed in the left panel.
Selecting a project displays its details on the right.

3. Project details

In the details view you can:

• Change the project name.
• Change the de-identification profile.

Click Update to save your changes.

4. Project secret

The project secret is central to Karnak’s de-identification process.
It is a 32-character hexadecimal value.

• A secret is automatically generated when the project is created.
• In the details view, the secret is shown along with its creation date and time.

You can generate a new secret by clicking Generate Secret. When you do this:

• Previous secrets are kept in the database.
• You can select any previous secret to use again.

A destination is associated with a project for de-identification, as described in the Destination configuration.

To generate new values like UIDs and pseudonymize some patient information, Karnak uses a hash function seeded with the project secret. This makes the generated values unique per project and deterministic as long as the secret does not change.

Implications of changing the secret:

• If a DICOM instance is de-identified twice using the same project, secret, and profile, the resulting de-identified instances are identical.
• If the secret changes, de-identifying the same DICOM instance again with the same project and profile but the new secret will produce different de-identified instances.

Details about the algorithm and UID generation using the project secret are available here.

5. Action buttons

• Click Update to save any change made to a project.
• Click Remove to delete the selected project.

If the project is associated with a destination, deletion fails and an error message is displayed.

External Pseudonym

This page allows you to create or import pseudonyms that Karnak will use during de-identification. The de-identification process and how pseudonyms are used is detailed in the Pseudonym chapter.

De-identification is activated in the Destination configuration.

1. Choose a project

External pseudonyms are linked to a specific project. This allows Karnak to properly handle cases where:

• A patient participates in multiple clinical studies with different pseudonyms
• Potential pseudonym collisions occur between projects

2. Upload a CSV file

You can upload a CSV file containing external pseudonyms by:

• Clicking the Upload File button
• Dragging and dropping a file onto the upload area

2.1 CSV separator configuration

After selecting a file, a dialog appears asking for the CSV separator character. The default value is a comma (,).

Click Open CSV to proceed to the import configuration.

2.2 Preview and configuration

The CSV data is displayed in a grid for review and configuration.

From line: This field defines the starting row for the import. Use this to skip header rows or other non-data lines at the beginning of the file.

Column assignments: Map each CSV column to the corresponding pseudonym attribute. Only the Patient ID and External Pseudonym fields are required. Other fields are optional.

2.3 Import validation

Click Upload CSV to import the data. Karnak performs validation checks including:

• Duplicate Patient IDs
• Duplicate Pseudonyms
• Required field validation

If validation errors occur, they will be displayed and the import will be rejected.

3. Add a new patient manually

You can also add external pseudonyms manually by filling in the form fields:

• External Pseudonym (required)
• Patient ID (required)
• Patient First Name (optional)
• Patient Last Name (optional)
• Issuer of Patient ID (optional)

Click Add patient to add the entry to the external pseudonyms table.

4. Pseudonym management

4.1 Edit or delete individual entries

Each pseudonym row has action buttons:

• Edit: Modify the patient fields
• Delete: Remove the pseudonym from the cache

4.2 Bulk operations

Select multiple rows using the checkboxes on the left side of each row. Click Delete selected patients to remove all selected entries and confirm the action in the dialog.

4.3 Delete all patients

The Delete all patients button removes all external pseudonyms for the selected project only. Pseudonyms linked to other projects are not affected.

Pseudonym mapping

The pseudonym mapping page lets you look up the original data corresponding to pseudonyms that were added in the External pseudonym view. Note that the external pseudonym table is stored within a limited time frame.

1. Search field

To retrieve the original value:

1. Enter the pseudonym in the search field.
2. Click the Find button.

The search is case-sensitive.

2. Results

If a match is found, the result is displayed below the search field.

• The prefix [External] indicates that the match comes from the external pseudonym table, followed by the associated project.
• The original patient data is also displayed.

If no correspondence is found for the pseudonym, an error message is displayed, as illustrated below.

Monitoring

The Monitoring view allows you to track transfers in progress or view the history of recent transfers. The list is ordered chronologically, with the most recent transfers displayed first.

By default, the log retains the last 150,000 transfers. An automatic cleaning process runs to remove older entries when this limit is exceeded.

Detailed information for each transfer, including both original and de-identified attributes, can be viewed by clicking on a transfer row.

1. Filters

Filters allow you to search and narrow down the list of transfers. You can filter by:

• Date/Time: Range of the transfer.
• UIDs: Study, Series, or SOP Instance UID (matches original or de-identified values).
• Status: The outcome of the transfer (Not sent, Sent, All, Excluded, Error).

Transfer Statuses

The status of a transfer is color-coded:

• Sent (Green): The instance was successfully sent.
• Excluded (Orange): The instance was not sent due to configuration rules. This includes the SOP Class filter, destination conditions, or the use of ExcludeInstance() in the profile. The label indicates the specific reason for exclusion.
• Error (Red): The instance was not sent because an unexpected error occurred. The label indicates the error type.

2. Browsing

Use the navigation bar at the bottom of the view to browse through the pages of the transfer log.

3. Refresh

Click the refresh button to update the list with the most recent transfers.

4. Export

You can export the transfer log to a CSV file. The export function respects the currently active filters, so only the transfers displayed (or matching the criteria) will be included in the file.

Before exporting, you can customize the CSV format:

• Delimiter: Select the character used to separate fields.
• Quote character: Select the character used to enclose fields.

Once customized, click the export button to generate and download the CSV file.

DICOM Tools

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

• Test DICOM node availability using DICOM Echo
• Query a DICOM Worklist and display results
• Monitor multiple DICOM nodes using DICOM Echo and WADO protocols

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

DICOM Echo

This tool tests DICOM communication between two Application Entity Titles (AETs).

Configuration Fields

The following fields must be configured to execute an Echo test:

All fields are mandatory to execute the Echo test.

Running the Test

Click the Echo button to launch the connectivity test and DICOM Echo command.

Successful Test

Below is an example of a successful DICOM Echo test:

Failed Test

In this example, the “Called AETitle” value is intentionally incorrect. The network connectivity test succeeds, but the DICOM Echo fails, displaying the reason for the failure:

Select Node Utility

The Select Node popup simplifies configuration by allowing you to choose from pre-configured DICOM nodes.

Click the Select Node button to open the popup:

Configuration:

1. Choose the node type in the DICOM Nodes Type field
2. The DICOM Node dropdown updates automatically based on the selected type
3. Filter nodes by typing in the field (searches AET, hostname, port, or description)
4. Click Select to auto-fill the Called AETitle, Called Hostname, and Called Port fields

DICOM Worklist

This tool retrieves and displays the content of a DICOM Worklist to test connectivity and data retrieval.

Worklist Configuration

Configure the following fields to connect to a worklist:

All fields are mandatory to retrieve worklist content.

Worklist Query Filters

Additional optional fields are available to filter the results returned by the worklist:

• If no filters are specified, all worklist entries are retrieved
• Multiple filters can be combined to narrow results

Query Results

Click the Query Worklist button to execute the test and retrieve data.

Retrieved worklist data is displayed in a sortable table. Click any column header to sort by that column:

Select Worklist Utility

The Select Worklist popup allows you to choose from pre-configured worklists.

Click the Select Worklist button to open the popup:

Configuration:

1. Browse the list of available worklists
2. Filter by typing in the search field (searches AET, hostname, port, or description)
3. Click Select to auto-fill the Worklist AET, Worklist Hostname, and Worklist Port fields

Monitor

This tool monitors the status of DICOM nodes using both DICOM and WADO protocols, allowing you to verify connectivity and service availability.

DICOM Echo Monitoring

To test a DICOM node:

1. Select a DICOM node from the list
2. Click the Check button to launch the DICOM Echo test

Below is an example of a successful DICOM Echo monitoring test:

WADO Monitoring

To test WADO connectivity:

1. Select a DICOM node from the list
2. Navigate to the WADO tab
3. Click the Check button to launch the WADO test

Below is an example of a successful WADO test:

Authentication Configuration

This page allows you to configure authentication credentials for API calls. Since this information is sensitive, it is stored in an encrypted database table.

1. Create an Authentication Configuration

Click the Create Authentication Config button to begin. You’ll be prompted to enter a unique identifier for the new configuration.

Requirements:

• The identifier must be unique (an error will appear if a duplicate exists)
• We recommend avoiding spaces in the identifier for easier reference in profiles

Click Create to proceed. The configuration will be added to the list on the left and its details will appear in the right panel.

OAuth 2.0

Currently, OAuth 2.0 is the only supported authentication type.

Required fields:

How it works:

When an API call references this configuration (via the authConfig parameter):

1. Karnak checks if a valid access token is available
2. If yes, the token is added to the request for authentication
3. If no, a new token is requested using the configuration details
4. The API call proceeds with the authenticated token

2. Authentication Configuration List

All available authentication configurations are displayed in the left panel. Select a configuration to view its details on the right.

3. Configuration Details

The details view displays all configuration information in read-only mode.

To modify a configuration, you must delete it and create a new one.

4. Delete Configuration

To delete a configuration:

1. Select it from the list
2. Click the red trash bin icon next to its identifier
3. Confirm the deletion in the popup

Kheops

Create a destination album

To create a Kheops album as a destination, configure the following values:

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

For detailed instructions on creating an album, refer to the official Kheops documentation.

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

1. Create a new token

2. Configure token permissions

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

3. Copy the authentication token

Copy the authentication token value to use in the header of your Karnak destination.

For complete instructions on creating and configuring a STOW destination in Karnak, see Destinations.

Switching to different Kheops albums

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

This feature is useful for sharing specific studies with research groups without exposing the entire album. For example, you can send a cohort of studies to collaborators while maintaining data isolation.

This functionality leverages the Kheops API to distribute data to multiple locations without creating additional destinations in Karnak. Data is automatically split according to rules defined in Kheops, ensuring that authorized users access only relevant data.

The following diagram illustrates how data flows through Karnak and is distributed 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 condition syntax and usage are detailed in the Conditions page.

Portable distribution

Karnak Gateway can be distributed as a portable application, allowing you to run it without installing it on your system.

The purpose of this distribution is to provide an easy way to use Karnak Gateway for deidentification tasks on a local machine. It is typically used by researchers in collaborative projects that require a consistent method for de-identifying DICOM data with a shared de-identification profile.

Download Karnak portable distribution

Run Karnak Gateway portable

With the portable distribution, Karnak Gateway can be run directly from the extracted folder from the downloaded archive.

Double-click on the `run.bat` file to launch Karnak Gateway.

Double-click on the `run.sh` file to launch Karnak Gateway or execute it in the terminal.

Execute the `run.sh` file in the terminal to launch Karnak Gateway. 

Once the application is running, you can access the Karnak Gateway web interface by opening your web browser and navigating to http://localhost:8081. The default login credentials are:

• Username: admin
• Password: karnak

User guide

For detailed instructions on how to use Karnak Gateway, please refer to the Karnak Gateway User Guide. This distribution includes new features in the Forward Node view that are not covered in the main user guide:

Add a local destination

Click the LOCAL button A to add a destination that saves DICOM instances to the dicom folder in the portable distribution’s extracted directory.

This button automatically configures a DICOM destination for local storage. For other options related to de-identification and forwarding rules, refer to the main user guide.

Upload local folder

Click the Upload Local Folder button B to select a local folder containing DICOM instances that you want to forward through the selected forward node destinations.