API: Ontology edits

In addition to writing Functions that return derived values based on the Ontology, you can also write Functions that edit the properties and links between objects in the Ontology. 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.

To actually be used in an operational context, Ontology Edit Functions must be configured as an Action, known 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.

Declaring an Edit Function

Functions that edit the Ontology must:

• Be decorated with the @OntologyEditFunction() decorator imported from @foundry/functions-api
• Be decorated with the @Edits([object type]) decorator imported from @foundry/functions-api to specify the object types that will be edited
• Have an explicit void return type

Updating properties

You can edit property values by simply reassigning the property value for an object. For example:

Copied!
1
employee.lastName = newName;

If you access the lastName property value later in the same Function execution, the new value that you just set will be returned.

Array properties on objects are generated with the ReadOnlyArray type. To modify an array, create a copy of it, modify the copy, then update the property:

Copied!
1
2
3
4
5
6
// Copy to a new array
let arrayCopy = [...myObject.myArrayProperty];
// Now you can modify the copied array
arrayCopy.push(newItem);
// Then overwrite the property value
myObject.myArrayProperty = arrayCopy;

Note that you cannot update the primary key property value of an existing object.

Updating links

The SingleLink and MultiLink interfaces have various methods you can use to update links:

Copied!
1
2
3
4
5
6
7
8
9
10
11
// Set an Employee's supervisor
employee.supervisor.set(newSupervisor);

// Clear an Employee's supervisor
employee.supervisor.clear();

// Add a new report to the given employee
employee.reports.add(newReport);

// Remove an old report associated with the given employee
employee.reports.remove(oldReport);

As with updating properties, accessing links after they have been updated reflects the updates you have made.

Creating objects

You can create new objects using the Objects.create() interface available from @foundry/ontology-api. When creating a new object, you have to specify a value for its primary key.

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).

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

export class TicketActionFunctions {
    @Edits(Employee, Tickets)
    @OntologyEditFunction()
    public createNewTicketAndAssignToEmployee(employee: Employee, ticketId: Integer): void {
        const newTicket = Objects.create().ticket(ticketId);

        newTicket.dueDate = LocalDate.now().plusDays(7);

        employee.assignedTickets.add(newTicket);
    }
}

Deleting objects

You can delete an object by calling the .delete() method.

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

Copied!
1
2
const tickets = employee.tickets.all();
tickets.forEach(ticket => ticket.delete());