Categorization

Overview

If a Conformance Suite is composed of more than one test group, then Categorization is required and interaction counts will be aggregated based on the Categorization definition.

We will create a suite with two test groups next:

  1. Click on “New Conformance Suite” on Conformance Suites page.

    ../_images/new_conformance_suite_button_a1.png

  1. Enter the values for the fields as indicated by the blue arrows below:

    ../_images/new_suite_single_group_a2.png

  1. Click the + sign:

    ../_images/new_suite_plus_sign_a1.png

  1. You’ll get a warning indicating that Categorization is required when multiple test groups are selected:

    ../_images/new_suite_categorization_warning_a2.png

    Touchstone uses the Categorization definition to channel the interactions of multiple test groups into one Result Summary chart on the Conformance Current page.


  1. Open the link within the warning on a new browser tab to get to the Categorizations page:

    ../_images/new_suite_categorization_warning_here_a2.png

    You can also get to the Categorizations page from Conformance Suites page via the Categorizations link:

    ../_images/categorizations_link_a1.png

  2. Here is the Categorizations page:

    ../_images/categorizations_page_a1.png

    The page lists all the categorizations that you have view access to.

    You can only use categorizations that your organization owns as part of your suites. This is to minimize the impact on your conformance program if other organizations modify the categorization. You can view other categorizations and copy them (assuming no Copyright infringement) into your own.


  1. Filter for FHIR-Client categorizations (since the suite we’re creating in this section is of FHIR-Client type) and click on FHIR3-0-2-Standard-Client categorization in the list:

    ../_images/categorization_filter_a1.png

  2. Copy and paste the contents into a file in your XML editor:

    ../_images/categorization_copy_paste_a1.png

    We’ve saved the contents into a file called “InitechCert.xml”:


  1. Change the description appropriately:

    ../_images/categorization_contents_a2.png

  1. Upload the Categorization file on the Categorizations page:

../_images/categorizations_upload_link_a1.png

  1. Browse to the InitechCert.xml file on your machine and click on Upload button:

    ../_images/categorization_upload_popup_a1.png

  1. The Categorization will take on the name of the uploaded file. Touchstone will prepend the Specification name/version and will append the type to the name of the file to enforce uniform naming convention across categorizations so they’re easier to identify by end-users:

    ../_images/categorizations_saved_a1.png

  1. Resume where we left off on New Conformance Suite page from step 4.

    Re-enter the field values if you had to refresh the screen and click on the + sign again.

    This time the system will not generate a warning and will allow you to select the Categorization that we just created:

    ../_images/new_suite_categorization_selected_a1.png

  1. Click on Create and then select the suite that got created:

    ../_images/categorization_suite_created_a1.png

  1. Notice that the root node of the Results Summary chart (blue arrows below) matches the name of the Categorization file that we just uploaded.

    ../_images/categorization_current_a2.png

    We have successfully created a conformance suite with two test groups (green arrows above) that uses a Categorization.


When Categorization is used in a suite, the Result Summary chart is entirely driven by the Categorization. The individual nodes/bands within the Result Summary chart (red arrows below) will be identical to the individual categories within the Categorization (blue arrows below):

../_images/categorization_hierarchy_result_summary_a2.png ../_images/categorization_hierarchy_file_a2.png

The terms node and category are hence synonymous when Categorization is used. We will use the terms interchangeably in the remainder of this section.


Definition

We will dive deeper into the Categorization file contents in this section and see how it impacts the Conformance Results.

Root Node

Notice that the root node (blue arrow below) does not have a name:

../_images/categorization_root_node_a3.png

Touchstone will use the Categorization file name (red arrow above) as the name of the root node which in turn gets used as the name of the root node on the Results Summary chart (blue arrows below):

../_images/categorization_current_root_node_a1.png

Leaf Nodes

Leaf categories are those that have no more categories beneath them:

../_images/categorization_leaf_categories_a1.png

They correspond to the outermost nodes in the Result Summary chart when categorization is used:

../_images/categorization_outermost_node_a1.png

Notice that the hierarchy of nodes (red arrows below) in the Results Summary chart matches the hierarchy of categories (blue arrows below) in the file definition:

../_images/categorization_hierarchy_result_summary_a2.png ../_images/categorization_hierarchy_file_a2.png

Side note: When categorization is not used then the outermost node corresponds to individual test scripts within the test group as indicated in this section.


Parent Nodes

The Parent categories are pointed to by the (blue arrows below):

../_images/categorization_non_leaf_nodes_a1.png

You can organize the nodes any way you like.


Node Deletion

  1. Notice the existing interaction counts for the Summary category:

    ../_images/categorization_existing_summary_node_counts_a1.png

  1. Remove the AllergyIntolerance category from the file:

    ../_images/categorization_allergy_removal_a1.png

  2. Re-upload the categorization file. Notice that the version increments:

    ../_images/categorization_uploaded_version_2_a1.png

    Notice also that the Conformance Suite version increments as well:

    ../_images/categorization_suite_version_2_a1.png

    Click on the history icon to see the history of the suite:

    ../_images/categorization_history_click_a1.png

    The cause of the version increments is shown under the Updates column:

    ../_images/categorization_history_increment_cause_a1.png

    Hovering over the text gives more details about the cause:

    ../_images/categorization_suite_increment_cause_hover_a2.png

  3. Go back to the Current page

    Observe the new interaction counts for the Summary category. The AllergyIntolerance node is absent as it was removed from the file:

    ../_images/categorization_new_summary_node_counts_a1.png

Paths

This section explains how the interactions in the test groups (that are part of a suite with categorization) get categorized into different buckets based on the Categorization definition.

The leaf nodes of the Categorization have the categorization paths specified:

../_images/categorization_paths_a1.png

FHIR

FHIR paths are of three types:

  • resource paths: whose values take the form “resource/[Type]” where Type is one of the values listed on FHIR Resource Types.

    ../_images/categorization_resource_paths_a1.png

    For example, all test scripts in the suite that invoke operations involving the Patient resource (blue arrow below) would get aggregated into the Patient category (red arrow below)

    ../_images/categorization_result_summ_patient_a2.png

  • operation paths: whose values take the form “operation/[Type]” where Type is one of the extended operation values listed on FHIR Extended Operations. There are ways to define extended operations not on this list and use them in Categorization. Please contact Touchstone_Support@aegis.net for details.

    ../_images/categorization_operation_paths_a2.png ../_images/categorization_testscript_expand_a1.png

  • whole system paths: whose values take the form “/[Type]” or “interaction/[Type]” where

    • “/[Type]” can be “/capabilities” or “/metadata”, and..

    • “interaction/[Type]” can be “interaction/transaction”, “interaction/batch”, “interaction/search-system”, or “interaction/history-system”.

    See this section on FHIR API page:

    ../_images/categorization_whole_system_a1.png ../_images/categorization_whole_system_categs_a2.png

    The /capabilities and /metadata endpoints are used to retrieve Capabilities Statement from the FHIR system.

    Note

    If the test groups in a suite do not contain the interactions in a categorization path, the Result Summary chart will not display the category/node even if it’s specified in the Categorization. This is true for all types of categorizations.

    For example, notice that even though the Individuals categorization has many sub-categories (green arrows below) besides Patient and RelatedPerson, only the Patient and RelatedPerson nodes display in the Result Summary chart (blue arrows below) because the test groups within the suite only contain operations/interactions for Patient and RelatedPerson:

    ../_images/categorization_missing_resources_a1.png ../_images/categorization_categs_ignored_missing_tsi_a1.png

CDS Hooks

CDS Hooks interactions are not standardized in the specification.

The operation codes in the test script will map directly to the interactions in the Result Summary chart (blue arrows below):

The categories can be arranged in any way. In the example below, the cds-services operation/interaction has been assigned to the CDS-Services node/category (green arrows below):

../_images/categorization_cdsh_file_categ_a1.png