Mapping a class to a collection
Mapping a class to a collection
This page shows how to bind a class to an Item Service collection and map item fields to ontology properties, so the class can hold individuals. For background, see Collection mapping.
Before you start, make sure you have the following:
- An ontology with the class you want to map, and an editable draft version. For more information, see Creating an ontology.
EDITpermission on the ontology.- To use an existing collection, the ID of a
NamedUserCollectionorNamedTelemetryCollectionin your namespace, andREADpermission on it. A class that descends fromTelemetryneeds aNamedTelemetryCollection. The collection can't belong to another platform service.
Every request needs an Authorization: Bearer <token> header. The examples use the namespace myapp and draft version 2.
To map a class to a collection, complete the following steps:
-
Bind the class to a collection in the draft. To have the service create a new collection at promotion, send
_collectionName:POST /aosvc/api/v1/classes/{classId}/mapping?nsfilter=myappX-Ontology-Draft: 2{"_collectionName": "facility-pumps","_userType": "Pump"}To use an existing collection instead, send its
_userItemIdor_idas_collectionId:POST /aosvc/api/v1/classes/{classId}/mapping?nsfilter=myappX-Ontology-Draft: 2{"_collectionId": "66f2a1c9e4b0a37d5c8e9a10","_userType": "Pump"}Note: Send only one of
_collectionNameand_collectionId. Each_collectionNamecan be used by only one class in a version.For more information, see Bind a class to a collection.
-
Add a property mapping for each item field you want to link to an ontology property.
POST /aosvc/api/v1/classes/{classId}/mapping/properties?nsfilter=myappX-Ontology-Draft: 2{"_itemsvcField": "properties.flowRate","_ontologyProperty": "nominalFlowRate","_transform": "number"}For more information, see Add a property mapping.
-
Check the binding in the draft.
GET /aosvc/api/v1/classes/{classId}/mapping?nsfilter=myappX-Ontology-Draft: 2For more information, see Get a collection binding.
-
Check the property mappings in the draft.
GET /aosvc/api/v1/classes/{classId}/mapping/properties?nsfilter=myappX-Ontology-Draft: 2For more information, see List property mappings.
-
Publish and promote the draft. For the steps, see steps 6 to 10 of Creating an ontology.
-
Get the binding from the live version, and check that
_collectionIdhas a value.GET /aosvc/api/v1/classes/{classId}/mapping?nsfilter=myappNote: If you bound the class by name, promotion creates the collection and sets
_collectionIdto the new collection's_userItemId.For more information, see Get a collection binding.
The class can now hold individuals. For more information, see Creating individuals and relationships.