Medical imaging platforms must move large volumes of DICOM data without losing track of image identity, metadata, or import errors. AWS HealthImaging Solutions provide a managed foundation for storing and retrieving medical imaging data, but the ingestion workflow still needs careful engineering.
A production-ready pipeline involves more than uploading .dcm files and starting an import job. It needs source validation, secure S3 staging, a scoped IAM role, job orchestration, manifest processing, and post-import verification.
This guide explains how to build a DICOM import pipeline using AWS HealthImaging, from preparing source files to making imported image sets available to downstream applications.
Understand the DICOM Import Architecture
AWS HealthImaging imports DICOM P10 files from an Amazon S3 input location into a data store. During import, it performs pixel-data verification and transforms source files into image sets containing metadata and image frames.
A typical workflow looks like this:
PACS / VNA / Scanner Export
|
v
Source Validation
|
v
Amazon S3 Input
|
v
StartDICOMImportJob
|
v
AWS HealthImaging
|
+-------------------+
| |
v v
Image Sets S3 Job Results
|
+----------+----------+
| | |
v v v
Success Warning Failure
Manifest Manifest Manifest
|
v
Reconciliation and QA
|
v
Imaging Viewer
In this architecture, S3 holds incoming files and import results, while HealthImaging manages the resulting image sets. Your application handles workflow state, reconciliation, access policies, and readiness checks.
For teams implementing AWS HealthImaging Solutions, this separation helps keep ingestion logic independent from the applications that consume the data.
Start with the official AWS HealthImaging import guide.
1. Define the Source Data Contract
Before moving files, establish exactly what the source system will deliver. DICOM environments vary in export conventions, metadata quality, transfer syntaxes, and directory structures.
Document these details:
Source system and export method
Expected DICOM SOP classes
Supported transfer syntaxes
Study, Series, and Instance identifiers
Approximate file count and total data volume
Whether metadata overrides are required
How duplicate or corrected studies should be handled
Which system owns the authoritative identifiers
HealthImaging supports specific DICOM elements, SOP classes, and transfer syntaxes. Check the dataset against the current DICOM support documentation before starting a large migration.
An uploaded file is not necessarily a valid import candidate. It may reach S3 but fail validation or produce warnings during processing.
A reliable AWS HealthImaging Solutions implementation should validate representative files early, including data from different modalities and source systems.
2. Stage DICOM Files in Amazon S3
Use a dedicated S3 bucket or prefix for each ingestion environment. Keep source files separate from job outputs so that the pipeline can identify exactly which data belongs to each batch.
For example:
s3://imaging-ingestion-prod/
incoming/
batch-2026-10-15/
study-a/
instance-001.dcm
instance-002.dcm
study-b/
instance-001.dcm
s3://imaging-import-results/
jobs/
batch-2026-10-15/
The folder structure helps with operational organization. HealthImaging uses DICOM metadata, including Study, Series, and Instance UIDs, when organizing imported data.
Consider these controls:
Assign a unique batch identifier to each import.
Maintain a manifest of source object keys and checksums.
Prevent files from changing after a batch is approved.
Restrict bucket access to the required roles and services.
Enable encryption and appropriate access logging.
Define retention rules for source data and import results.
Avoid patient names or other sensitive information in resource names and job labels.
These controls make retries, troubleshooting, and audits easier. They also prevent an upload from silently changing the input associated with a previously submitted job.
For AWS HealthImaging Solutions that handle clinical data, treat source files and processing manifests as sensitive assets throughout the pipeline.
3. Configure the Data Store and IAM Role
Create a HealthImaging data store before starting the import. Decide on the storage format at creation time because it affects how lossless image frames are stored. HTJ2K is the default, and JPEG 2000 Lossless is also available as a configuration option.
Confirm that the selected format works with the applications that will retrieve and decode the images. See the data store creation guide for the available configuration options.
Next, configure the IAM role used by the import job. It needs permission to read the input files and write processing results to the designated output location. Its trust policy must allow HealthImaging to assume the role.
Follow least-privilege principles:
Grant read access only to the approved input location.
Grant write access only to the job-results location.
Avoid broad wildcard permissions where narrower resource permissions are possible.
Separate deployment permissions from runtime import permissions.
Review role trust policies and bucket permissions during testing.
The import role is a key part of the security boundary. A production pipeline should not rely on a developer's personal credentials or broad administrative access.
Refer to the AWS HealthImaging setup guide for the required S3 buckets, permissions, and role configuration.
4. Start an Import Job
The StartDICOMImportJob action starts the bulk import. Its request identifies the target data store, S3 input and output locations, and the data-access role.
The following AWS CLI example illustrates the command structure. Replace the sample values with the identifiers and locations from your environment.
aws medical-imaging start-dicom-import-job \
--datastore-id "$DATASTORE_ID" \
--input-s3-uri "s3://imaging-ingestion-prod/incoming/batch-2026-10-15/" \
--output-s3-uri "s3://imaging-import-results/jobs/batch-2026-10-15/" \
--data-access-role-arn "$IMPORT_ROLE_ARN" \
--job-name "batch-2026-10-15"
Check the current AWS CLI reference for the exact options supported by your installed version. In application code, use an AWS SDK and store the returned job identifier with your internal batch ID.
For example, an application-level batch record might look like this:
{
"batchId": "batch-2026-10-15",
"dataStoreId": "replace-with-datastore-id",
"jobId": "returned-job-id",
"inputPrefix": "incoming/batch-2026-10-15/",
"status": "SUBMITTED"
}
This is an illustrative internal record, not the exact AWS API response. Store only the operational information needed to manage the import.
If a worker times out after submitting a job, the orchestration layer should check the stored job state before attempting another submission. This reduces accidental duplicate processing and makes recovery more predictable.
5. Track Job Status and Parse the Manifests
An import job's status describes job execution. It does not guarantee that every file imported successfully. AWS documents that a job can reach COMPLETED even when file-level validation issues occurred.
Use GetDICOMImportJob to check job status. Once the job reaches a terminal state, inspect the output location and reconcile individual file results.
The output can include:
success.ndjson for successfully imported instances
failure.ndjson for instances that could not be imported
warning.ndjson for instances imported with warnings
The results are stored in an output structure that also includes a job manifest. Each NDJSON line is a separate JSON record, so process the file line by line instead of parsing the entire file as one JSON document.
For every input file, record its outcome, image-set identifier when available, warning details, and any follow-up action. Make reconciliation idempotent so that processing the same manifest twice does not create duplicate application records or trigger downstream actions repeatedly.
The official import-job documentation explains the result structure and how HealthImaging organizes imported instances.
6. Handle Warnings, Failures, and Conflicting Data
Import results should not be reduced to a simple success-or-failure flag. A warning may indicate that an instance was imported but has a data-conformance issue or a limitation affecting later retrieval.
A practical handling policy is:
Outcome
Recommended action
Success without warnings
Record the image-set ID and continue verification
Success with warnings
Store warning codes and route for review based on impact
Failure
Capture the error, correct the source if possible, and retry under controlled conditions
Conflicting metadata
Review primary and non-primary image-set behavior before releasing data
HealthImaging organizes instances using DICOM Study, Series, and Instance UIDs. If newly imported data conflicts with existing primary image sets, HealthImaging may place the new data in non-primary image sets.
Therefore, do not assume that every imported file automatically becomes part of the expected primary image set. Build explicit rules for repeat imports, corrected studies, and data arriving from multiple source systems.
Maintain a source-to-target mapping and avoid treating filenames as unique clinical identifiers. Familiar filenames do not prove that two files represent the same image instance.
Consult the HealthImaging warning codes reference when defining warning categories and remediation procedures.
7. Verify Image Sets Before Releasing Data
A completed import job does not mean the data is ready for an application. Add a verification stage before marking a batch as available to downstream users.
Depending on the use case, checks can include:
Confirm that every expected source file has a recorded outcome.
Compare success, warning, and failure counts with the source manifest.
Confirm image-set identifiers exist for successful imports.
Retrieve metadata for representative image sets.
Retrieve selected image frames and verify that the consuming application can decode them.
Check expected Study and Series relationships.
Test permissions for authorized and unauthorized users.
Record unresolved warnings and failures for follow-up.
Choose representative studies across relevant modalities, file sizes, and transfer syntaxes. A small test import is useful, but it should not replace validation against the actual production dataset.
Pay particular attention to image decoding. HealthImaging may store lossless frames in HTJ2K or another configured format, so the viewer or downstream service must support the transfer syntaxes it receives.
For AWS HealthImaging Solutions connected to a viewer, test the complete retrieval path—not just whether the metadata API returns a response.
8. Orchestrate Large Imports for Recovery
For large archives, avoid relying on a single long-running script to upload files and wait for every job to finish. Separate the workflow into stages so failures can be diagnosed and retried independently.
A pipeline may coordinate:
Batch registration
Source-file validation
S3 upload completion
Import-job submission
Job-status tracking
Manifest parsing
Post-import verification
Exception review
Completion notifications
Persist each stage's state. If a worker stops after an import job starts, another worker should recover the job using the stored identifier. If manifest processing fails, rerun that stage without resubmitting the import.
Use bounded retries with backoff for transient errors. Do not repeatedly retry permanent validation failures without correcting the source or configuration. Account for service quotas, API throttling, and the time required to process large batches.
This staged approach makes AWS HealthImaging Solutions easier to operate because each step has a clear input, output, and recovery procedure.
9. Monitor the Pipeline and Protect Clinical Data
Monitor infrastructure metrics alongside file-level outcomes. Useful operational measurements include:
Files discovered and uploaded
Import jobs submitted and completed
Successful imports
Imports completed with warnings
Failed-file counts and error categories
Time from upload to job completion
Time spent reconciling manifests
Batches awaiting manual review
Retry counts and age of pending batches
Alert on unexpected failure rates, jobs that remain pending too long, missing output manifests, and growth in the manual-review queue.
Keep logs useful for troubleshooting without copying DICOM payloads or unnecessary patient information into general application logs. Define who can access source files, image sets, manifests, and operational dashboards.
Apply least-privilege permissions and follow your organization's retention, audit, and incident-response requirements. The exact controls depend on the deployment and applicable healthcare obligations.
Common Mistakes to Avoid
Assuming COMPLETED means every file succeeded. Reconcile the output manifests and investigate failures and warnings.
Skipping DICOM compatibility checks. Verify supported SOP classes, elements, and transfer syntaxes before importing a large dataset.
Using broad IAM permissions. Scope access to the required input and output resources.
Ignoring warnings. Some warnings can affect downstream retrieval and require a documented review process.
Treating filenames as unique identifiers. Use DICOM identifiers and maintain a source-to-target mapping.
Retrying an entire batch without checking its state. Persist job identifiers and make processing stages idempotent.
Releasing data before verification. Confirm metadata, representative image frames, and application access before declaring a batch ready.
Production Readiness Checklist
Before deploying the pipeline, confirm that:
The dataset has been checked against current HealthImaging DICOM support.
S3 input and output locations are separated and access-controlled.
The import role follows least-privilege principles.
The data store's storage-format choice matches downstream requirements.
Each batch has a stable identifier and source manifest.
Import job IDs and terminal states are persisted.
Success, warning, and failure manifests are reconciled.
Duplicate and conflicting image-set behavior is understood.
Representative metadata and image-frame retrieval tests pass.
Alerts, retries, audit logs, and manual-review procedures are defined.
These controls turn a basic import script into a pipeline that can be operated, monitored, and audited over time.
How Oodles Approaches AWS HealthImaging Integration
At Oodles, we approach AWS HealthImaging Solutions as part of a complete medical imaging workflow rather than an isolated storage task. The implementation can include DICOM ingestion, S3 staging, import-job orchestration, manifest processing, secure APIs, viewer integration, monitoring, and operational tooling.
The architecture depends on the source environment, data volume, supported DICOM formats, identity model, and applications that consume the imported studies. We begin by mapping these dependencies, then define a staged workflow with clear recovery paths and verification checks.
If your team is planning a DICOM migration or building a medical imaging platform, let's connect to discuss the import workflow, integration points, and technical requirements.
Top comments (0)