Ontology edits

In addition to writing functions that read data from the Ontology, you can also write functions that create objects and edit the properties and links between objects. This page documents the object edit APIs available to you in functions. For more details about how edit functions work, refer to the overview page.

For the edits created in a function to actually be applied, Ontology edit functions must be configured as a function-backed Action. Configuring an Action in this way allows you to provide additional metadata, configure permissions, and access the Action in various operational interfaces. As noted in the documentation, running an edit function outside of an Action will not actually modify any object data.

Define an edit function

Functions that edit the Ontology must explicitly declare the entities that will be edited using the Edits type exported from the @osdk/functions package. The following example declares a new type representing edits to the Employee and Ticket object types, as well as a link type between Employee and Ticket. Edits to multiple entities need to be joined with the | operator.

Copied!
1
2
3
4
import { Employee, Ticket } from "@ontology/sdk";
import { Edits } from "@osdk/functions";

type OntologyEdit = Edits.Object<Employee> | Edits.Object<Ticket> | Edits.Link<Employee, "assignedTickets">;

You must then declare that the function returns an array of edits of the new type.

Copied!
1
2
3
export default function createNewTicketAndAssignToEmployee(): OntologyEdit[] {
    // ...
}

Construct an Ontology edits batch

To perform Ontology edits in a TypeScript v2 function, first construct an Ontology edits batch using the createEditBatch function exported from @osdk/functions, passing the previously declared type as a type argument:

Copied!
1
2
3
4
5
6
7
8
9
10
11
import { Employee, Ticket } from "@ontology/sdk";
import { Client } from "@osdk/client";
import { createEditBatch, Edits } from "@osdk/functions";

type OntologyEdit = Edits.Object<Employee> | Edits.Object<Ticket> | Edits.Link<Employee, "assignedTickets">;

export default function createNewTicketAndAssignToEmployee(client: Client): OntologyEdit[] {

    const batch = createEditBatch<OntologyEdit>(client);
    // ...
}

This batch is used to keep track of all edits made in a function.

Update properties

Use the update method available on the created batch to modify one or more object properties:

Copied!
1
batch.update(employee, { lastName: newName });

If you have not loaded the employee object instance into memory, you can also update it by referencing the object's API name and primary key:

Copied!
1
batch.update({ $apiName: "Employee", $primaryKey: 23 }, { lastName: newName });

Subsequent access to the lastName property value of employee later in the same function execution will not reflect the changes that you make when calling update on the edit batch.

Sometimes, it is useful to copy all of the property values of one instance of an object type to another instance. The following example assigns the property values of employee2 to employee1:

Copied!
1
batch.update(employee1, employee2);

Note that the primary key property value of an existing object cannot be updated.

Update links

Use the link and unlink methods available on the created batch to add or remove links between objects.

Copied!
1
2
3
4
5
// Assign a ticket to an employee.
batch.link(employee, "assignedTickets", ticket);

// Unassign a ticket from an employee.
batch.unlink(employee, "supervisor", ticket);

As with updating properties, you can also reference either side of the link with an API name and primary key if you have not loaded a concrete instance of the object type previously.

Copied!
1
2
3
4
5
// Assign a ticket to an employee.
batch.link({ $apiName: "Employee", $primaryKey: 23 }, "assignedTickets", { $apiName: "Ticket", $primaryKey: 12 });

// Unassign a ticket from an employee.
batch.unlink({ $apiName: "Employee", $primaryKey: 23 }, "assignedTickets", { $apiName: "Ticket", $primaryKey: 12 });

Create objects

You can create new objects using the create method on the edit batch. When creating a new object, you must specify a value for its primary key and can optionally initialize any other properties.

In this example, we create a new Ticket object with the given ID, set its dueDate property, and assign it to the given Employee by modifying the assignedTickets link. To simplify the calculation of the new value of dueDate, we use the luxon library.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import { Employee, Ticket } from "@ontology/sdk";
import { Client, Osdk } from "@osdk/client";
import { createEditBatch, Edits, Integer } from "@osdk/functions";
import { DateTime } from "luxon";

type OntologyEdit = Edits.Object<Employee> | Edits.Object<Ticket> | Edits.Link<Employee, "assignedTickets">;

export default function createNewTicketAndAssignToEmployee(
    client: Client,
    employee: Osdk.Instance<Employee>,
    ticketId: Integer,
): OntologyEdit[] {
    const batch = createEditBatch<OntologyEdit>(client);

    batch.create(Ticket, { 
        ticketId, 
        dueDate: DateTime.now().plus({ days: 7 }).toFormat('yyyy-MM-dd'),
    });

    // The new ticket does not exist in the Ontology as a concrete instance, but we can link it
    // by referencing its API name and primary key.
    batch.link(employee, "assignedTickets", { $apiName: "Ticket", $primaryKey: ticketId });

    return batch.getEdits();
}

Delete objects

You can delete an object by calling the delete method on the edit batch.

In this example, we delete all the tickets assigned to the given employee:

Copied!
1
2
3
for await (const ticket of employee.$link.assignedTickets.asyncIter()) {
    batch.delete(ticket);
}

Objects may also be deleted using a primary key instead of an instance:

Copied!
1
batch.delete({ $apiName: "Ticket", $primaryKey: 12 });