Ensemble DICOM Development Guide
Creating DICOM Associations in Ensemble
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter describes how to DICOM associations in Ensemble, which are required before the production can process DICOM input or output. It contains the following sections:

Introduction to DICOM Associations
Before you can develop a production that processes DICOM input or output, you require access to the information contained in the manufacturer’s conformance statement for each DICOM device (modality). You use this information to create DICOM associations that the production uses to facilitate communication between a DICOM modality and Ensemble. A DICOM association is the metadata that describes the characteristics of the conversation of such communication.
The unique and most important aspect of Ensemble productions interfacing with DICOM modalities is creating and testing associations. Before you can create these associations you require the information contained in the Conformance Statement from the manufacturer of the modality. A manufacturer claiming that their equipment or software conforms to the DICOM standard must be able to provide a conformance statement that describes exactly how that device or software conforms to the standard.
An association defines the characteristics of a conversation between modalities. To create an association, use the following information from the Conformance Statement:
During negotiation of the association, Ensemble picks one transfer syntax to use. The order in which they are listed is important. The transfer syntaxes at the front of the list are given preference over the transfer syntaxes at the end of the list. You achieve better performance if you know the exact syntax, which is important for compressed images. Ensemble does not convert from one data to another
The conformance statement describes how an activity handles associations (that is, whether the activity initiates associations and accepts multiple associations) for each activity in the model. Some devices, such as the archives in a picture archiving and communication system (PACS), must support multiple associations for acceptable performance. Otherwise, only a single activity (for example, DICOM storage) could be handled at any given time.
The association information you enter in Ensemble is namespace-specific. You must create and run your production in the same namespace where you define and maintain these associations.
See the EnsLib.DICOM.Util.AssociationContext entry in the Class Reference for more information.
Importing DICOM Associations
You can add associations to your Ensemble namespace by importing acceptable and proposed presentation contexts from a file containing SOP / transfer syntax pairs by executing the ImportAssociation() method of EnsLib.DICOM.Util.AssociationContext.
The ImportAssociation() method has the following signature:
classmethod ImportAssociation(pFileName As %String,
                              pCallingAET As %String,
                              pCalledAET As %String,
                              pOverWriteExisting As %Boolean = 0)
The ImportAssociation() method has the following arguments:
pFileName
The name of a file containing a list of presentation contexts in the form of SOP class UID/transfer syntax UID. The method creates an association between the calling application entity title (AET) and the called AET with a presentation context for each pair in the file.
List the SOP classes (abstract syntaxes) one per line. Specify the transfer syntax by appending it to the line using a \ as the delimiter. If you do not specify any transfer syntaxes, then the import adds the default DICOM transfer syntax (Implicit VR - Little Endian). Use the numeric representation (UID) in the import file.
pCallingAET
Identifies the Application Entity (AE) that contains the requestor of the service; it is based on the source DICOM Application Name. The calling Application Entity Title (AET) is usually the Service Class User (SCU).
pCalledAET
Identifies the Application Entity that contains the intended acceptor of the service. It is based on the destination DICOM Application Name. The called Application Entity Title is usually the Service Class Provider (SCP).
pOverWriteExisting
If an association between the same AET peers exists in the namespace, this argument controls what happens. If True (1), overwrite the association. If False (0), display an error stating the association exists.
See the appendix DICOM Transfer Syntax for detailed information. For DICOM abstract syntax, use the Management Portal. Click Ensemble, click Interoperate, click DICOM, click DICOM Abstract Syntax, and then click Go.
Import Association Example
For example, you can add an association between Ensemble and a work list modality using the information from the following sample Presentation Context Table taken from a conformance statement.
Create a file for the association containing a line for each abstract syntax / transfer syntax combination. Use the UIDs for each item. For example, the contents of text file, MyAssociations.txt:
1.2.840.10008.1.1
1.2.840.10008.5.1.4.31\1.2.840.10008.1.2
1.2.840.10008.5.1.4.31\1.2.840.10008.1.2.1
1.2.840.10008.5.1.4.31\1.2.840.10008.1.2.2
If the only acceptable transfer syntax for a SOP class is the default Implicit VR - Little Endian (UID: 1.2.840.10008.1.2), you do not have to include the transfer syntax for that SOP class, as seen in line 1 of the file.
Once you create a file of abstract / transfer syntax pairs, you invoke the following method in the namespace where you are developing your production. For example:
 Zn "ENSDEMO"

 Do ##class(EnsLib.DICOM.Util.AssociationContext).ImportAssociation
           ("c:\Ensemble\DICOM\MyAssociations.txt",
            "ENS-SCU",
            "MWL-SCP",
             0)
You can view the resulting association information in the Management Portal. Click Ensemble, click Interoperate, click DICOM, and then click DICOM Settings. This displays the [Ensemble] > [DICOM Settings] page:
Click a row in the table and then click Edit to see the Association and Presentation Context tabs.
Creating DICOM Associations
You can also create a superset of associations between the calling and called AET for every known SOP class and a provided list of transfer syntaxes by executing the CreateAssociation() method of EnsLib.DICOM.Util.AssociationContext.
The CreateAssociation() method has the following signature:
classmethod CreateAssociation(pCallingAET As %String,
                              pCalledAET As %String,
                              pTransferSyntaxes As %List)
The CreateAssociation() method has the following arguments:
pCallingAET
Identifies the Application Entity (AE) that contains the requestor of the service; it is based on the source DICOM application name. The calling Application Entity Title (AET) is usually the Service Class User (SCU).
pCalledAET
Identifies the Application Entity that contains the intended acceptor of the service. It is based on the destination DICOM application name. The calling Application Entity Title is usually the Service Class Provider (SCP).
pTransferSyntaxes
A list of transfer syntaxes to pair with every known SOP class to create the presentation context for the association.
(The default list contains the required default Implicit VR Little Endian transfer syntax.)
This method creates an association context instance for the specified calling and called AET that supports all known SOPs.
Note:
This association simply defines all SOP classes that are known in the data dictionary. There is a small performance penalty for this and it may be preferable for you to define just the SOP classes you need either using the Management Portal as described in the next section or by using the ImportAssociation() method described in the previous section. A handshake may take longer between the modality and Ensemble if you include unnecessary classes in the association.
As an example, the ENSDEMO namespace contains sample DICOM productions that generate default associations that include all known SOP classes using the following code.
#; We will be accepting Storage and Query requests from JD-SCU
  Do ##class(EnsLib.DICOM.Util.AssociationContext).CreateAssociation
            ("JD-SCU","ENS-SCP",$ListBuild($$$IMPLICITVRLETRANSFERSYNTAX))

#; We will be sending storage requests to the JD-SCP
  Do ##class(EnsLib.DICOM.Util.AssociationContext).CreateAssociation
            ("ENS-SCU","JD-SCP",$ListBuild($$$IMPLICITVRLETRANSFERSYNTAX))
Transfer Syntax Considerations
Sometimes explicit works better because in many cases, it preserves original type names and provides additional backward compatibility.
Because explicit and implicit value representation (VR) encoding cannot be mixed, the decision regarding which technique to use must be made at the very beginning of any data transfer; DICOM applications negotiate and agree on encoding types before they exchange any data.
Maintaining DICOM Associations
To maintain your associations, use the [Ensemble] > [DICOM Settings] page of the Management Portal. To access this page, click Ensemble, click Interoperate, click DICOM, and then click DICOM Settings.
This page lists any existing associations for the selected namespace and provides the following functions:
Creating and Editing DICOM Associations
The [Ensemble] > [DICOM Settings] page lists all associations defined in the selected namespace. From this list you can Edit or Delete an existing association or you can choose to Create a New Association. To delete an association, click Delete in the appropriate row and click OK to confirm.
This page has two tabs:
Adding Presentation Context
Each network transfer involving DICOM-specific messages begins with establishing an association handshake, when the two connecting applications exchange information about each other. This information is called the presentation context. The presentation context is the set of DICOM network services used over an association, as negotiated between application entities; it includes abstract syntaxes and transfer syntaxes. Ensemble uses the EnsLib.DICOM.Util.PresentationContext class to represent this information. If the two applications can match their contexts, they can connect and start SCU-SCP processing.
To add a presentation context entry:
  1. Click Add on the Presentation Context tab.
  2. Click an abstract syntax supported by the DICOM device. The tab lists the UID and SOP class name for all known abstract syntax in the DICOM standard. You can only select one Abstract Syntax from the list at a time for which to add transfer syntax.
  3. Once you select an abstract syntax, use the > arrow to move the types valid for your device from the Available Transfer Syntax list to the Selected Transfer Syntax list.
  4. When you are finished selecting the appropriate transfer syntax for the abstract syntax, click Save to add the new context to the tree. Click Cancel to ignore your edits and return to the existing presentation context tree.
For example, the common SOP Verification class (1.2.840.10008.1.1) appears as an abstract syntax in many conformance statements. A conformance statement usually lists the acceptable presentation context combinations when the modality acts as a provider (SCP) and the proposed presentation context combinations when it acts as a user (SCU). From the previous example Presentation Context Table this class accepts the Implicit VR Little Endian transfer syntax (1.2.840.10008.1.2).
The appendix DICOM Transfer Syntax lists the information displayed on this page.
Viewing Abstract Syntax
The [Ensemble] > [DICOM AS List] page displays a table of SOP classes and their unique identifiers from the DICOM PS 3.3 Standard. To access this page, click Ensemble, click Interoperate, click DICOM, click DICOM Abstract Syntax, and then click Go. The term abstract syntax is used in part because it is defined in one of the international standards that DICOM references.
To use the Filter feature on the View Abstract Syntax page, enter a partial string and hit the Tab key to reload the table with the filter applied. The search is not case-sensitive and the filter returns results if your entry matches data in any column.
Viewing the DICOM Data Dictionary
The DICOM data dictionary represents the centralized registry which defines the collection of all DICOM data elements available to represent information, along with elements used for media encoding and a list of uniquely identified items that DICOM assigns. The [Ensemble] > [DICOM Dictionary] page displays a table of elements from the DICOM PS 3.3 Standard. To access this page, click Ensemble, click Interoperate, click DICOM, click DICOM Dictionary Syntax, and then click Go.
To use the Filter feature on the View Dictionary page, enter a partial string and hit the Tab key to reload the table with the filter applied. The search is not case-sensitive and the filter returns results if your entry matches data in any column.
The following table describes the page display.
Column name Description
Tag A unique identifier for an element of information composed of an ordered pair of numbers (a group number followed by an element number), which is used to identify attributes and corresponding data elements.
Name Name of the DICOM data dictionary element.
VR Value representation — specifies the data type and format of the value(s) contained in the value field of a data element. (For example, the type of integer or string.)
VM Value multiplicity — specifies the number of values that can be encoded in the value field of that data element.
(Code) Displays a link if the item has code defined. When you click Code, a dialog box displays a list of values valid for this element with the corresponding internal numeric code. You may also filter this table by entering a partial string in the Filter.
The information is intended for reference only. Ensemble does not enforce the use of these enumerated values as variations may appear in the field. You may use these reference tables when trying to decide what value to put in a particular field. The definitive reference is always the official NEMA DICOM PS 3.3 standard.
Testing DICOM Associations
Once you define your associations, you can test them in a production using the following procedure:
  1. Obtain a TCP trace of a working modality before you configure Ensemble.
  2. Start either of the demonstration productions.
  3. Add a business service.
  4. Send an echo message.
  5. Debug the connection.
The following is a sample log from a third-party DICOM testing tool showing the establishment of an association, a request and response of an ECHO message and a release of the association connection.
test: #5:ENS-SCP << A-ASSOCIATE-RQ PDU
test: #5:ENS-SCP >> A-ASSOCIATE-AC PDU
test: #5:ENS-SCP << C-ECHO-RQ Verification SOP Class
test: #5:ENS-SCP >> C-ECHO-RSP Verification SOP Class, status #0000H[Success]
test: #5:ENS-SCP << A-RELEASE-RQ PDU
test: #5:ENS-SCP >> A-RELEASE-RP PDU
test: #5:ENS-SCP closing socket