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_CREATEon every class you import into, andINDIVIDUALS_EDITon every class whose elements carry import-form relationships. For more information, see Granting permissions.- For the default
UPSERTmode, 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:
-
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.
-
Review the dry run result. If the response is
422, read_planand_validationin each_classesentry to find the elements that fail, fix the data, and repeat step 1. -
Send the same data without
dryRunto queue the import. Note the_taskIdin the response.POST /aosvc/api/v1/ontologies/{ontologyId}/import?nsfilter=myappNote: A
202response means the import is queued, not that it succeeded. -
Get the task until
_statusisCOMPLETEDorFAILED. While the import runs,_batchCompletedcounts the class groups it has finished.GET /aosvc/api/v1/async-tasks/{taskId}?nsfilter=myappFor more information, see Get an async task.
-
Check the outcome:
- If
_statusisCOMPLETED, read_response._body._conforms. If it'strue, the import succeeded. If it'sfalse, the import didn't conform. By default, the service has already deleted what the import created, and_response._body._rollbackshows the deletes. - If
_statusisFAILED, read the reason in_detailedStatus.
- If
-
To remove the individuals that the import created, undo the import with its task ID.
DELETE /aosvc/api/v1/ontologies/{ontologyId}/import/{taskId}?nsfilter=myappNote: Undoing an import needs
INDIVIDUALS_DELETEon 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.