Token Generation

To launch eUnity from an external application, a secure launch token must first be generated. This token contains the information required to identify the study or studies to display and is encrypted using an AdvaPACS API key. The generated token is passed to eUnity as part of the launch URL, allowing AdvaPACS to validate the request and open the requested studies in the viewer.

Before proceeding, ensure you have obtained an Access Key ID and Access Key Secret with permission to generate eUnity launch tokens.

Launch Parameters

The following parameters can be included when generating a token:

Parameter	Description
user	AdvaPACS username to use when launching eUnity. The user must exist in AdvaPACS and have permission to access eUnity.
accession_number	Accession Number of the study to display. Multiple accession numbers may be provided.
patient_id	Patient ID associated with the study or studies being displayed.
studyUID	Study Instance UID of the study to display.

note

Only one of accession_number or studyUID may be supplied in a single launch request.

Example Launch Scenarios

Open a Study by Accession Number

patient_id=ABC123
accession_number=65264575
user=john.doe

Open a Study by Study Instance UID

studyUID=1.2.840.113619.2.55.3.2831164357.781.1599753090.467
user=john.doe

Open Multiple Studies

patient_id=ABC123|ABC123
accession_number=65264575|8546258
user=john.doe

Generate A Token

To launch eUnity, a token must be generated and signed with an AdvaPACS API Key so AdvaPACS can verify it.

To obtain an API Key that can be used with eUnity, please contact support.

The following parameters are supported when launching studies.

user this shall match the username of the user in AdvaPACS. This will ensure they are assigned the expected permissions given in AdvaPACS and their eUnity user settings are saved correctly.

accession_number shall be the Accession Number of the study to display.

patient_id shall be the Patient ID of the study to display.

studyUID shall be the Study Instance UID for the study to display.

note

Only one of studyUID or accession_number can be provided.

These URLs show some examples of different display scenarios.

Display single study by accession number.

...?patient_id=ABC123&accession_number=65264575&user=john.doe

Display single study by Study Instance UID.

...?studyUID=1.2.3.4.5&user=john.doe

Display multiple studies via accession number.

...?patient_id=ABC123|ABC123&accession_number=65264575|8546258&user=john.doe

Encrypt Token

Once the URL query has been assembled, it must be encrypted with the AdvaPACS Access Key Secret.

Example Java Code

package com.advahealthsolutions.advapacs.example;

import javax.crypto.BadPaddingException;
import javax.crypto.Cipher;
import javax.crypto.IllegalBlockSizeException;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.nio.ByteBuffer;
import java.nio.charset.StandardCharsets;
import java.security.*;
import java.time.Instant;
import java.util.Base64;

public class EunityExample {

    private static final SecureRandom secureRandom = new SecureRandom();

    public static void main(String[] args) throws InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException {
        String advapacsRegion = "aus";
        String accessKeyId = "<Access Key ID>";
        String accessKeySecret = "<Access Key Secret>";

        String patientId = "<Patient ID>";
        String accessionNumber = "<Accession Number>";

        String token = encryptToken("patient_id=%s&accession_number=%s&expiry=%s".formatted(patientId, accessionNumber, Instant.now().plusSeconds(60).getEpochSecond()), accessKeySecret);
        System.out.println("https://%s.eunity.advapacs.com/e/viewer?CLOAccessKeyID=%s&arg=%s".formatted(advapacsRegion, accessKeyId, token));
    }

    private static String encryptToken(String token, String accessKeySecret) throws NoSuchAlgorithmException, NoSuchPaddingException, InvalidKeyException, InvalidAlgorithmParameterException, IllegalBlockSizeException, BadPaddingException {
        final byte[] iv = new byte[12];
        secureRandom.nextBytes(iv);
        final int tLEN = 128;
        final GCMParameterSpec parameterSpec = new GCMParameterSpec(tLEN, iv);
        final Key secretKey = buildDefaultKey(accessKeySecret);
        final Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        cipher.init(Cipher.ENCRYPT_MODE, secretKey, parameterSpec);
        final byte[] encryptedBytes = cipher.doFinal(token.getBytes(StandardCharsets.UTF_8));
        final ByteBuffer byteBuffer = ByteBuffer.allocate(4 + iv.length + encryptedBytes.length);
        byteBuffer.putInt(iv.length);
        byteBuffer.put(iv);
        byteBuffer.put(encryptedBytes);
        final byte[] encryptedBytesAndIV = byteBuffer.array();
        return Base64.getUrlEncoder().encodeToString(encryptedBytesAndIV);
    }

    private static Key buildDefaultKey(String secretKey) throws NoSuchAlgorithmException {
        final MessageDigest digester = MessageDigest.getInstance("SHA-256");
        digester.update(secretKey.getBytes(StandardCharsets.UTF_8));
        final byte[] key = digester.digest();
        return new SecretKeySpec(key, "AES");
    }
}

Launch eUnity

To display the studies in eUnity, the generated token shall be passed to eUnity with the following format.

<region> shall be set to the region code associated with your AdvaPACS tenant. For example aus for Australia.

<access key id> shall be set to the Access Key ID associated with the Access Key Secret used to encrypt the URL.

<token> shall be set to the token generated previously.

https://<region>.eunity.advapacs.com/e/viewer?CLOAccessKeyID=<access key id>&arg=<token>