Ontology edits

An Ontology edit is the act of creating, modifying, or deleting an object. Functions support returning Ontology edits for use in a function-backed action.

• TypeScript v1 functions are authored using the @OntologyEditFunction decorator, which provides special semantics to simplify your code. TypeScript v1 functions also use the @Edits decorator to provide actions with provenance information, which the actions may use to enforce permissions. You can write unit tests for TypeScript v1 Ontology edit functions using the APIs available for verifying Ontology edits.
• TypeScript v2 functions are authored using the createEditBatch function exported from the @osdk/functions package. These functions rely on the Edits type to provide actions with provenance information.
• Python functions are authored by creating an edits container using the FoundryClient exported from the Ontology SDK. These functions rely on the edits parameter of the @function decorator to provide actions with provenance information.

The rest of this document describes how Ontology edit functions work behind the scenes to provide you with a better understanding of the underlying infrastructure.

When edits are applied

A common misunderstanding about Ontology edit functions is whether or not running them will update objects in the Ontology. When you run an Ontology Edit function in the functions helper in Authoring, edits are not applied to the actual objects. The only way to update objects using a function is by configuring an Action to use the function as described in the documentation for function-backed Actions.

This means that you can freely run Ontology edit functions in the functions helper to validate results on various inputs, without concern that the objects themselves will be updated.

Caveat: Edits and object search

Changes to objects and links are propagated to the object set APIs after your function has finished executing. This means that Objects.search() APIs will use the old objects, properties, and links. As a result, search, filtering, search arounds, and aggregations may not reflect the edits to the Ontology, including creation and deletion. Your function will need to handle this case manually.

For the following example, assume there is an Employee with ID 1.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { OntologyEditFunction } from "@foundry/functions-api";
import { Employee, Objects } from "@foundry/ontology-api";

export class CaveatEditFunctions {
    @Edits(Employee)
    @OntologyEditFunction()
    public async editAndSearch(): Promise<void> {
        const employeeOne = Objects.search().employee().filter(e => e.id.exactMatch(1)).all()[0];
        employeeOne.name = "Bob";

        const count = await Objects.search().employee().filter(e => e.name.exactMatch("Bob").count() ?? -1;
        console.log(count);
        // Expected: 1, Actual: 0
    }
}