> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-reference/resources/upsert-a-resource-in-the-registry), [Relationship API](/api-reference/relationships/create-a-relationship-between-two-resources-in-the-registry), [Bulk API](/api-reference/bulk/bulk-create-upsert-or-delete-resources) and [Bundle API](/api-reference/bundle/bundle-resource-and-relationship-operations-to-be-processed) allow specifying metadata information in a create or upsert operation (but not update).

System modifiable metadata properties are:

```json theme={null}
{
    "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](/explanation/data-types/clinia-types#identifier) 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

<Accordion title="Set up">
  This setup creates a demo registry source with minimal profiles and a relationship so the examples can run consistently.

  <Steps>
    <Step title="Create a source">
      ```bash {collectForTests="histSource"} theme={null}
      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"
      }'
      ```
    </Step>

    <Step title="Create minimal profiles">
      ```bash {collectForTests="histProfilesPatient"} theme={null}
      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"
            }
          }
        }
      }'
      ```

      ```bash {collectForTests="histProfilesPractitioner"} theme={null}
      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"
              }
            }
          }
        }
      }'
      ```
    </Step>

    <Step title="Create a relationship definition">
      ```bash {collectForTests="histRelDef"} theme={null}
      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": {}
        }
      }'
      ```
    </Step>
  </Steps>
</Accordion>

### Resource Upsert

Specify system-modifiable metadata when creating or replacing a resource. See the [Resource API Reference](/api-reference/resources/upsert-a-resource-in-the-registry).

```bash {collectForTests="histUpsert"} theme={null}
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](/guides/managing-data/tasks#checking-task-status).

```bash {collectForTests="histUpsertGet"} theme={null}
curl -X GET "https://$CLINIA_WORKSPACE/sources/history-demo/v1/resources/patient/patient-001" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"
```

```json {collectForTests="histUpsertObj"} theme={null}
{
  "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](/api-reference/relationships/create-a-relationship-between-two-resources-in-the-registry).

First, ensure the related resources exist (no global seeding required):

```bash {collectForTests="histRelPrePatient"} theme={null}
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"
  }
}'
```

```bash {collectForTests="histRelPrePract"} theme={null}
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"
      }
    ]
  }
}'
```

```bash {collectForTests="histRelCreate"} theme={null}
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](/guides/managing-data/tasks#checking-task-status).

```bash {collectForTests="histRelGet"} theme={null}
curl -X GET "https://$CLINIA_WORKSPACE/sources/history-demo/v1/relationships/treats/pract-001.patient-001" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"
```

```json {collectForTests="histRelObj"} theme={null}
{
  "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](/api-reference/bulk/bulk-create-upsert-or-delete-resources), then poll the task result. Also see the [Task API Reference](/api-reference/task/get-a-task-from-the-registry).

```bash {collectForTests="histBulk"} theme={null}
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](/guides/managing-data/tasks#checking-task-status).

```bash {collectForTests="histBulkGet"} theme={null}
curl -X GET "https://$CLINIA_WORKSPACE/sources/history-demo/v1/resources/patient/patient-002" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"
```

```json {collectForTests="histBulkObj"} theme={null}
{
  "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"
  }
}
```