IHE XDS-I.b Imaging Document Source Actor. More...

#include <imaging_document_source.h>

Collaboration diagram for kcenon::pacs::services::xds::imaging_document_source:

Public Member Functions
	imaging_document_source ()=default

	imaging_document_source (const imaging_document_source_config &config)

kos_creation_result	create_kos_document (const std::string &study_instance_uid, const std::vector< kos_instance_reference > &references, const std::optional< core::dicom_dataset > &patient_demographics=std::nullopt) const
	Create a KOS document from a set of DICOM instance references.

xds_document_entry	build_document_entry (const core::dicom_dataset &kos_dataset) const
	Build XDS document entry metadata from a KOS dataset.

xds_submission_set	build_submission_set (const std::string &patient_id) const
	Build XDS submission set metadata.

publication_result	publish_document (const core::dicom_dataset &kos_dataset, const xds_document_entry &entry, bool is_imaging=true) const
	Publish a KOS document to the XDS registry/repository.

void	set_audit_handler (std::shared_ptr< kcenon::pacs::security::atna_service_auditor > auditor)
	Install an ATNA audit handler for XDS-I.b transactions.

const imaging_document_source_config &	config () const noexcept
	Get current configuration.

void	set_config (const imaging_document_source_config &config)
	Set configuration.

Private Member Functions
std::string	generate_uid () const
	Generate a new UID for KOS instances.

void	build_evidence_sequence (core::dicom_dataset &kos_dataset, const std::vector< kos_instance_reference > &references) const
	Build the Current Requested Procedure Evidence Sequence.

Private Attributes
imaging_document_source_config	config_

std::shared_ptr< kcenon::pacs::security::atna_service_auditor >	auditor_

Detailed Description

IHE XDS-I.b Imaging Document Source Actor.

Creates KOS (Key Object Selection) documents from DICOM studies and provides the interface for publishing them to an XDS Document Registry/Repository via the ITI-41 transaction.

Workflow

When a study is received/completed, call create_kos_document()
Optionally customize the document metadata
Call publish_document() to submit to the XDS registry

Example:: imaging_document_source_config config;

config.registry_url = "https://xds-registry.example.com/services/iti41";

config.source_oid = "1.2.3.4.5.6.7.8.9";

imaging_document_source source{config};

// Create KOS from study instances

auto kos_result = source.create_kos_document(

"1.2.840.10008.1.2.3.4", // Study Instance UID

instances, // Instance references

patient_dataset // Patient demographics

);

// Build submission and publish

auto pub_result = source.publish_document(

kos_result.kos_dataset.value(),

document_entry

);

kcenon::pacs::services::xds::imaging_document_source
IHE XDS-I.b Imaging Document Source Actor.
Definition imaging_document_source.h:264

kcenon::pacs::services::xds::imaging_document_source::config
const imaging_document_source_config & config() const noexcept
Get current configuration.
Definition imaging_document_source.cpp:331

kcenon::pacs::services::xds::imaging_document_source_config
Configuration for the Imaging Document Source actor.
Definition imaging_document_source.h:200

kcenon::pacs::services::xds::imaging_document_source_config::source_oid
std::string source_oid
Source system OID (used as sourceId in submissions)
Definition imaging_document_source.h:205

kcenon::pacs::services::xds::imaging_document_source_config::registry_url
std::string registry_url
XDS Registry/Repository endpoint URL.
Definition imaging_document_source.h:202

Definition at line 264 of file imaging_document_source.h.

Constructor & Destructor Documentation

◆ imaging_document_source() [1/2]

kcenon::pacs::services::xds::imaging_document_source::imaging_document_source ( )

default

◆ imaging_document_source() [2/2]

kcenon::pacs::services::xds::imaging_document_source::imaging_document_source ( const imaging_document_source_config & config )

explicit

Definition at line 92 of file imaging_document_source.cpp.

94 : config_(config) {}

kcenon::pacs::services::xds::imaging_document_source::config_

imaging_document_source_config config_

Definition imaging_document_source.h:355

Member Function Documentation

◆ build_document_entry()

xds_document_entry kcenon::pacs::services::xds::imaging_document_source::build_document_entry ( const core::dicom_dataset & kos_dataset ) const

nodiscard

Build XDS document entry metadata from a KOS dataset.

Extracts patient and study metadata from the KOS dataset and populates an xds_document_entry structure suitable for registry submission.

Parameters

kos_dataset The KOS dataset to extract metadata from

Returns: Populated document entry metadata

Definition at line 186 of file imaging_document_source.cpp.

                                                {
 
    xds_document_entry entry;
 
    entry.entry_uuid = "urn:uuid:" + generate_uid();
    entry.unique_id = kos_dataset.get_string(tags::sop_instance_uid);
    entry.patient_id = kos_dataset.get_string(tags::patient_id);
    entry.source_patient_id = entry.patient_id;
 
    entry.class_code = "IMG";
    entry.class_code_scheme = "1.3.6.1.4.1.19376.3.840.1.1.4";
    entry.class_code_display = "Imaging Procedure";
 
    entry.type_code = "KOS";
    entry.type_code_scheme = "1.2.840.10008.2.16.4";
    entry.type_code_display = "Key Object Selection";
 
    entry.format_code = std::string(sop_classes::key_object_selection_document_storage_uid);
    entry.format_code_scheme = "1.2.840.10008.2.6.1";
 
    entry.creation_time = current_datetime();
    entry.service_start_time = entry.creation_time;
    entry.service_stop_time = entry.creation_time;
 
    entry.facility_type_code = config_.facility_type_code;
    entry.facility_type_code_scheme = config_.facility_type_code_scheme;
    entry.practice_setting_code = config_.practice_setting_code;
    entry.practice_setting_code_scheme = config_.practice_setting_code_scheme;
 
    // Extract author from patient demographics if available
    auto ref_physician = kos_dataset.get_string(tags::referring_physician_name);
    if (!ref_physician.empty()) {
        entry.author_person = ref_physician;
    }
 
    entry.title = "Key Object Selection Document";
 
    return entry;
}

Here is the call graph for this function:

◆ build_evidence_sequence()

void kcenon::pacs::services::xds::imaging_document_source::build_evidence_sequence	(	core::dicom_dataset &	kos_dataset,
		const std::vector< kos_instance_reference > &	references ) const

private

Build the Current Requested Procedure Evidence Sequence.

Definition at line 353 of file imaging_document_source.cpp.

                                                               {
 
    // Group references by study -> series -> instances
    struct series_group {
        std::string series_uid;
        std::vector<std::pair<std::string, std::string>> instances;  // sop_class, sop_instance
    };
 
    std::unordered_map<std::string, std::vector<series_group>> study_map;
 
    for (const auto& ref : references) {
        auto& series_list = study_map[ref.study_instance_uid];
 
        auto it = std::find_if(series_list.begin(), series_list.end(),
                               [&](const series_group& sg) {
                                   return sg.series_uid == ref.series_instance_uid;
                               });
 
        if (it != series_list.end()) {
            it->instances.emplace_back(ref.sop_class_uid, ref.sop_instance_uid);
        } else {
            series_group sg;
            sg.series_uid = ref.series_instance_uid;
            sg.instances.emplace_back(ref.sop_class_uid, ref.sop_instance_uid);
            series_list.push_back(std::move(sg));
        }
    }
 
    // Build the sequence structure
    std::vector<dicom_dataset> study_items;
    for (const auto& [study_uid, series_list] : study_map) {
        dicom_dataset study_item;
        study_item.set_string(tags::study_instance_uid, vr_type::UI, study_uid);
 
        std::vector<dicom_dataset> series_items;
        for (const auto& sg : series_list) {
            dicom_dataset series_item;
            series_item.set_string(tags::series_instance_uid, vr_type::UI, sg.series_uid);
 
            std::vector<dicom_dataset> sop_items;
            for (const auto& [sop_class, sop_instance] : sg.instances) {
                dicom_dataset sop_item;
                sop_item.set_string(kos_tags::referenced_sop_class_uid, vr_type::UI, sop_class);
                sop_item.set_string(kos_tags::referenced_sop_instance_uid, vr_type::UI, sop_instance);
                sop_items.push_back(std::move(sop_item));
            }
            insert_sequence(series_item, kos_tags::referenced_sop_sequence, std::move(sop_items));
            series_items.push_back(std::move(series_item));
        }
        insert_sequence(study_item, kos_tags::referenced_series_sequence, std::move(series_items));
        study_items.push_back(std::move(study_item));
    }
 
    insert_sequence(kos_dataset,
                    kos_tags::current_requested_procedure_evidence_sequence,
                    std::move(study_items));
}

References kcenon::pacs::services::xds::kos_tags::current_requested_procedure_evidence_sequence, kcenon::pacs::services::xds::kos_tags::referenced_series_sequence, kcenon::pacs::services::xds::kos_tags::referenced_sop_class_uid, kcenon::pacs::services::xds::kos_tags::referenced_sop_instance_uid, kcenon::pacs::services::xds::kos_tags::referenced_sop_sequence, kcenon::pacs::core::tags::series_instance_uid, kcenon::pacs::core::dicom_dataset::set_string(), and kcenon::pacs::core::tags::study_instance_uid.

Referenced by create_kos_document().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ build_submission_set()

xds_submission_set kcenon::pacs::services::xds::imaging_document_source::build_submission_set ( const std::string & patient_id ) const

nodiscard

Build XDS submission set metadata.

Creates a submission set entry for ITI-41 Provide and Register Document Set-b transaction.

Parameters

patient_id Patient ID for the submission

Returns: Populated submission set metadata

Definition at line 227 of file imaging_document_source.cpp.

                                       {
 
    xds_submission_set set;
 
    set.unique_id = generate_uid();
    set.source_id = config_.source_oid;
    set.patient_id = patient_id;
    set.content_type_code = "IMG";
    set.content_type_code_scheme = "1.3.6.1.4.1.19376.3.840.1.1.4";
    set.content_type_code_display = "Imaging Procedure";
    set.submission_time = current_datetime();
 
    return set;
}

Here is the call graph for this function:

◆ config()

const imaging_document_source_config & kcenon::pacs::services::xds::imaging_document_source::config ( ) const

nodiscardnoexcept

Get current configuration.

Returns: Reference to configuration

Definition at line 331 of file imaging_document_source.cpp.

                                               {
    return config_;
}

References config_.

Referenced by set_config().

Here is the caller graph for this function:

◆ create_kos_document()

kos_creation_result kcenon::pacs::services::xds::imaging_document_source::create_kos_document	(	const std::string &	study_instance_uid,
		const std::vector< kos_instance_reference > &	references,
		const std::optional< core::dicom_dataset > &	patient_demographics = std::nullopt ) const

nodiscard

Create a KOS document from a set of DICOM instance references.

Generates a Key Object Selection Document (SOP Class 1.2.840.10008.5.1.4.1.1.88.59) containing references to the specified instances, following TID 2010.

Parameters

study_instance_uid	The Study Instance UID
references	Vector of instance references to include
patient_demographics	Optional patient demographics dataset

Returns: KOS creation result with the generated dataset

Definition at line 96 of file imaging_document_source.cpp.

                                                                      {
 
    kos_creation_result result;
 
    if (references.empty()) {
        result.error_message = "No instance references provided";
        return result;
    }
 
    core::dicom_dataset kos;
 
    // --- SOP Common Module ---
    kos.set_string(tags::sop_class_uid, vr_type::UI,
                   std::string(sop_classes::key_object_selection_document_storage_uid));
    result.kos_instance_uid = generate_uid();
    kos.set_string(tags::sop_instance_uid, vr_type::UI, result.kos_instance_uid);
 
    // --- Patient Module (Type 2) ---
    if (patient_demographics) {
        auto copy_if_present = [&](dicom_tag tag, vr_type vr) {
            if (patient_demographics->contains(tag)) {
                kos.set_string(tag, vr, patient_demographics->get_string(tag));
            } else {
                kos.set_string(tag, vr, "");
            }
        };
        copy_if_present(tags::patient_name, vr_type::PN);
        copy_if_present(tags::patient_id, vr_type::LO);
        copy_if_present(tags::patient_birth_date, vr_type::DA);
        copy_if_present(tags::patient_sex, vr_type::CS);
    } else {
        kos.set_string(tags::patient_name, vr_type::PN, "");
        kos.set_string(tags::patient_id, vr_type::LO, "");
        kos.set_string(tags::patient_birth_date, vr_type::DA, "");
        kos.set_string(tags::patient_sex, vr_type::CS, "");
    }
 
    // --- General Study Module ---
    kos.set_string(tags::study_instance_uid, vr_type::UI, study_instance_uid);
    kos.set_string(tags::study_date, vr_type::DA, current_date());
    kos.set_string(tags::study_time, vr_type::TM, current_time());
    kos.set_string(tags::referring_physician_name, vr_type::PN, "");
    kos.set_string(tags::study_id, vr_type::SH, "");
    kos.set_string(tags::accession_number, vr_type::SH, "");
 
    // --- General Series Module ---
    kos.set_string(tags::modality, vr_type::CS, "KO");
    kos.set_string(tags::series_instance_uid, vr_type::UI, generate_uid());
    kos.set_string(tags::series_number, vr_type::IS, "1");
 
    // --- General Equipment Module ---
    kos.set_string(dicom_tag{0x0008, 0x0070}, vr_type::LO, "");  // Manufacturer
 
    // --- SR Document General Module ---
    kos.set_string(tags::instance_number, vr_type::IS, "1");
    kos.set_string(tags::content_date, vr_type::DA, current_date());
    kos.set_string(tags::content_time, vr_type::TM, current_time());
    kos.set_string(kos_tags::completion_flag, vr_type::CS, "COMPLETE");
    kos.set_string(kos_tags::verification_flag, vr_type::CS, "UNVERIFIED");
 
    // --- SR Document Content Module ---
    // Value type: CONTAINER (root)
    kos.set_string(kos_tags::value_type, vr_type::CS, "CONTAINER");
 
    // Concept Name Code Sequence: Key Object Selection (113000, DCM)
    dicom_dataset concept_name;
    concept_name.set_string(kos_tags::code_value, vr_type::SH, "113000");
    concept_name.set_string(kos_tags::coding_scheme_designator, vr_type::SH, "DCM");
    concept_name.set_string(kos_tags::code_meaning, vr_type::LO, "Of Interest");
    insert_sequence(kos, kos_tags::concept_name_code_sequence, {concept_name});
 
    // Content Template Sequence: TID 2010
    dicom_dataset template_item;
    template_item.set_string(kos_tags::template_identifier, vr_type::CS, "2010");
    template_item.set_string(kos_tags::mapping_resource, vr_type::CS, "DCMR");
    insert_sequence(kos, kos_tags::content_template_sequence, {template_item});
 
    // --- Current Requested Procedure Evidence Sequence ---
    build_evidence_sequence(kos, references);
 
    result.success = true;
    result.reference_count = references.size();
    result.kos_dataset = std::move(kos);
 
    return result;
}

Here is the call graph for this function:

◆ generate_uid()

std::string kcenon::pacs::services::xds::imaging_document_source::generate_uid ( ) const

nodiscardprivate

Generate a new UID for KOS instances.

Definition at line 340 of file imaging_document_source.cpp.

                                                      {
    static constexpr const char* uid_root = "1.2.826.0.1.3680043.2.1545.1";
    static std::mt19937_64 gen{std::random_device{}()};
    static std::uniform_int_distribution<uint64_t> dist;
 
    auto now = std::chrono::system_clock::now();
    auto timestamp = std::chrono::duration_cast<std::chrono::milliseconds>(
        now.time_since_epoch()).count();
 
    return std::string(uid_root) + "." + std::to_string(timestamp) +
           "." + std::to_string(dist(gen) % 100000);
}

Referenced by build_document_entry(), build_submission_set(), and create_kos_document().

Here is the caller graph for this function:

◆ publish_document()

publication_result kcenon::pacs::services::xds::imaging_document_source::publish_document	(	const core::dicom_dataset &	kos_dataset,
		const xds_document_entry &	entry,
		bool	is_imaging = true ) const

nodiscard

Publish a KOS document to the XDS registry/repository.

Performs the ITI-41 (Provide and Register Document Set-b) transaction to publish the KOS document and its metadata to the configured XDS registry/repository. When an ATNA audit handler is installed, an Export audit event is emitted for both success and failure paths.

Parameters

kos_dataset	The KOS dataset to publish
entry	The document entry metadata
is_imaging	true for RAD-68 (Provide and Register Imaging Document Set), false for ITI-41 (Provide and Register Document Set-b). Controls the transaction code recorded in the ATNA audit.

Returns: Publication result

Definition at line 273 of file imaging_document_source.cpp.

                           {
 
    publication_result result;
 
    // Build audit fields once; used for both success and failure paths.
    auto study_uid = kos_dataset.get_string(core::tags::study_instance_uid);
    auto patient_id = kos_dataset.get_string(core::tags::patient_id);
    auto sop_instance_uids = collect_sop_instance_uids(kos_dataset);
    const auto transaction =
        is_imaging
            ? security::atna_service_auditor::xds_source_transaction::rad_68
            : security::atna_service_auditor::xds_source_transaction::iti_41;
 
    if (config_.registry_url.empty()) {
        result.error_message = "XDS registry URL not configured";
        if (auditor_) {
            auditor_->audit_xds_provide_and_register(
                transaction,
                config_.source_oid,
                config_.registry_url,   // empty when unconfigured
                study_uid,
                patient_id,
                sop_instance_uids,
                false);
        }
        return result;
    }
 
    // NOTE: Actual HTTP POST to the XDS registry/repository (ITI-41 / RAD-68)
    // would be implemented here using the network layer.
    // The ITI-41 / RAD-68 transactions use SOAP/MTOM encoding.
    // For now, return success to indicate the interface is operational.
    result.success = true;
    result.document_entry_uuid = entry.entry_uuid;
 
    if (auditor_) {
        auditor_->audit_xds_provide_and_register(
            transaction,
            config_.source_oid,
            config_.registry_url,
            study_uid,
            patient_id,
            sop_instance_uids,
            true);
    }
 
    return result;
}

References kcenon::pacs::security::atna_service_auditor::audit_xds_provide_and_register(), auditor_, config_, kcenon::pacs::services::xds::publication_result::document_entry_uuid, kcenon::pacs::services::xds::xds_document_entry::entry_uuid, kcenon::pacs::services::xds::publication_result::error_message, kcenon::pacs::core::dicom_dataset::get_string(), kcenon::pacs::security::atna_service_auditor::iti_41, kcenon::pacs::core::tags::patient_id, kcenon::pacs::security::atna_service_auditor::rad_68, kcenon::pacs::services::xds::imaging_document_source_config::registry_url, kcenon::pacs::services::xds::imaging_document_source_config::source_oid, kcenon::pacs::core::tags::study_instance_uid, and kcenon::pacs::services::xds::publication_result::success.

Here is the call graph for this function:

◆ set_audit_handler()

void kcenon::pacs::services::xds::imaging_document_source::set_audit_handler ( std::shared_ptr< kcenon::pacs::security::atna_service_auditor > auditor )

Install an ATNA audit handler for XDS-I.b transactions.

When set, an audit event is emitted for each publish_document() call (ITI-41 or RAD-68) on both success and failure paths. Passing nullptr disables auditing for this source.

Parameters

auditor Shared pointer to an ATNA service auditor

Definition at line 325 of file imaging_document_source.cpp.

                                                                   {
    auditor_ = std::move(auditor);
}

References auditor_.

◆ set_config()

void kcenon::pacs::services::xds::imaging_document_source::set_config ( const imaging_document_source_config & config )

Set configuration.

Parameters

config New configuration

Definition at line 335 of file imaging_document_source.cpp.

                                                  {
    config_ = config;
}

References config(), and config_.

Here is the call graph for this function:

Member Data Documentation

◆ auditor_

std::shared_ptr<kcenon::pacs::security::atna_service_auditor> kcenon::pacs::services::xds::imaging_document_source::auditor_

private

Definition at line 356 of file imaging_document_source.h.

Referenced by publish_document(), and set_audit_handler().

◆ config_

imaging_document_source_config kcenon::pacs::services::xds::imaging_document_source::config_

private

Definition at line 355 of file imaging_document_source.h.

Referenced by build_document_entry(), build_submission_set(), config(), publish_document(), and set_config().

The documentation for this class was generated from the following files:

include/kcenon/pacs/services/xds/imaging_document_source.h
src/services/xds/imaging_document_source.cpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Workflow

Constructor & Destructor Documentation

◆ imaging_document_source() [1/2]

◆ imaging_document_source() [2/2]

Member Function Documentation

◆ build_document_entry()

◆ build_evidence_sequence()

◆ build_submission_set()

◆ config()

◆ create_kos_document()

◆ generate_uid()

◆ publish_document()

◆ set_audit_handler()

◆ set_config()

Member Data Documentation

◆ auditor_

◆ config_