The “Big Picture”

Most scriptable applications are designed with a hierarchical organization where the scriptable elements are contained within other elements. For example, the OmniPlan application edits documents that contain projects that contain scenarios that contain tasks and resources.

In the OmniPlan scripting implementation:

The illustration below shows the hierarchical nature and relationships of the scriptable OmniPlan objects (both on macOS and iOS).

The OmniPlan Hierarchy

Application

In Omni Automation scripts, the application object is represented by the abbreviation: “app”. The application object is addressed by scripts to determine the current system platform, pressed modifier keys, and for opening documents. (see Application section)

Documents

Although documents are the sole and primary element of the OmniPlan application, the current document is not referenced using the app object, but is referenced instead as a top-level object:

For the sake of security, documents are not allowed to be accessed by scripts run in the consoles of other documents, so the application object will not return references to other documents.

Document Windows

In the OmniPlan scripting implementation, windows belong to documents, and their references include their parent implied document object:

Document > Window

And the current window is always the first item in the list (array) of open windows:

Document Selection

A document’s selection object belongs to the window class, which in turn, belongs to the parent implied document. The Selection class includes three properties whose values are a single item reference (selection, project) or arrays of references (resources, tasks) to the objects selected in the window: project, resources, and tasks

Document > Window > Selection

document.windows[0].selection //--> [object Selection] document.windows[0].selection.project //--> [object Project] document.windows[0].selection.resources //--> [[object Resource]] document.windows[0].selection.tasks //--> [[object Task],[object Task],[object Task]]

For example, here’s a simple script for getting the titles of the selected tasks:

selectedTasks = document.windows[0].selection.tasks taskTitles = selectedTasks.map((task)=>{return task.title})

Project

A Project represents the contents of an OmniPlan document, and when writing scripts that target the content of the current document, the project becomes the topmost object, providing properties whose values are references to the scenarios (actual and baselines) the project contains.

Scenarios

A Scenario represents a set of tasks and resources and associated schedules. The actuals for a project are one scenario, and saved baselines are the others.

The project property “actual” references the current scenario, which has properties of its own, such as hasFixedEndDate:

The project property baselineNames provides an array of the names of any other scenarios, and references to those scenarios can be derived using the baselineNamed(…) scripting method:

Also note that an instance of the Scenario class contains two properties representing the origin items of their Task and Resource elements. These “root” items are used when creating and managing additional instances of their classes.

Resources

Instances of the Resources class represent the people, groups, and physical materials and equipment used by the project. A Resource is an element of a Scenario and is created and added to a scenario by using the addMember() method of the Resource class on the root resource object of the scenario.

var resc = actual.rootResource.addMember() resc.type = ResourceType.staff resc.name = "Sala Mander" resc.email = "salamander@acmeprojects.com"
omniplan://localhost/omnijs-run?script=try%7Bvar%20resc%20%3D%20actual%2ErootResource%2EaddMember%28%29%0Aresc%2Etype%20%3D%20ResourceType%2Estaff%0Aresc%2Ename%20%3D%20%22Sala%20Mander%22%0Aresc%2Eemail%20%3D%20%22salamander%40acmeprojects%2Ecom%22%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D
actual.resource("Target Resource Title")

The members property of the Resource class when used with the root resource object, will return an array of references to the top-level resources for the scenario, as in this example script for getting the titles of a scenario’s top-level resources:

resourceNames = actual.rootResource.members.map((rsc)=>{return rsc.name})

Creating a reference to an instance of the Resource class can be done using the resourceNamed() method of the parent instance of the Scenario class.

Tasks

A Task is anything that needs to get done in order for the project to move toward completion. Each task has attributes such as start and end dates, a completion percentage, and resource assignments.

A Task is an element of a Scenario and is created and added to a scenario by using the addSubtask() method of the Task class on the root task object of the scenario.

newTask = actual.rootTask.addSubtask() newTask.title = "NEW TASK"
omniplan://localhost/omnijs-run?script=try%7BnewTask%20%3D%20actual%2ErootTask%2EaddSubtask%28%29%0AnewTask%2Etitle%20%3D%20%22NEW%20TASK%22%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D

The descendents() method of the Task class when used with the root task object, will return an array of references to the tasks in the entire tree of the scenario, as in this example script for getting all the task titles of a scenario:

taskTitles = actual.rootTask.descendents().map((task)=>{return task.title})

The property subtasks has a value that is an array of references to the subtasks of a specified task.

Creating a reference to an instance of the Task class can be done using the taskNamed() method of the parent instance of the Scenario class.

UNDER CONSTRUCTION

This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.

DISCLAIMER