IafAOSvc
Use the IafAOSvc API to work with AO Service resources, such as an ontology's impact analysis reports.
abandonPromotionRequest
Abandons an open promotion request so a different version can be put forward. Needs the action on the ontology.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| requestId | Yes | String | Pass the promotion request's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcPromotionRequest> - A promise with the promotion request.
const request = await IafAOSvc.abandonPromotionRequest('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'req-1', ctx);
acquireOntologyLock
Acquires an ontology's edit lock. Fails with 409 when another user holds it. Reports when the ontology is not lock-protected.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcOntologyLock> - A promise with the lock status.
const lock = await IafAOSvc.acquireOntologyLock('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
if (lock._changedByAnother) console.log('Someone edited the ontology while you were away.');
addPropertyMapping
Adds a field to property mapping to a class.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| mapping | Yes | AosvcPropertyMappingCreate | Pass a property mapping. is required. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcPropertyMapping> - A promise with the created property mapping.
const mapping = await IafAOSvc.addPropertyMapping('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', { _itemsvcField: 'properties.flowRate', _ontologyProperty: 'flowRate' }, ctx);
addReadings
Appends telemetry readings to one individual (telemetry item) of a Telemetry-rooted class.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| individualId | Yes | String | Pass the individual's id. |
| readings | Yes | (JSON | Array<JSON>) | Pass one reading object or an array of readings. |
| criteria | No | AosvcAddReadingsCriteria | Pass a JSON object with "sourceId" and "transactional" parameters. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.addReadings('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', 'sensor-1', [{ _ts: '2026-09-30T10:00:00Z', value: 21.4 }], { transactional: true }, ctx);
addReadingsBatch
Appends telemetry readings to several individuals (telemetry items) of a Telemetry-rooted class.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| readings | Yes | (JSON | Array<JSON>) | Pass one reading object or an array of readings. Each reading identifies its individual. |
| criteria | No | AosvcAddReadingsCriteria | Pass a JSON object with a "transactional" parameter. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.addReadingsBatch('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', readings, { transactional: false }, ctx);
applyChangeSet
Atomically applies an ordered set of add, update and delete schema operations as one new revision. Pass the header to guard against concurrent changes.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| changeSet | Yes | AosvcChangeSet | Pass an object with an ordered array. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcRevision> - A promise with the new revision manifest.
const revision = await IafAOSvc.applyChangeSet('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {
operations: [
{ op: 'update', collection: 'entity_classes', id: '5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', document: updatedClassDocument }
]
}, ctx, { headers: { 'If-Match': '"6"' } });
bindStateMachineClasses
Binds additional classes to a state machine's . Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| machineId | Yes | String | Pass the state machine's id. |
| binding | Yes | AosvcStateMachineClassBinding | Pass an object with the to bind. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcStateMachine> - A promise with the updated state machine.
const machine = await IafAOSvc.bindStateMachineClasses('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'machine-1', { _classIds: ['valve-cls'] }, ctx, { headers: { 'X-Ontology-Draft': 2 } });
bulkAddIndividualRelationships
Bulk-adds individual relationships asynchronously. The call returns a task id immediately; validation and the submit run on a worker. Poll the task with getBulkRelationshipsStatus. The batch is validated all-or-nothing.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| relationships | Yes | Array<AosvcIndividualRelationship> | Pass a JSON array of relationship edges (maximum 10 MB). Each entry needs , and . |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<JSON> - A promise with the accepted task: , (QUEUED) and .
const task = await IafAOSvc.bulkAddIndividualRelationships('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', [
{ _relatedFromId: 'pump-1', _userType: 'locatedIn', _relatedToIds: ['room-1'] }
], ctx);
confirmPromotionRequest
Confirms a promotion request: step two, which makes the version live. Needs the action on the ontology; is not enough. The version is applied by a queued job that runs as the caller, so the service answers 202 with no body and a header, the URL of the promotion request.When the request has an impact analysis report, is required: it must be this request's report, it must be , and the live version must not have changed since it was made — otherwise the call fails (400 when missing, 409 otherwise). A first promotion has no report and needs no body.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| requestId | Yes | String | Pass the promotion request's id. |
| confirm | No | AosvcPromotionConfirm | Pass an object with the of the request's report. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<(AosvcPromotionRequest | String)> - A promise with the promotion request (200, when the service applies it at once). When the job was queued (202) there is no body, so the promise resolves with the request's absolute URL; poll the request with getPromotionRequests until its is PROMOTED or FAILED.
const request = await IafAOSvc.confirmPromotionRequest('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'req-1',
{ _reportId: '7e2b4f19-6c8a-4d05-9e31-2a8f6c1d9b47' }, ctx);
createAction
Creates an action. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| action | Yes | AosvcActionCreate | Pass an action object. and are required. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcAction> - A promise with the created action.
const action = await IafAOSvc.createAction('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {
_name: 'Notify on fault', _actionType: 'NOTIFICATION', _params: { template: 'pump_fault' }
}, ctx, { headers: { 'X-Ontology-Draft': 2 } });
createClasses
Creates one or more entity classes in an ontology. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| classes | Yes | (AosvcEntityClassCreate | Array<AosvcEntityClassCreate>) | Pass one entity class or an array of entity classes to create. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<JSON> - A promise with the created class, or an array of the created classes.
const created = await IafAOSvc.createClasses('a1b2c3d4-e5f6-7890-abcd-ef1234567890', [
{ _name: 'Pump', _parentClass: { _id: 'Equipment' }, _pluralName: 'Pumps' }
], ctx, { headers: { 'X-Ontology-Draft': 2 } });
createConstraints
Adds one or more property constraints to an ontology. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| constraints | Yes | (AosvcConstraintCreate | Array<AosvcConstraintCreate>) | Pass one constraint or an array of constraints. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<JSON> - A promise with the created constraint, or an array of the created constraints.
const created = await IafAOSvc.createConstraints('a1b2c3d4-e5f6-7890-abcd-ef1234567890', [{
_constraintId: 'pump-name-required',
_targetClass: { _id: 'pump-cls' },
_constraintsJson: JSON.stringify({ _name: { minCount: 1 } })
}], ctx, { headers: { 'X-Ontology-Draft': 2 } });
createDraft
Creates a draft by copying a version. Copies the live version unless names another. Use the draft number in the header for schema writes.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| draft | Yes | AosvcDraftCreate | Optionally pass an object with the to copy. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcOntologyVersion> - A promise with the draft version.
const draft = await IafAOSvc.createDraft('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {}, ctx);
// Then write to the draft
await IafAOSvc.createClasses('a1b2c3d4-e5f6-7890-abcd-ef1234567890', { _name: 'Valve', _parentClass: { _id: 'Equipment' } }, ctx, { headers: { 'X-Ontology-Draft': draft._versionNumber } });
createIndividualRelationship
Creates a relationship from an individual to one or more target individuals. The relationship is validated against the ontology.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| individualId | Yes | String | Pass the individual's id. |
| relationship | Yes | AosvcIndividualRelationship | Pass the relationship type in and the targets in . |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcIndividualRelationship>> - A promise with the relationship edges of the individual.
const edges = await IafAOSvc.createIndividualRelationship('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', 'pump-1', { _userType: 'locatedIn', _relatedToIds: ['room-1'] }, ctx);
createIndividuals
Creates one or more individuals of a class. The individuals are validated against the ontology first and stored in ItemSvc. A non-conforming body is rejected with 422.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| individuals | Yes | (JSON | Array<JSON>) | Pass one individual or an array of individuals. Inline are created with them. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<JSON> - A promise with the created individual, or an array of the created individuals.
const created = await IafAOSvc.createIndividuals('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', [
{ _name: 'Pump A', _relationships: [{ _userType: 'locatedIn', _relatedToIds: ['room-1'] }] },
{ _name: 'Pump B' }
], ctx);
createOntology
Creates an application ontology.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontology | Yes | AosvcOntologyCreate | Pass an ontology object. is required. Set to opt in to edit locking. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcOntology> - A promise with the created ontology.
const ontology = await IafAOSvc.createOntology({
_name: 'Plant Ontology',
_description: 'Pumps, valves and rooms of the plant.',
_editLockTimeoutSeconds: 21600
}, ctx);
createOrUpdatePermissions
Idempotently creates or updates ontology or ontology class permissions. Class permission changes, and ontology permissions that grant (or stop granting) or , reconcile downstream Item Service grants in the background; the service then answers 202 instead of 200, with the same body. The task is identified by the response header (), which this method returns as the non-enumerable property of the response: pass its last path segment to getAsyncTask and poll until the task is COMPLETED or FAILED.
| Parameter | Required | Type | Description |
|---|---|---|---|
| permissions | Yes | Array<Permission> | Pass an array of Permission objects whose is an aosvc ontology or ontology class IRN. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<CreatePermissionsResponse> - A promise with the created and failed permissions, for both 200 and 202. Check : it is the only place a failed grant is reported. On a 202, holds the task's absolute URL.
const response = await IafAOSvc.createOrUpdatePermissions([{
_namespace: 'plant_ns',
_resourceDesc: { _irn: 'aosvc:ontology:a1b2c3d4-e5f6-7890-abcd-ef1234567890' },
_user: { _id: 'f1e2d3c4-b5a6-4789-8abc-def012345678', _type: 'usergroup' },
_actions: ['READ']
}], ctx);
createPromotionRequest
Requests a promotion of a published version: step one, which runs the checks and reports what they found. Needs the action on the ontology; is not enough.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| request | Yes | AosvcPromotionRequestCreate | Pass an object with the to promote. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as .The request carries an impact analysis report on the version against the live one, as — an |
| existing matching report or a new one being generated. A first promotion, with nothing live yet, has none. |
Promise<AosvcPromotionRequest> - A promise with the promotion request, including .
const ontologyId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const request = await IafAOSvc.createPromotionRequest(ontologyId, { _versionNumber: 2 }, ctx);
if (request._reportId) {
// Review the report once it is READY, then confirm with it.
let report = await IafAOSvc.getImpactAnalysisReport(ontologyId, request._reportId, ctx);
while (report._status === 'PENDING') {
await new Promise(resolve => setTimeout(resolve, 2000));
report = await IafAOSvc.getImpactAnalysisReport(ontologyId, request._reportId, ctx);
}
}
await IafAOSvc.confirmPromotionRequest(ontologyId, request._requestId, { _reportId: request._reportId }, ctx);
createRelationship
Adds an object property relationship between two classes. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| relationship | Yes | AosvcEntityRelationshipCreate | Pass a relationship object. , and are required. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcEntityRelationship> - A promise with the created relationship.
const relationship = await IafAOSvc.createRelationship('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {
_sourceClassId: 'pump-cls', _targetClassId: 'room-cls', _type: 'locatedIn'
}, ctx, { headers: { 'X-Ontology-Draft': 2 } });
createRules
Adds one or more rules to an ontology. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| rules | Yes | (AosvcRuleCreate | Array<AosvcRuleCreate>) | Pass one rule or an array of rules. is required. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<JSON> - A promise with the created rule, or an array of the created rules.
const created = await IafAOSvc.createRules('a1b2c3d4-e5f6-7890-abcd-ef1234567890', [
{ _ruleType: 'SubClassOf', _subClassId: 'pump-cls', _superClassId: 'equipment-cls' }
], ctx, { headers: { 'X-Ontology-Draft': 2 } });
createStateMachine
Creates a complete state machine. Exactly one state must be marked — the state a new individual of a bound class starts in (422 otherwise). Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| stateMachine | Yes | AosvcStateMachine | Pass the complete state machine: name, class ids, states, events and transitions. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcStateMachine> - A promise with the created state machine.
const machine = await IafAOSvc.createStateMachine('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {
_name: 'Pump status',
_classIds: ['pump-cls'],
_states: [{ _id: 's-on', _name: 'On', _value: 'ON', _initial: true }, { _id: 's-off', _name: 'Off', _value: 'OFF' }],
_events: [{ _id: 'e-stop', _name: 'Stop' }],
_transitions: [{ _name: 'Stop pump', _fromStateId: 's-on', _toStateId: 's-off', _eventIds: ['e-stop'], _actions: [] }]
}, ctx, { headers: { 'X-Ontology-Draft': 2 } });
deleteAction
Deletes an action. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| actionId | Yes | String | Pass the action's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.deleteAction('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'action-1', ctx, { headers: { 'X-Ontology-Draft': 2 } });
deleteAsyncTask
Deletes a task row. Note: this route is disabled in aosvc 5.3 (its controller is commented out), so the service currently answers 404.
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Yes | String | Pass the resource's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.deleteAsyncTask('f3b1c2d4-0000-4000-8000-000000000002', ctx);
deleteClass
Deletes an entity class. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| classId | Yes | String | Pass the entity class's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.deleteClass('a1b2c3d4-e5f6-7890-abcd-ef1234567890', '5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', ctx, { headers: { 'X-Ontology-Draft': 2 } });
deleteCollectionMapping
Removes the binding and property mappings of a class. Also deletes the ItemSvc collection and its items unless another class still maps to it.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.deleteCollectionMapping('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', ctx);
deleteConstraint
Deletes a property constraint. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| constraintId | Yes | String | Pass the constraint's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.deleteConstraint('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'pump-name-required', ctx, { headers: { 'X-Ontology-Draft': 2 } });
deleteImport
Undoes an import by deleting the individuals it created. The deletes run asynchronously in ItemSvc, so the result is not a completion receipt.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| asyncTaskId | Yes | String | Pass the import's async task id (the _asyncTaskId of its result). |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcImportCleanupResult> - A promise with what was dispatched.
const result = await IafAOSvc.deleteImport('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'f3b1c2d4-0000-4000-8000-000000000002', ctx);
deleteIndividual
Deletes an individual.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| individualId | Yes | String | Pass the individual's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.deleteIndividual('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', 'pump-1', ctx);
deleteIndividualRelationship
Removes one relationship edge from an individual.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| individualId | Yes | String | Pass the individual's id. |
| userType | Yes | String | Pass the relationship type name. |
| targetIndividualId | Yes | String | Pass the target individual's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcIndividualRelationship>> - A promise with the remaining relationship edges of the individual.
const edges = await IafAOSvc.deleteIndividualRelationship('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', 'pump-1', 'locatedIn', 'room-1', ctx);
deleteMcpConfig
Removes the MCP tool configuration of a class.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.deleteMcpConfig('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', ctx);
deleteOntology
Deletes an application ontology.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.deleteOntology('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
deletePropertyMapping
Removes a field to property mapping from a class.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| mappingId | Yes | String | Pass the property mapping's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.deletePropertyMapping('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', 'mapping-1', ctx);
deleteRelationship
Removes an object property relationship. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| relationshipId | Yes | String | Pass the relationship's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.deleteRelationship('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'rel-1', ctx, { headers: { 'X-Ontology-Draft': 2 } });
deleteRule
Deletes a rule. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ruleId | Yes | String | Pass the rule's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.deleteRule('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'rule-1', ctx, { headers: { 'X-Ontology-Draft': 2 } });
deleteStateMachine
Deletes a state machine definition. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| machineId | Yes | String | Pass the state machine's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.deleteStateMachine('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'machine-1', ctx, { headers: { 'X-Ontology-Draft': 2 } });
discardDraft
Discards a draft and deletes its schema rows.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| versionNumber | Yes | Number | Pass the ontology version's number. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.discardDraft('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 2, ctx);
explainOwl
Returns bounded proof availability and reasoner metadata for an axiom of an OWL preview.
| Parameter | Required | Type | Description |
|---|---|---|---|
| request | Yes | AosvcOwlExplanationRequest | Pass the and the preview request it came from. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcOwlExplanationResponse> - A promise with the explanation.
const explanation = await IafAOSvc.explainOwl({ contractVersion: 1, axiomId: preview.axioms[0].id, preview: previewRequest }, ctx);
generateModel
Build with AI: proposes an application model (subclasses, relationships and rules) through aisvc.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| request | Yes | AosvcGenerateModelRequest | Pass a request with the , and optionally a team, the current model, conversation history and file attachments. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcGenerateModelResponse> - A promise with the proposed model.
const response = await IafAOSvc.generateModel('a1b2c3d4-e5f6-7890-abcd-ef1234567890', { _prompt: 'Model a water treatment plant with pumps, valves and tanks.' }, ctx);
getAction
Gets an action by its id.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| actionId | Yes | String | Pass the action's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcAction> - A promise with the action.
const action = await IafAOSvc.getAction('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'action-1', ctx);
getActions
Gets the actions defined in an ontology.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcAction>> - A promise with the actions.
const actions = await IafAOSvc.getActions('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
getAsyncTask
Gets the state of a queued aosvc task, such as a bulk import, a bulk relationship add, a promotion or a permission reconciliation.
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Yes | String | Pass the resource's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcAsyncTask> - A promise with the task.
const task = await IafAOSvc.getAsyncTask('f3b1c2d4-0000-4000-8000-000000000002', ctx);
getBaseClasses
Gets the core classes defined in the base platform ontology.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcCoreClass>> - A promise with the core classes.
const coreClasses = await IafAOSvc.getBaseClasses(ctx);
getBaseOntology
Gets the base platform ontology files: the ontology, its rules and its constraints.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<JSON> - A promise with the base ontology files.
const base = await IafAOSvc.getBaseOntology(ctx);
getBaseOntologyVersions
Gets the available base platform ontology versions, newest first.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcBaseOntologyVersion>> - A promise with the base ontology versions.
const versions = await IafAOSvc.getBaseOntologyVersions(ctx);
getBulkRelationshipsStatus
Gets the status of a bulk relationship task: the aosvc status while it is queued, validating or rejected, and then the ItemSvc task status once submitted.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| taskId | Yes | String | Pass the task's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<JSON> - A promise with the task status.
const status = await IafAOSvc.getBulkRelationshipsStatus('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', task._taskId, ctx);
getClass
Gets an entity class by its id.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| classId | Yes | String | Pass the entity class's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcEntityClass> - A promise with the entity class.
const entityClass = await IafAOSvc.getClass('a1b2c3d4-e5f6-7890-abcd-ef1234567890', '5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', ctx);
getClasses
Gets the entity classes of an ontology that the caller may read.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcEntityClass>> - A promise with the entity classes.
const classes = await IafAOSvc.getClasses('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
// Read the classes of a draft version
const draftClasses = await IafAOSvc.getClasses('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx, { headers: { 'X-Ontology-Draft': 2 } });
getClassPermissions
Gets the Passport permissions granted on an entity class.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<Permission>> - A promise with the permissions.
const permissions = await IafAOSvc.getClassPermissions('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', ctx);
getClassReadings
Gets the telemetry readings of all the individuals (telemetry items) of a Telemetry-rooted class, newest first.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| criteria | No | AosvcReadingsCriteria | Pass a JSON object with "from", "to", "offset", "limit" and "ascending" parameters. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcReadingsPage> - A promise with a page of readings.
const page = await IafAOSvc.getClassReadings('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', { ascending: true, limit: 200 }, ctx);
getCollectionMapping
Gets the ItemSvc collection a class is bound to.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcCollectionMapping> - A promise with the collection mapping.
const mapping = await IafAOSvc.getCollectionMapping('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', ctx);
getConstraints
Gets the property constraints defined for an ontology.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcConstraint>> - A promise with the constraints.
const constraints = await IafAOSvc.getConstraints('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
getEffectiveClassSchema
Gets the effective schema of a class: its properties (including inherited ones), constraints and state machines. Pass 'base' as the ontologyId to read a base platform class.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| classId | Yes | String | Pass the entity class's id. |
| criteria | No | AosvcEffectiveSchemaCriteria | Pass a JSON object with "inherited" and "baseVersion" filters. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcEffectiveClassSchema> - A promise with the effective schema.
const schema = await IafAOSvc.getEffectiveClassSchema('a1b2c3d4-e5f6-7890-abcd-ef1234567890', '5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', {}, ctx);
// Only the properties the class declares itself
const own = await IafAOSvc.getEffectiveClassSchema('a1b2c3d4-e5f6-7890-abcd-ef1234567890', '5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', { inherited: false }, ctx);
getImpactAnalysisReport
Gets an impact analysis report by its id, including once it is , or if it .
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| reportId | Yes | String | Pass the report's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
Promise<ImpactAnalysisReport> - A promise with the ImpactAnalysisReport object.
const report = await IafAOSvc.getImpactAnalysisReport('d4721098-9c7f-4e7d-84f4-84bea8f21ca2', '7e2b4f19-6c8a-4d05-9e31-2a8f6c1d9b47', ctx);
getImpactAnalysisReports
Gets an ontology's impact analysis reports that match your criteria, newest first. Reports in the page do not include ; get a report by its id for that.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| criteria | No | ImpactAnalysisReportCriteria | Pass a JSON object with a filter, such as by or . |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcOptions | Pass a JSON object for optional control parameters, such as pagination options. |
Promise<Page<ImpactAnalysisReport>> - A promise with a page that contains the ImpactAnalysisReport objects, without .
// Get the latest reports
const reports = await IafAOSvc.getImpactAnalysisReports('d4721098-9c7f-4e7d-84f4-84bea8f21ca2', {}, ctx);
// Get reports on version 3 created after a date
const v3Reports = await IafAOSvc.getImpactAnalysisReports('d4721098-9c7f-4e7d-84f4-84bea8f21ca2',
{ query: { _versionFrom: 3, _createdAt: { $gt: '2026-09-22T14:00:00Z' } } }, ctx, { _pageSize: 10 });
// Get reports with breaking changes
const breaking = await IafAOSvc.getImpactAnalysisReports('d4721098-9c7f-4e7d-84f4-84bea8f21ca2',
{ query: { '_report._verdict._breaking': { $gt: 0 } } }, ctx);
getIndividual
Gets an individual by its id.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| individualId | Yes | String | Pass the individual's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<JSON> - A promise with the individual.
const individual = await IafAOSvc.getIndividual('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', 'pump-1', ctx);
getIndividualRelationships
Gets the relationship edges of an individual.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| individualId | Yes | String | Pass the individual's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcIndividualRelationship>> - A promise with the relationship edges.
const edges = await IafAOSvc.getIndividualRelationships('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', 'pump-1', ctx);
getIndividuals
Gets the individuals of a class.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| criteria | No | AosvcLimitCriteria | Pass a JSON object with a "limit". The service default is 1000. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<JSON>> - A promise with the individuals.
const individuals = await IafAOSvc.getIndividuals('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', { limit: 100 }, ctx);
getMcpConfig
Gets the MCP tool declaration of a class.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcMcpConfig> - A promise with the MCP configuration.
const config = await IafAOSvc.getMcpConfig('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', ctx);
getOntologies
Gets the base ontology and the application ontology of the namespace.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcOntology>> - A promise with the ontologies.
const ontologies = await IafAOSvc.getOntologies(ctx);
getOntology
Gets an application ontology by its id.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcOntology> - A promise with the ontology.
const ontology = await IafAOSvc.getOntology('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
getOntologyLock
Gets who currently holds an ontology's edit lock.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcOntologyLock> - A promise with the lock status.
const lock = await IafAOSvc.getOntologyLock('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
getOntologyMappings
Gets the ItemSvc collection mappings of all the classes in an ontology.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcCollectionMapping>> - A promise with the collection mappings.
const mappings = await IafAOSvc.getOntologyMappings('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
getOntologyPermissions
Gets the Passport permissions granted on an ontology.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<Permission>> - A promise with the permissions.
const permissions = await IafAOSvc.getOntologyPermissions('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
getOntologySchema
Gets the complete canonical aosvc schema bundle of an ontology.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| criteria | No | AosvcSchemaCriteria | Pass a JSON object with a "revision" to read a past revision. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<JSON> - A promise with the schema bundle.
const schema = await IafAOSvc.getOntologySchema('a1b2c3d4-e5f6-7890-abcd-ef1234567890', { revision: 4 }, ctx);
getPermissions
Gets the logical ontology or ontology class permissions visible to the caller, by IRN. aosvc IRNs look like and .
| Parameter | Required | Type | Description |
|---|---|---|---|
| criteria | No | PermissionCriteria | Pass a JSON object with "_namespace" and "_resourceDesc._irn", and optionally "_user._id", "_user._type" and "patternmatch". |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Page<Permission>> - A promise with the permissions.
const permissions = await IafAOSvc.getPermissions({ _namespace: 'plant_ns', '_resourceDesc._irn': 'aosvc:ontology:a1b2c3d4-e5f6-7890-abcd-ef1234567890' }, ctx);
getPromotionHistory
Gets the immutable canonical promotion history of an ontology.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcCanonicalPromotion>> - A promise with the promotion records.
const history = await IafAOSvc.getPromotionHistory('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
getPromotionRequests
Gets the promotion requests of an ontology, newest first.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcPromotionRequest>> - A promise with the promotion requests.
const requests = await IafAOSvc.getPromotionRequests('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
getPropertyMappings
Gets the field to property mappings of a class.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcPropertyMapping>> - A promise with the property mappings.
const mappings = await IafAOSvc.getPropertyMappings('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', ctx);
getReadings
Gets the telemetry readings of one individual (telemetry item), newest first.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| individualId | Yes | String | Pass the individual's id. |
| criteria | No | AosvcReadingsCriteria | Pass a JSON object with "from", "to", "offset", "limit" and "ascending" parameters. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcReadingsPage> - A promise with a page of readings.
const page = await IafAOSvc.getReadings('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', 'sensor-1', { from: '2026-09-01T00:00:00Z', limit: 500 }, ctx);
getRelationships
Gets the object property relationships of an ontology.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcEntityRelationship>> - A promise with the relationships.
const relationships = await IafAOSvc.getRelationships('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
getRevision
Gets the manifest of one ontology revision.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| revision | Yes | Number | Pass the aggregate revision number. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcRevision> - A promise with the revision manifest.
const revision = await IafAOSvc.getRevision('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 4, ctx);
getRevisions
Gets the immutable aggregate revisions of an ontology, newest first.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcRevision>> - A promise with the revision manifests.
const revisions = await IafAOSvc.getRevisions('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
getRevisionSnapshot
Gets the complete canonical aggregate snapshot of one revision.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| revision | Yes | Number | Pass the aggregate revision number. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<JSON> - A promise with the snapshot.
const snapshot = await IafAOSvc.getRevisionSnapshot('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 4, ctx);
getRules
Gets the rules defined for an ontology.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcRule>> - A promise with the rules.
const rules = await IafAOSvc.getRules('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
getRuleTypes
Gets the supported rule types.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcRuleType>> - A promise with the rule types.
const ruleTypes = await IafAOSvc.getRuleTypes('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
getStateMachine
Gets one complete state machine definition.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| machineId | Yes | String | Pass the state machine's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcStateMachine> - A promise with the state machine.
const machine = await IafAOSvc.getStateMachine('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'machine-1', ctx);
getStateMachineEvents
Gets every event across an ontology's state machines, grouped by machine, optionally for one machine only.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| criteria | No | AosvcStateMachinePartCriteria | Pass a JSON object with a "machineId" filter. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcStateMachineEvents>> - A promise with one entry per state machine.
const all = await IafAOSvc.getStateMachineEvents('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {}, ctx);
const one = await IafAOSvc.getStateMachineEvents('a1b2c3d4-e5f6-7890-abcd-ef1234567890', { machineId: 'machine-1' }, ctx);
getStateMachineHistory
Gets the newest transition attempts of one state machine, across every individual it tracks, newest first.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| machineId | Yes | String | Pass the state machine's id. |
| criteria | No | AosvcStateMachineHistoryCriteria | Pass a JSON object with a "limit" (default 100). |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcTransitionHistory>> - A promise with the transition attempts.
const history = await IafAOSvc.getStateMachineHistory('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'machine-1', { limit: 20 }, ctx);
getStateMachines
Gets the complete state machine definitions of an ontology, optionally only those that track a class.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| criteria | No | AosvcStateMachineCriteria | Pass a JSON object with a "classId" filter. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcStateMachine>> - A promise with the state machines.
const machines = await IafAOSvc.getStateMachines('a1b2c3d4-e5f6-7890-abcd-ef1234567890', { classId: 'pump-cls' }, ctx);
getStateMachineStates
Gets every state across an ontology's state machines, grouped by machine, optionally for one machine only.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| criteria | No | AosvcStateMachinePartCriteria | Pass a JSON object with a "machineId" filter. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcStateMachineStates>> - A promise with one entry per state machine.
const all = await IafAOSvc.getStateMachineStates('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {}, ctx);
const one = await IafAOSvc.getStateMachineStates('a1b2c3d4-e5f6-7890-abcd-ef1234567890', { machineId: 'machine-1' }, ctx);
getStateMachineTransitions
Gets every transition across an ontology's state machines, grouped by machine, optionally for one machine only.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| criteria | No | AosvcStateMachinePartCriteria | Pass a JSON object with a "machineId" filter. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcStateMachineTransitions>> - A promise with one entry per state machine.
const all = await IafAOSvc.getStateMachineTransitions('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {}, ctx);
const one = await IafAOSvc.getStateMachineTransitions('a1b2c3d4-e5f6-7890-abcd-ef1234567890', { machineId: 'machine-1' }, ctx);
getTransitionHistory
Gets the attempted state transitions of an individual, committed or rejected, newest first.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| individualId | Yes | String | Pass the individual's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcTransitionHistory>> - A promise with the transition history.
const history = await IafAOSvc.getTransitionHistory('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', 'pump-1', ctx);
getVersion
Gets one ontology version, including how many rows it holds per collection.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| versionNumber | Yes | Number | Pass the ontology version's number. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcOntologyVersion> - A promise with the version.
const version = await IafAOSvc.getVersion('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 2, ctx);
getVersions
Gets every version of an ontology, oldest first.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<AosvcOntologyVersion>> - A promise with the versions.
const versions = await IafAOSvc.getVersions('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
grantClassPermission
Grants a user, user group or profile permissions on an entity class. The grant cascades to its subclasses.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| grant | Yes | AosvcPermissionGrant | Pass the grantee and the actions to grant. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.grantClassPermission('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', {
_user: { _id: 'f1e2d3c4-b5a6-4789-8abc-def012345678', _type: 'usergroup' },
_actions: ['INDIVIDUALS_READ', 'INDIVIDUALS_EDIT']
}, ctx);
grantOntologyPermission
Grants a user, user group or profile permissions on an ontology. Granting (or ) also gives the grantee the Item Service access a promotion needs; that is done before the call returns, so the answer is still 204 and the grantee can promote at once.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| grant | Yes | AosvcPermissionGrant | Pass the grantee and the actions to grant. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.grantOntologyPermission('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {
_user: { _id: 'f1e2d3c4-b5a6-4789-8abc-def012345678', _type: 'usergroup' },
_actions: ['READ', 'EDIT']
}, ctx);
heartbeatOntologyLock
Extends an ontology's edit lock lease without making a change.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcOntologyLock> - A promise with the lock status.
const lock = await IafAOSvc.heartbeatOntologyLock('a1b2c3d4-e5f6-7890-abcd-ef1234567890', ctx);
importData
Bulk-imports individuals across multiple classes and sets relationship edges between them. A real import is queued and returns a task id; poll it with getAsyncTask. A dry run validates inline and writes nothing.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| individuals | Yes | Array<AosvcImportIndividual> | Pass a non-empty JSON array of individuals (maximum 10 MB). Each names its class in ; inline become edges. |
| criteria | No | AosvcImportCriteria | Pass a JSON object with "dryRun", "mode", "facets", "rollback" and "modelRevision" parameters. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<JSON> - A promise with the queued task (, , , ), or with the validation result for a dry run.
// Validate first
const check = await IafAOSvc.importData('a1b2c3d4-e5f6-7890-abcd-ef1234567890', individuals, { dryRun: true }, ctx);
// Then import and poll the task
const task = await IafAOSvc.importData('a1b2c3d4-e5f6-7890-abcd-ef1234567890', individuals, { mode: 'UPSERT' }, ctx);
const status = await IafAOSvc.getAsyncTask(task._taskId, ctx);
inferSchema
Infers an ItemSvc item type schema from raw JSON sample data through aisvc.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| request | Yes | AosvcInferSchemaRequest | Pass a request whose is the sample data as a JSON string. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcInferSchemaResponse> - A promise with the inferred schema.
const response = await IafAOSvc.inferSchema('a1b2c3d4-e5f6-7890-abcd-ef1234567890', { dataJson: JSON.stringify([{ name: 'Pump A', flowRate: 12.5 }]), _typeName: 'pump' }, ctx);
prepareSource
Infers an instance-map dataset from File Service attachments through aisvc.
| Parameter | Required | Type | Description |
|---|---|---|---|
| request | Yes | AosvcSourcePrepareRequest | Pass the file attachments to infer from. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcSourcePrepareResponse> - A promise with the dataset and the inference log.
const response = await IafAOSvc.prepareSource({ _attachments: [{ _fileId: 'file-1', _fileVersionId: 'ver-1' }] }, ctx);
prepareSourceStream
Infers a dataset from File Service attachments and returns the aisvc progress. The service streams NDJSON; this method resolves with all the events once the stream ends.
| Parameter | Required | Type | Description |
|---|---|---|---|
| request | Yes | AosvcSourcePrepareRequest | Pass the file attachments to infer from. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<Array<JSON>> - A promise with the array of progress events, in order.
const events = await IafAOSvc.prepareSourceStream({ _attachments: [{ _fileId: 'file-1', _fileVersionId: 'ver-1' }] }, ctx);
previewOwl
Parses and classifies bounded inline OWL documents without persisting them.
| Parameter | Required | Type | Description |
|---|---|---|---|
| request | Yes | AosvcOwlPreviewRequest | Pass a request with 1 and the OWL as inline text. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcOwlPreviewResponse> - A promise with the classification, axioms and diagnostics.
const preview = await IafAOSvc.previewOwl({
contractVersion: 1,
documents: [{ name: 'plant.ttl', content: turtleText, mediaType: 'text/turtle' }],
includeInferred: true
}, ctx);
promoteRevision
Promotes a canonical revision through schema export and import. Runs as a dry run unless is false.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| request | Yes | AosvcCanonicalPromotionRequest | Pass a promotion request. is required; defaults to true. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcCanonicalPromotion> - A promise with the promotion record.
const promotion = await IafAOSvc.promoteRevision('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {
reason: 'Release 2.1', sourceRevision: 6, targetNamespace: 'plant_prod', targetEnvironment: 'prod', dryRun: false
}, ctx);
provisionMcpConfig
Provisions the declared MCP tool in aisvc. The tool wraps the class's OMAPI 'list' script.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcMcpConfig> - A promise with the MCP configuration and its .
const config = await IafAOSvc.provisionMcpConfig('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', ctx);
publishStateMachineEvent
Queues a state machine event for individuals grouped by class. This changes individuals, not the ontology definition.
| Parameter | Required | Type | Description |
|---|---|---|---|
| machineId | Yes | String | Pass the state machine's id. |
| event | Yes | AosvcStateMachineEventPublish | Pass the event id and name and the target individuals grouped by class (1 to 500 individuals per class). |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcStateMachineEventQueued> - A promise with the queued event trigger id.
const queued = await IafAOSvc.publishStateMachineEvent('machine-1', {
_eventId: 'e-stop', _eventName: 'Stop',
_targets: [{ _classId: 'pump-cls', _individualIds: ['pump-1', 'pump-2'] }]
}, ctx);
publishVersion
Freezes a draft so its schema can no longer change.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| versionNumber | Yes | Number | Pass the ontology version's number. |
| publish | Yes | AosvcPublish | Optionally pass an object with a for the published version. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcOntologyVersion> - A promise with the published version.
const version = await IafAOSvc.publishVersion('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 2, { _label: 'Release 2.1' }, ctx);
releaseOntologyLock
Releases an ontology's edit lock.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| criteria | No | AosvcLockReleaseCriteria | Pass { force: true } to release a lock held by another user. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcOntologyLock> - A promise with the lock status.
const lock = await IafAOSvc.releaseOntologyLock('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {}, ctx);
removePermission
Deletes a logical aosvc permission by its id. Removing a class permission, or an ontology permission that carried or , takes back the downstream Item Service grants in the background; the service then answers 202 with no body and a header that points at the task.
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | Yes | String | Pass the resource's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response, or, when a reconciliation task was queued (202), the task's absolute URL; pass its last path segment to getAsyncTask.
await IafAOSvc.removePermission('a1b2c3d4-0000-4000-8000-000000000001', ctx);
requestImpactAnalysisReport
Requests an impact analysis report: what would change if a draft or published version of an ontology replaced the live one. The report is created and filled in the background, usually within seconds, moving to (with ) or (with ).An existing or report that still describes the same version pair is returned instead of a new one. A report is never reused, so requesting again is the retry.By default the call resolves as soon as the report is stored, and you can poll IafAOSvc.getImpactAnalysisReport yourself. Pass to have it resolve once the report is or instead.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| version | Yes | ImpactAnalysisReportRequest | Pass the version to compare against the live one, by number or by id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | ImpactAnalysisReportRequestOptions | Pass to wait for the report to finish, and poll timing overrides. |
Promise<ImpactAnalysisReport> - A promise with the report: as stored (usually ), or or when is . With , rejects with an Error if the report is still after attempts.
// Request a report on version 3 and poll for it yourself
const report = await IafAOSvc.requestImpactAnalysisReport('d4721098-9c7f-4e7d-84f4-84bea8f21ca2', { _versionFrom: 3 }, ctx);
// Request a report by version id and wait until it is READY or FAILED
const finished = await IafAOSvc.requestImpactAnalysisReport('d4721098-9c7f-4e7d-84f4-84bea8f21ca2',
{ _versionFromId: 'd4721098-9c7f-4e7d-84f4-84bea8f21ca2:v3' }, ctx, { poll: true, pollMilliSecs: 1000, maxPoll: 60 });
if (finished._status === 'READY') {
console.log(finished._report._verdict);
} else {
console.log(finished._failureReason);
}
reviewDataset
Reviews an import dataset through aisvc and persists the result as a proposal.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| request | Yes | AosvcReviewDatasetRequest | Pass a request with the review , the and the , both as JSON strings. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcReviewDatasetResponse> - A promise with the review.
const response = await IafAOSvc.reviewDataset('a1b2c3d4-e5f6-7890-abcd-ef1234567890', { prompt: 'Check the data fits the model.', datasetJson, modelJson }, ctx);
revokeClassPermission
Revokes one Passport permission on an entity class.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| permissionId | Yes | String | Pass the permission's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.revokeClassPermission('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', 'a1b2c3d4-0000-4000-8000-000000000001', ctx);
revokeOntologyPermission
Revokes one Passport permission on an ontology. When it carried (or ), the Item Service access it brought is taken back first, before the call returns, so the answer is still 204.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| permissionId | Yes | String | Pass the permission's id. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<String> - {ok:204} response.
await IafAOSvc.revokeOntologyPermission('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'a1b2c3d4-0000-4000-8000-000000000001', ctx);
rollbackToRevision
Restores a prior revision snapshot as a new forward revision. Pass the header to guard against concurrent changes.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| revision | Yes | Number | Pass the aggregate revision number. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcRevision> - A promise with the new revision manifest.
const revision = await IafAOSvc.rollbackToRevision('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 4, ctx, { headers: { 'If-Match': '"6"' } });
runReasoner
Runs the stateless reasoner over the ontology, rules, constraints and instances you supply. Nothing is read from or written to the database.
| Parameter | Required | Type | Description |
|---|---|---|---|
| request | Yes | AosvcReasonerRequest | Pass the ontology definition, and optionally rules, constraints and instances. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcReasonerResult> - A promise with the inferences, violations, derived relationships and instance types.
const result = await IafAOSvc.runReasoner({
ontology: ontologyDefinition,
rules: rules,
instances: { 'pump-1': { _classId: 'pump-cls', _name: 'Pump A' } }
}, ctx);
searchIndividuals
Searches the individuals of a class with structured filters and class-subtree paging.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| search | Yes | AosvcIndividualSearchRequest | Optionally pass a search request with a filter, paging, sort and projection. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcIndividualSearchResponse> - A promise with a page of individuals.
const page = await IafAOSvc.searchIndividuals('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', {
_filter: { _name: 'Pump A' }, _includeSubclasses: true, _offset: 0, _pageSize: 50
}, ctx);
setCollectionMapping
Binds a class to an ItemSvc collection. Creates the binding or replaces the existing one.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| mapping | Yes | AosvcCollectionMappingCreate | Pass a mapping object naming the collection to create or the collection id to bind. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcCollectionMapping> - A promise with the collection mapping.
const mapping = await IafAOSvc.setCollectionMapping('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', { _collectionName: 'pumps', _userType: 'pump' }, ctx);
setIndividualRelationshipsBatch
Batch-sets relationships for many individuals of a class. Each parent and relationship type is replaced, and the whole batch is all-or-nothing.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| batch | Yes | AosvcRelationshipBatch | Pass an object with the entries to set. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<JSON> - A promise with the result of the batch.
const result = await IafAOSvc.setIndividualRelationshipsBatch('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', {
_relationships: [{ _userType: 'locatedIn', _relatedFromId: 'pump-1', _relatedToIds: ['room-1'] }]
}, ctx);
setMcpConfig
Declares, or replaces, the MCP tool configuration of a class.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| config | Yes | AosvcMcpConfigUpdate | Pass the tool name and optional query criteria. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcMcpConfig> - A promise with the MCP configuration, with PENDING.
const config = await IafAOSvc.setMcpConfig('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', { _toolName: 'list_pumps' }, ctx);
traverseRelationships
Traverses validated ontology relationships from individuals, following the hops in the order supplied.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| traversal | Yes | AosvcTraversalRequest | Pass the start individuals and the relationships to follow. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcTraversalResponse> - A promise with the path, breadcrumbs and a page of terminal individuals.
const result = await IafAOSvc.traverseRelationships('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', {
_startIndividualIds: ['pump-1'],
_hops: [{ _relationship: 'locatedIn' }]
}, ctx);
unbindStateMachineClasses
Unbinds classes from a state machine's ; at least one class must remain. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| machineId | Yes | String | Pass the state machine's id. |
| binding | Yes | AosvcStateMachineClassBinding | Pass an object with the to unbind. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcStateMachine> - A promise with the updated state machine.
const machine = await IafAOSvc.unbindStateMachineClasses('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'machine-1', { _classIds: ['valve-cls'] }, ctx, { headers: { 'X-Ontology-Draft': 2 } });
updateAction
Updates an action. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| actionId | Yes | String | Pass the action's id. |
| action | Yes | AosvcActionUpdate | Pass an action object with the properties you want to update. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcAction> - A promise with the updated action.
const action = await IafAOSvc.updateAction('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'action-1', { _description: 'Sends the fault notification.' }, ctx, { headers: { 'X-Ontology-Draft': 2 } });
updateClass
Updates an entity class. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| classId | Yes | String | Pass the entity class's id. |
| entityClass | Yes | AosvcEntityClassUpdate | Pass an entity class object with the properties you want to update. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcEntityClass> - A promise with the updated entity class.
const entityClass = await IafAOSvc.updateClass('a1b2c3d4-e5f6-7890-abcd-ef1234567890', '5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f',
{ _pluralName: 'Centrifugal Pumps' }, ctx, { headers: { 'X-Ontology-Draft': 2 } });
updateConstraint
Updates a property constraint. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| constraintId | Yes | String | Pass the constraint's id. |
| constraint | Yes | AosvcConstraintUpdate | Pass a constraint object with the properties you want to update. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcConstraint> - A promise with the updated constraint.
const constraint = await IafAOSvc.updateConstraint('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'pump-name-required', { _description: 'Every pump has a name.' }, ctx, { headers: { 'X-Ontology-Draft': 2 } });
updateIndividual
Updates an individual. The individual is validated against the ontology first. A non-conforming body is rejected with 422.
| Parameter | Required | Type | Description |
|---|---|---|---|
| classId | Yes | String | Pass the entity class's id. |
| individualId | Yes | String | Pass the individual's id. |
| individual | Yes | JSON | Pass the individual object with the properties to store. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<JSON> - A promise with the updated individual.
const individual = await IafAOSvc.updateIndividual('5f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f', 'pump-1', { _name: 'Pump A (rebuilt)' }, ctx);
updateOntology
Updates an application ontology.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ontology | Yes | AosvcOntologyUpdate | Pass an ontology object with the properties you want to update. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcOntology> - A promise with the updated ontology.
const ontology = await IafAOSvc.updateOntology('a1b2c3d4-e5f6-7890-abcd-ef1234567890', { _description: 'Updated description.' }, ctx);
updateRelationship
Updates an object property relationship. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| relationshipId | Yes | String | Pass the relationship's id. |
| relationship | Yes | AosvcEntityRelationshipCreate | Pass the complete relationship object. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcEntityRelationship> - A promise with the updated relationship.
const relationship = await IafAOSvc.updateRelationship('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'rel-1', {
_sourceClassId: 'pump-cls', _targetClassId: 'room-cls', _type: 'locatedIn', _description: 'Where the pump is installed.'
}, ctx, { headers: { 'X-Ontology-Draft': 2 } });
updateRule
Updates a rule. Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| ruleId | Yes | String | Pass the rule's id. |
| rule | Yes | AosvcRuleUpdate | Pass a rule object with the properties you want to update. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcRule> - A promise with the updated rule.
const rule = await IafAOSvc.updateRule('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'rule-1', { _superClassId: 'asset-cls' }, ctx, { headers: { 'X-Ontology-Draft': 2 } });
updateStateMachine
Replaces a complete state machine definition. Exactly one state must be marked (422 otherwise). Schema writes need the header.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| machineId | Yes | String | Pass the state machine's id. |
| stateMachine | Yes | AosvcStateMachine | Pass the complete replacement state machine. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcStateMachine> - A promise with the updated state machine.
const machine = await IafAOSvc.updateStateMachine('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'machine-1', machineDefinition, ctx, { headers: { 'X-Ontology-Draft': 2 } });
validateAgainstBaseOntology
Validates individuals against the base platform ontology constraints.
| Parameter | Required | Type | Description |
|---|---|---|---|
| request | Yes | AosvcValidationRequest | Pass an object whose is the individuals to validate, as a JSON string. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcValidationResult> - A promise with the validation result.
const result = await IafAOSvc.validateAgainstBaseOntology({ dataJson: JSON.stringify([{ _name: 'Pump A' }]) }, ctx);
validateAgainstOntology
Validates individuals against an ontology's constraints, merged with those of the base ontology.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| request | Yes | AosvcValidationRequest | Pass an object whose is the individuals to validate, as a JSON string. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<AosvcValidationResult> - A promise with the validation result.
const result = await IafAOSvc.validateAgainstOntology('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {
dataJson: JSON.stringify([{ _classId: 'pump-cls', _name: 'Pump A' }])
}, ctx);
if (!result._conforms) console.log(result._violations);
validateSchema
Validates a schema bundle and diffs it against the current aggregate without changing anything.
| Parameter | Required | Type | Description |
|---|---|---|---|
| ontologyId | Yes | String | Pass the ontology's id. |
| bundle | Yes | AosvcSchemaBundle | Pass an object whose is the schema bundle to validate. |
| ctx | No | Ctx | Context, such as namespaces and authentication token information. |
| options | No | AosvcRequestOptions | Pass a JSON object with request headers in a property, such as . |
Promise<JSON> - A promise with the validation and diff result.
const schema = await IafAOSvc.getOntologySchema('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {}, ctx);
const result = await IafAOSvc.validateSchema('a1b2c3d4-e5f6-7890-abcd-ef1234567890', { snapshot: schema.snapshot }, ctx);