Gateway

Forward Node

This page allows the creation of a forward node and its edition. All the forward nodes present in your Karnak are listed here. The forward node will configure the Application Entity of your DICOM node.

1. Creation of a forward node

Once clicked on the button “New forward node”, a form will appear, as below, instead of the “New forward node” button (It will replace it).

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

2. Forward node list

This list displays all the forward nodes created in your Karnak instance. You can select a forward node to view and manage its details on the right panel.

3. Forward node inputs

You can directly modify the value of the forward AETitle and its description. To save your changes, you have to click on the “Save” action button.

4. Forward node sources or destinations

In an Application Entity, you can add source control, which checks if the received DICOM is provided from a known source. You can also create one or more destinations to distribute received DICOM instance. These destinations can communicate with the DICOM or DICOM WEB protocol.

4.1 Sources or destinations navigation

Depending on the navigation selected, between sources and destinations, the list and the action buttons will change.

4.2 Filter in destinations or sources list

The destination filter will use the destination description.

The source filter will use the AE title, hostname and description source.

4.3 Destination or sources list

All the destinations or sources, depending on the navigation selected, associated to the forward node is listed here.

You can click on a destination or source present in this list to view details or to modify it.

4.4 Action buttons

The action buttons will change depending the navigation selected.

For a destination, these buttons defined the protocol you can use to create a destination. The protocol can be DICOM or DICOM WEB. The details for the destination creation will be explained below in the section Destinations.

If you click on the DICOM button, the DICOM destination creation page will appear.

If you click on the STOW button, the DICOM WEB destination creation page will appear.

For a source, the illustration below show the button. The details for the source creation will be explained below in the section Sources.

If you click on the the Sources button, the source creation page will appear.

5. Action buttons

You have three action buttons available.

• “Save” will save your change apply on the forward node inputs.
• “Delete” will delete your forward node
• “Cancel” will cancel the changes applied on the forward node inputs.

Destinations

Beware, to activate the de-identification in a destination, you must first create a new project.

You can create a destination that sends your studies using the DICOM or STOW protocol.

DICOM destination

For a DICOM destination the following is mandatory:

• AETitle
• Hostname
• Port ( Should be between 1 and 65535)

1. Destination field

These fields define the destination to which Karnak should send.

The Condition is a field to define a condition for the destination. If the condition is met, the destination will be activated. See Destination Conditions for more details.

The hostname and the port will be used to define the host in case the “Use AETitle destination” is not checked.

2. Transfer Syntax

This field will define the transfer syntax used.

3. Use AETitle destination

If “Use AETitle destination” is checked, the AETitle defined will be used as host.

4. Notifications

These fields will allow you to define the emails to be notified during various events that take place during the sending.

• Error subject prefix: Prefix of the email object when containing an issue. Default value: ERROR.
• Subject pattern: Pattern of the email object, see this link. Default value: [Karnak Notification] %s %.30s.
• Subject values: Values injected in the pattern [PatientID StudyDescription StudyDate StudyInstanceUID]. Default value: PatientID,StudyDescription
• Interval: Interval in seconds for sending a notification (when no new image is arrived in the archive folder). Default value: 45

5. De-identification

The de-identification in the DICOM destination will be explained below, in the section Activate the de-identification

6. Authorized SOPs

This field allows you to define a filter on a list of SOPs. The chosen SOPs will serve as a filter for Karnak when sending. This allow you to define a destination which is applied only for SOPs of your choice. The SOPs present in the list are defined by DICOM.

If “Authorized SOPs” is checked, you can define one or more SOPs.

If “Authorized SOPs” is not checked, Karnak will not apply a SOP filter and will let all SOPs pass.

The following illustration shows the list of SOPs with two SOPs selected.

7. Enable the destination

This field allows you to enable or disable a destination.

If “Enable destination” is checked, the destination is enable.

If “Enable destination” is not checked, the destination is disable.

8. Actions buttons

You have three action buttons available.

• “Save” will create a new DICOM destination or update your modifications on the selected DICOM destination.
• “Delete” will delete the selected DICOM destination.
• “Cancel” will cancel the changes applied on the selected source. You will be redirect to the forward node.

STOW destination

For a STOW destination the following is mandatory:

• URL

1. Destination field

The URL is the DICOM endpoint of your final destination.

The Condition is a field to define a condition for the destination. If the condition is met, the destination will be activated. See Destination Conditions for more details.

The URL credentials is the STOW-RS service (format is "user:password")

2. Destination headers

This field will contains the headers for HTTP request.

To add the header Authorization: Bearer 123456790 you must write following the format below:

<key>Authorization</key>
<value>Bearer 1234567890</value>

3. Transfer Syntax

This field will define the transfer syntax used.

4. Notifications

These fields will allow you to define the emails to be notified during various events that take place during the sending.

• Error subject prefix: Prefix of the email object when containing an issue. Default value: ERROR.
• Subject pattern: Pattern of the email object, see this link. Default value: [Karnak Notification] %s %.30s.
• Subject values: Values injected in the pattern [PatientID StudyDescription StudyDate StudyInstanceUID]. Default value: PatientID,StudyDescription
• Interval: Interval in seconds for sending a notification (when no new image is arrived in the archive folder). Default value: 45

5. De-identification

The de-identification in the STOW destination will be explained below, in the section Activate the de-identification

6. Authorized SOPs

This field allows you to define a filter on a list of SOPs. The chosen SOPs will serve as a filter for Karnak when sending. This allow you to define a destination which is applied only for SOPs of your choice. The SOPs present in the list are defined by DICOM.

If “Authorized SOPs” is checked, you can define one or more SOPs.

If “Authorized SOPs” is not checked, Karnak will not apply a SOP filter and will let all SOPs pass.

The following illustration shows the list of SOPs with two SOPs selected.

7. Switching in different Kheops albums

You have the possibility of sharing your data in different Kheops album. For this you must use a DICOM endpoint from Kheops.

The purpose of this functionality is to allow sending your data to a single destination and to use the Kheops API to propagate your data to different places without having to create a new destination.

The following illustration show a scenario of this functionality. The illustrated scenario allows you to send a DICOM data to Karnak. Karnak has a destination defined to send the data to a Kheops album (Album main). This means that this album will regroup all the data sent by KANRAK. To prevent researchers or end users from having access to all the data, the data will be shared in other albums according to defined conditions.

1. The DICOM data is send to Karnak
2. Karnak send the data to the album main in Kheops
3. The data will be shared in the album X and in the album Y

Details for configuring this feature are explained in the Kheops chapter.

8. Enable the destination

This field allows you to enable or disable a destination.

If “Enable destination” is checked, the destination is enable.

If “Enable destination” is not checked, the destination is disable.

9. Actions buttons

You have three action buttons available.

• “Save” will create a new STOW destination or update your modifications on the selected STOW destination.
• “Delete” will delete the selected STOW destination.
• “Cancel” will cancel the changes applied on the selected source. You will be redirect to the forward node.

Activate the de-identification

To use de-identification, a project must be present. See create a new project if you haven’t already created a project.

When you created a new destination, “Activate the de-identification” is not checked. When you check the box, Karnak will react in two different ways depending on whether you have a project or not.

If you have not yet created a project a pop up will appear asking you to create a project, as illustrated below.

• Create a project will redirect you to the page project. Beware, if you click on this button your configuration already made will be lost, save it first.

• Continue will close the pop-up and the de-identification will be unchecked.

If you have already create the project, you can configure the de-identifcation.

1. Project

Here you can select the project to use for de-identification.

A message below shows you which profile is associated with the selected project.

2. Pseudonym Type

2.1 By default, you can choose four different type of pseudonym.

2.2 Is an exemple of external id provider injected in Karnak (for more details, see ExternalID provider).

Pseudonym is generated by Mainzelliste will generate the pseudonym and store it by using Mainzelliste.

Pseudonym that has already been entered manually in Mainzelliste will use the pseudonym that an user has added by using the mainzelliste pseudonym page. Pseudonym are stored in mainzelliste.

Pseudonym is already store in Karnak will use the pseudonym that an user has added by using the pseudonym page. Pseudonym added alive in the Karnak cache. Beware if the patient to be de-identified is not present in the Karnak cache, it will not be sent.

Pseudonym is in a DICOM tag, will look for the pseudonym in a DICOM tag. The illustration below shows the different elements to configure.

1 Use as Patient Name

Instead to use the generated patient name by Karnak, it will contains the pseudonym find in the DICOM tag.

2 Fields to find the pseudonym

This fields are used to define the configuration to find the pseudonym.

Tag - will contain the tag where Karnak should look for the pseudonym.

Delimiter - will contain the delimiter to use for split the value of the tag. (Optionnal)

Position - will contain the position where the pseudonym is after the split. (Optionnal)

In case the delimiter and the position fields are not defined, Karnak will directly use the value present in the given tag.

3 Save the pseudonym

If “Save pseudonym” is checked, Karnak will save the patient and his pseudonym in Mainzelliste.

Sources

A source is used to perform control over the sending entity to the associated forward node. It will check if the received DICOM is provided from an AET known.

In the case that no source is defined, the verification does not take place and the forward node can receive data from any AET.

1. Form input

All the fields are optional, excepted the AETitle, which is mandatory.

If the “Check the hostname” box is checked, Karnak also checks the hostname.

2. Action buttons

You have three action buttons available.

• “Save” will create a new source or update your modifications on the selected source.
• “Delete” will delete the selected source.
• “Cancel” will cancel the changes applied on the selected source. You will be redirect to the forward node.

Profiles

The profile page allows you to manage your profiles. On this page.

Karnak has the “Dicom Basic Profile” profile by default, the details about this profile is explained 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

As presented below, you can drag and drop your yaml profile configuration.

2. Profile list

All the profiles available in your Karnak instance are listed here. To view Profile details, you can click on a profile.

3. Profile details

This panel will change depending on your action.

Once you have clicked on a profile, this panel will display the details about the chosen profile.

If you have drag and drop your profile, the details about the profile uploaded will be presented. In case your profile contains any errors, it will show where and what the error are, as the illustration below.

The following table shows you the different action of icons present in the profile details.

Icons	Action associated to the icon
	Download the profile
	Remove the profile. However, if a profile is used by a project, you will not be able to delete it
	Edit the name, version, minimum version Karnak required and default issuer of patient ID profile.

Projects

When you want to use Karnak’s de-identification methods, you need to associate a project with your destination. This project defines the profile to be used as weel as the integrity of the data using a secret. The secret makes it possible to maintain consistency between the data to be de-identified, see Action U, Generate a new UID for more details.

The project page allows you to manage your projects. On this page, you can perform the following actions:

1. Create a project

To create a new project, you must give a project name and choose a profile that will be used for de-identification. To validate your choose, you can click on the button “Add”.

The list of profiles that you can associated with a project are the profiles that you have uploaded, see Profile drag and drop area.

2. Project list

All the projects available in your Karnak instance are listed here. You can click on a project to view its details in the right panel.

3. Project metadata

You can change the project name and the de-identification profile using these inputs. By clicking on the “Update” button, see Action buttons, you save your changes.

4. Project secret

The secret is generated automatically at the creation of a project. You can generate a new secret by using the “Generate Secret” button.

If new secrets are generated, previous secrets are saved in database in order to be able to use them again if needed.

The history of secrets is listed in the secret combobox with the creation date.

In order to take into account the new generated secret, project has to be saved by clicking on the update button.

• A secret is a hexadecimal value

• Must contains 32 characters

5. Action buttons

Button	Action
	Save your changes apply to project inputs
	Remove the project. However, if a project is used by a destination, you will not be able to delete it

External Pseudonym

Karnak will always use a given pseudonym when de-identifying. In this page, it is possible to import your data manually or from a CSV file your existing pseudonyms. So that Karnak can de-identify your studies while using your pseudonyms.

The pseudonyms are stored for a short period of time. Your data is stored in the cache for maximum 7 days. If Karnak is restarted, the uploaded data will be lost.

1. Choose a project

Each external pseudonym is linked to a project. In this way, there is no risk of collision between different external pseudonyms, if they are two similar pseudonym but patient information is different.

2. Upload a CSV file

To upload a CSV file containing external pseudonyms, you must click in the “Upload File” button.

A pop-up will appear and offer to enter the separator character of the CSV file. In the exemple bellow, we use the “,” separator.

After click “Open CSV” button, a grid will be appear with the CSV file content.

2.1 From line

This input field allows you to indicate from which line you want to start reading the CSV file. Your CSV file may contain headers. If these headers are in line 1 like the above example (EXTERNALID, PATIENTID, LASTNAME, FIRSTNAME, ISSUER_OF_PATIENTID), you can specify the entry “From line” to the value 2.

2.2 Columns assignements

Fill in the correct fields with the corresponding columns. All the fields are mandatory, excepted the Issuer of patient ID.

2.3 Upload CSV

Click to the “Upload CSV” button to validate the fields with the correct columns to store the externals pseudonyms in Karnak.

3. Add a new patient

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

4. Pseudonym kept temporarily

As explained in the introduction, the pseudonyms are stored for a short period of time in Karnak. It’s possible to edit the patient fields by clicking “Edit"button or delete a patient by clicking “Delete” button.

Pseudonym mapping

The pseudonym mapping is used to retrieve the mapping of pseudonyms added in the views External pseudonym and Mainzelliste pseudonym.

In order to retrieve the mapping enter the desired pseudonym and click on the Find button.

If found, the external or mainzelliste pseudonym mapping will be displayed.

Otherwise some messages will indicate no mapping found.

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 display the most recent transfers and is ordered with most recent first.

Filters allow to limit the results and makes it easier to 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, it opens details of the information original and deidentified.

1. Filters

Filters allow to ease the search of transfers. It is possible to filter by:

• Date/Time of transfers
• Study UID (original or deidentified)
• Serie UID (original or deidentified)
• Sop Instance UID (original or deidentified)
• Status of the transfer (not sent, sent, all)

2. Browsing

It is possible to go throw 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 customize, the export is launched by clicking on the export button.

Export will use the filters selected in the monitoring view and export only transfers corresponding to the filters.

DICOM tools

Kheops

Create a destination album

To create a Kheops album as a destination you must use:

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

First create the album destination, please refer to the official documentation of Kheops to create a new album.

1 Create a new token

2 Give WRITE permission to the token

3 Set a token expiration date

4 Copy the token value to be used in the header of your Karnak destination

Below is an example of creating headers with the token value:

<key>Authorization</key>
<value>Bearer y8KlxLhhq8yeEPpOHkhbHg</value>

Switching in different Kheops albums

When you create a destination that points to a Kheops album, you can propagate your data to underlying albums.

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

Beware, the study sharing between album, must be done only within the same Kheops. Studies cannot be shared between different Kheops instances, you should create one destination per Kheops instance.

The purpose of this functionality is to allow sending your data to a single destination and to use the Kheops API to propagate your data to different places without having to create a new destination.

The following illustration show a scenario of this functionality. The illustrated scenario allows you to send a DICOM data to Karnak. Karnak has a destination defined to send the data to a Kheops album (Album main). This means that this album will regroup all the data sent by KANRAK. To prevent researchers or end users from having access to all the data, the data will be shared in other albums according to defined conditions.

1. The DICOM data is send to Karnak
2. Karnak send the data to the album main in Kheops
3. The data will be shared in the album X and in the album Y

Create a switching Kheops album

To share your DICOM in different Kheops album, you must complete the following fields and validate them by clicking on Add button.

The destination is the album where the studies will be shared.

The source is the album main, where all studies are sent.

The condition field will allow you to assign a condition to enable sharing to the destination.

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