Skip to main content
Version: v5.3

Importing individuals

Importing individuals​

This page shows how to load individuals of several classes in one request: check the data with a dry run, queue the import, follow it to the end, and undo it if you need to. For background, see Importing individuals.

Before you start, make sure you have the following:

  • A live ontology. Each class you import into needs a live collection mapping with a collection. For more information, see Mapping a class to a collection.
  • INDIVIDUALS_CREATE on every class you import into, and INDIVIDUALS_EDIT on every class whose elements carry import-form relationships. For more information, see Granting permissions.
  • For the default UPSERT mode, external key fields for each class, declared on the class or sent on the elements. For more information, see External keys.
  • An import body of 10 MB or less. Split larger data into several imports.

Every request needs an Authorization: Bearer <token> header. The examples use the namespace myapp.

To import individuals, complete the following steps:

  1. Send the data as a dry run.

    POST /aosvc/api/v1/ontologies/{ontologyId}/import?nsfilter=myapp&dryRun=true

    [
    {
    "_classId": "<Room class ID>",
    "_externalKeyFields": ["_sourceKey"],
    "_sourceKey": "r-1",
    "_name": "Room 1"
    },
    {
    "_classId": "<Pump class ID>",
    "_externalKeyFields": ["_sourceKey"],
    "_sourceKey": "p-1",
    "_name": "Pump A",
    "properties": { "flowRate": 42.5 },
    "_relationships": [
    {
    "_propertyName": "locatedAt",
    "_parentExternalKey": "_sourceKey=p-1",
    "_childExternalKeys": ["_sourceKey=r-1"],
    "_targetClassId": "<Room class ID>"
    }
    ]
    }
    ]

    For more information, see Import individuals.

  2. Review the dry run result. If the response is 422, read _plan and _validation in each _classes entry to find the elements that fail, fix the data, and repeat step 1.

  3. Send the same data without dryRun to queue the import. Note the _taskId in the response.

    POST /aosvc/api/v1/ontologies/{ontologyId}/import?nsfilter=myapp

    Note: A 202 response means the import is queued, not that it succeeded.

  4. Get the task until _status is COMPLETED or FAILED. While the import runs, _batchCompleted counts the class groups it has finished.

    GET /aosvc/api/v1/async-tasks/{taskId}?nsfilter=myapp

    For more information, see Get an async task.

  5. Check the outcome:

    • If _status is COMPLETED, read _response._body._conforms. If it's true, the import succeeded. If it's false, the import didn't conform. By default, the service has already deleted what the import created, and _response._body._rollback shows the deletes.
    • If _status is FAILED, read the reason in _detailedStatus.
  6. To remove the individuals that the import created, undo the import with its task ID.

    DELETE /aosvc/api/v1/ontologies/{ontologyId}/import/{taskId}?nsfilter=myapp

    Note: Undoing an import needs INDIVIDUALS_DELETE on every class that the import wrote to, or on every class of the ontology once the import's task has expired. It deletes only the individuals that the import created, not the ones it updated.

    For more information, see Undo an import.