Skip to main content
Version: v5.3

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.
  • EDIT permission on the ontology.
  • To use an existing collection, the ID of a NamedUserCollection or NamedTelemetryCollection in your namespace, and READ permission on it. A class that descends from Telemetry needs a NamedTelemetryCollection. 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:

  1. 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=myapp
    X-Ontology-Draft: 2

    {
    "_collectionName": "facility-pumps",
    "_userType": "Pump"
    }

    To use an existing collection instead, send its _userItemId or _id as _collectionId:

    POST /aosvc/api/v1/classes/{classId}/mapping?nsfilter=myapp
    X-Ontology-Draft: 2

    {
    "_collectionId": "66f2a1c9e4b0a37d5c8e9a10",
    "_userType": "Pump"
    }

    Note: Send only one of _collectionName and _collectionId. Each _collectionName can be used by only one class in a version.

    For more information, see Bind a class to a collection.

  2. 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=myapp
    X-Ontology-Draft: 2

    {
    "_itemsvcField": "properties.flowRate",
    "_ontologyProperty": "nominalFlowRate",
    "_transform": "number"
    }

    For more information, see Add a property mapping.

  3. Check the binding in the draft.

    GET /aosvc/api/v1/classes/{classId}/mapping?nsfilter=myapp
    X-Ontology-Draft: 2

    For more information, see Get a collection binding.

  4. Check the property mappings in the draft.

    GET /aosvc/api/v1/classes/{classId}/mapping/properties?nsfilter=myapp
    X-Ontology-Draft: 2

    For more information, see List property mappings.

  5. Publish and promote the draft. For the steps, see steps 6 to 10 of Creating an ontology.

  6. Get the binding from the live version, and check that _collectionId has a value.

    GET /aosvc/api/v1/classes/{classId}/mapping?nsfilter=myapp

    Note: If you bound the class by name, promotion creates the collection and sets _collectionId to 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.