Historical Import

Each hit returned by Clinia is enriched with metadata information such as createdAt and updatedAt, which are generated automatically by Clinia’s infrastructure. To allow for more flexibility and support a system migration, Clinia’s Resource API, Relationship API, Bulk API and Bundle API allow specifying metadata information in a create or upsert operation (but not update). System modifiable metadata properties are:

{
    "createdAt": "<datetime>",
    "updatedAt": "<datetime>",
    "identifier": [
        {
            // Identifier type
        }
    ]
}

Metadata Rules

Some validation rules are imposed on those metadata to ensure consistency with system-generated values. Those are:

If a value is specified for updatedAt, one must also be provided for createdAt
The datetime value of the updatedAt must be greater or equal to the createdAt
The createdAt and updatedAt datetime values cannot be in the future.
The identifier field must contain Identifier Type with distinct combined values of system, use and value fields.
- Field use can’t take the reserved value "source"
- Field system can’t take the reserved value "mdm"

Examples

Set up

This setup creates a demo registry source with minimal profiles and a relationship so the examples can run consistently.

Create a source

curl -X PUT "https://$CLINIA_WORKSPACE/catalog/v1/sources/history-demo" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "registry"
}'

Create minimal profiles

curl -X PUT "https://$CLINIA_WORKSPACE/sources/history-demo/v1/collections/patient" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "resources",
  "profile": {
    "properties": {
      "name": {
        "type": "array",
        "items": {
          "type": "humanname"
        }
      },
      "birthDate": {
        "type": "date"
      }
    }
  }
}'

curl -X PUT "https://$CLINIA_WORKSPACE/sources/history-demo/v1/collections/practitioner" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "resources",
  "profile": {
    "properties": {
      "name": {
        "type": "array",
        "items": {
          "type": "humanname"
        }
      }
    }
  }
}'

Create a relationship definition

curl -X PUT "https://$CLINIA_WORKSPACE/sources/history-demo/v1/collections/treats" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "relationships",
  "relationshipDefinition": {
    "description": "A relationship indicating that a practitioner treats a patient",
    "from": {
      "profileKey": "practitioner",
      "includeKey": "practitioner",
      "includeCardinality": "0:*"
    },
    "to": {
      "profileKey": "patient",
      "includeKey": "patient",
      "includeCardinality": "0:*"
    },
    "properties": {}
  }
}'

Resource Upsert

Specify system-modifiable metadata when creating or replacing a resource. See the Resource API Reference.

curl -X PUT "https://$CLINIA_WORKSPACE/sources/history-demo/v1/resources/patient/patient-001" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "name": [
      {
        "given": [
          "John"
        ],
        "family": "Doe"
      }
    ],
    "birthDate": "1980-01-01"
  },
  "meta": {
    "createdAt": "2020-05-01T10:00:00Z",
    "updatedAt": "2021-06-15T12:30:00Z",
    "identifier": [
      {
        "system": "https://hospital.example/mrn",
        "value": "12345",
        "use": "external"
      }
    ]
  }
}'

Before fetching the resource, make sure the ingestion task is completed.

curl -X GET "https://$CLINIA_WORKSPACE/sources/history-demo/v1/resources/patient/patient-001" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"

{
  "id": "patient-001",
  "type": "patient",
  "includes": {},
  "meta": {
    "createdAt": "2020-05-01T10:00:00Z",
    "updatedAt": "2021-06-15T12:30:00Z",
    "identifier": [
      {
        "system": "https://hospital.example/mrn",
        "value": "12345",
        "use": "external"
      }
    ],
    "source": "history-demo"
  },
  "data": {
    "name": [{ "given": ["John"], "family": "Doe" }],
    "birthDate": "1980-01-01"
  }
}

Relationship Create

Create a relationship with historical metadata on the link itself. See the Relationship API Reference. First, ensure the related resources exist (no global seeding required):

curl -X PUT "https://$CLINIA_WORKSPACE/sources/history-demo/v1/resources/patient/patient-001" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "name": [
      {
        "given": [
          "John"
        ],
        "family": "Doe"
      }
    ],
    "birthDate": "1980-01-01"
  }
}'

curl -X PUT "https://$CLINIA_WORKSPACE/sources/history-demo/v1/resources/practitioner/pract-001" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "name": [
      {
        "given": [
          "Alice"
        ],
        "family": "Anderson"
      }
    ]
  }
}'

curl -X POST "https://$CLINIA_WORKSPACE/sources/history-demo/v1/relationships/treats" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "from": {
    "type": "practitioner",
    "id": "pract-001"
  },
  "to": {
    "type": "patient",
    "id": "patient-001"
  },
  "meta": {
    "createdAt": "2021-07-01T09:00:00Z",
    "updatedAt": "2021-07-01T09:00:00Z",
    "identifier": [
      {
        "system": "https://ehr.example/relationship-id",
        "value": "rel-7890",
        "use": "external"
      }
    ]
  },
  "data": {}
}'

Before fetching the relationship, make sure the ingestion task is completed.

curl -X GET "https://$CLINIA_WORKSPACE/sources/history-demo/v1/relationships/treats/pract-001.patient-001" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"

{
  "id": "pract-001.patient-001",
  "type": "treats",
  "from": { "type": "practitioner", "id": "pract-001" },
  "to": { "type": "patient", "id": "patient-001" },
  "data": {},
  "meta": {
    "createdAt": "2021-07-01T09:00:00Z",
    "updatedAt": "2021-07-01T09:00:00Z",
    "identifier": [
      {
        "system": "https://ehr.example/relationship-id",
        "value": "rel-7890",
        "use": "external"
      }
    ],
    "source": "history-demo"
  }
}

Bulk Request

Process multiple resource creations with historical metadata using the bulk resources endpoint, then poll the task result. Also see the Task API Reference.

curl -X POST "https://$CLINIA_WORKSPACE/sources/history-demo/v1/resources/bulk" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operations": [
    {
      "action": "CREATE",
      "create": {
        "type": "patient",
        "id": "patient-002",
        "data": {
          "name": [
            {
              "given": [
                "Carla"
              ],
              "family": "Nguyen"
            }
          ],
          "birthDate": "1990-02-02"
        },
        "meta": {
          "createdAt": "2019-03-10T08:00:00Z",
          "updatedAt": "2019-03-10T08:00:00Z",
          "identifier": [
            {
              "system": "https://hospital.example/mrn",
              "value": "67890",
              "use": "external"
            }
          ]
        }
      }
    }
  ]
}'

Before fetching the resource, make sure the ingestion task is completed.

curl -X GET "https://$CLINIA_WORKSPACE/sources/history-demo/v1/resources/patient/patient-002" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"

{
  "id": "patient-002",
  "type": "patient",
  "includes": {},
  "meta": {
    "createdAt": "2019-03-10T08:00:00Z",
    "updatedAt": "2019-03-10T08:00:00Z",
    "identifier": [
      {
        "system": "https://hospital.example/mrn",
        "value": "67890",
        "use": "external"
      }
    ],
    "source": "history-demo"
  },
  "data": {
    "name": [{ "given": ["Carla"], "family": "Nguyen" }],
    "birthDate": "1990-02-02"
  }
}

About Clinia

Core Concepts

Search

Configuring Data Sources

Configuring Partitions

Managing Data

Master Data Management

Terminology

Identity and Access Management

AI Engine

Historical Import

Metadata Rules

Examples

Resource Upsert

Relationship Create

Bulk Request

​Metadata Rules

​Examples

​Resource Upsert

​Relationship Create

​Bulk Request

Metadata Rules

Examples

Resource Upsert

Relationship Create

Bulk Request