Historical Import

Preserve original timestamps and identifiers when migrating historical data into Clinia.

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

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"
            }
          ]
        }
      }
    }
  ]
}'