The Checklist API

Introduction

The SDK offers an API for implementing electronic checklists that are embedded within an avionics system. The API is designed to be generic enough to be useful across a wide range of use cases. It can also be extended to suit the requirements of a particular avionics system.

The following sections describe

Checklist Structure

The Checklist API implements checklists with a five-tiered structure:

Checklist set. Each checklist set contains zero or more checklist groups.
Checklist group. This represents a group of related checklists. Each checklist group contains zero or more checklist lists.
Checklist list. This represents what is traditionally thought of as a single "checklist". Each checklist list contains zero or more checklist items and zero or more checklist branches.
Checklist branch. This represents a sub-list within a checklist list. Each checklist branch contains zero or more checklist items.
Checklist item. This represents a single line item within a checklist. Items can be members of a branch or of the base checklist (i.e. not in a branch).

Checklist Items

A checklist item represents a single line item within a checklist. There are six types of checklist items:

An actionable item is an item that has a completion state. At any time, an actionable item is either completed or not completed.

A branch item is an item whose completion state can depend on the completion state of zero or more linked branches within the same checklist list. When determining the completion state of a branch item from its linked branches, each linked branch is assigned one of three logic types (ChecklistBranchItemLogicType): None, Sufficient, or Necessary. The branch item is considered completed when at least one linked branch with the Sufficient logic type is completed or all linked branches with the Necessary logic type are completed. Linked branches with the None logic type do not affect the branch item's completion state. A branch item also has a override state. When a branch item is overridden, it is always considered completed regardless of the completion state of its linked branches.

A link item is an item that links to a checklist list or checklist branch. It has no completion state.

A note item is an item that displays informational text. It has no completion state.

A title item is an item that displays a section title or heading. It has no completion state.

A spacer item is an item that is used to add spacing between other items when a checklist is displayed. It has no completion state.

info

The ChecklistItemType enum is used to reference checklist item types programmatically.

Checklist Definitions

Within the Checklist API, checklist definitions are used to describe all the components of a set of checklists.

Set Definition

A checklist set definition (ChecklistSetDef) defines an ordered array of checklist groups contained within the set. It can also optionally define arbitrary metadata associated with the set.

Group Definition

A checklist group definition (ChecklistGroupDef) defines the group's name and an ordered array of checklist lists contained within the group. It can also optionally define arbitrary metadata associated with the group.

List Definition

A checklist list definition (ChecklistListDef) defines the list's name and an ordered array of checklist items contained within the list. It can also optionally define a unique ID (used to create links to the list) and arbitrary metadata associated with the list.

info

The unique ID assigned to a list, if one exists, must be unique across all lists and all branches in the entire checklist set.

Branch Definition

A checklist branch definition (ChecklistBranchDef) defines the branch's unique ID (used to create links to the branch), name and an ordered array of checklist items contained within the branch. It can also optionally define arbitrary metadata associated with the branch.

info

The unique ID assigned to a branch must be unique across all branches and all lists in the entire checklist set.

Item Definition

Checklist item definitions at a minimum must satisfy the types defined in the BaseChecklistItemTypeDefMap type alias. Definitions for individual item types can define additional properties as long as the resulting definitions still satisfy the types in BaseChecklistItemTypeDefMap.

The API provides a set of default checklist item definitions for each item type. These extend the types defined in BaseChecklistItemTypeDefMap with some properties that are commonly useful.

Item Type	Definition	Additional properties
Actionable	`ChecklistActionableItemDef`	Defines a label text and an action text for the item.
Branch	`ChecklistBranchItemDef`	Defines text for the item.
Link	`ChecklistLinkItemDef`	Defines optional text for the item.
Note	`ChecklistNoteItemDef`	Defines text for the item.
Title	`ChecklistTitleItemDef`	Defines text for the item.
Spacer	`ChecklistSpacerItemDef`	Defines an optional height for the item.

The ChecklistItemTypeDefMap type alias can be used to map from checklist item types to their associated default checklist item definitions.

For more information on how to extend the API to support custom item definitions, please refer to this page.

Declaring Checklist Definitions

Checklist definitions can be declared programmatically:

import { ChecklistItemType, ChecklistItemTypeDefMap, ChecklistSetDef } from '@microsoft/msfs-sdk';

const checklistDef: ChecklistSetDef<ChecklistItemTypeDefMap, void, void, void> = {
  groups: [
    {
      name: 'Normal Procedures',
      lists: [
        {
          name: 'Before Engine Start',
          items: [
            {
              type: ChecklistItemType.Actionable,
              labelText: '1. Preflight inspection',
              actionText: 'Completed'
            },
            {
              type: ChecklistItemType.Actionable,
              labelText: '2. Parking brake',
              actionText: 'On'
            },
            {
              type: ChecklistItemType.Actionable,
              labelText: '3. Battery switch',
              actionText: 'On'
            },
            {
              type: ChecklistItemType.Actionable,
              labelText: '4. Alternator switch',
              actionText: 'On'
            }
          ],
          metadata: undefined
        }
      ],
      metadata: undefined
    }
  ],
  metadata: undefined
};

They can also be parsed from JSON:

{
  "groups": [
    {
      "name": "Normal Procedures",
      "lists": [
        {
          "name": "Before Engine Start",
          "items": [
            {
              "type": "Actionable",
              "labelText": "1. Preflight inspection",
              "actionText": "Completed"
            },
            {
              "type": "Actionable",
              "labelText": "2. Parking brake",
              "actionText": "On"
            },
            {
              "type": "Actionable",
              "labelText": "3. Battery switch",
              "actionText": "On"
            },
            {
              "type": "Actionable",
              "labelText": "4. Alternator switch",
              "actionText": "On"
            }
          ]
        }
      ]
    }
  ]
}

Finally, they can also be parsed from DOM (such as from XML files) using ChecklistDOMParser. For more information on how to use ChecklistDOMParser, please refer to this page.

Checklist State

The Checklist API supports managing checklist state. Checklist state is managed independently for each checklist set. The state of a checklist set consists of its structure and the completion state of the set's lists and items. Each actionable checklist item has a completion state - it is either completed or not. The completion state of a list depends on the completion state of the actionable items contained within it - a list is considered not completed if and only if at least one actionable item is not completed. This means that a list with no actionable items is always considered completed.

Checklist state is encapsulated by the following:

ChecklistSet: the state of a checklist set.
ChecklistGroup: the state of a checklist group.
ChecklistList: the state of a checklist list.
ChecklistBranch: the state of a checklist branch.
ChecklistItem: the state of a checklist item. The state includes references to the item's type and definition. The state of an actionable item includes its completion state. The state of a branch item includes its completion and override states.

Controlling State

Checklist state can be controlled using ChecklistManager and ChecklistController. ChecklistManager maintains the state for a single checklist set. ChecklistController is used to send commands to ChecklistManager to change state. The completion state of checklist items and lists can be controlled in this manner.

To use ChecklistManager and ChecklistController, an index must first be assigned to each checklist set whose state is to be controlled. The index must be a positive integer and must be unique for each set. The event bus is also required for both classes to function.

When a ChecklistManager is created, it is initialized as asleep. While the manager is asleep, it will not respond to any commands. The manager must be awakened using wake() in order for it to respond to commands. After a manager is awakened, it can be put to sleep again using sleep().

import { ChecklistManager, EventBus } from '@microsoft/msfs-sdk';

const bus = new EventBus();

// Create a manager for the checklist set defined by checklistSetDef and assign it an index of 1.
const manager = new ChecklistManager(1, bus, checklistSetDef);

// Wake the manager up. It is now ready to respond to commands to change the checklist state.
manager.wake();

warning

Only one instance of ChecklistManager should be created for each checklist set across the entire airplane. Do not create multiple instances of ChecklistManager for the same checklist set on different VCockpit instruments.

Once a ChecklistManager has been created, checklist state can be controlled by directly calling methods on the manager.

manager.wake();

// Toggles the completion state of the first item in the first list in the first group.
manager.toggle(0, 0, -1, 0);

// Resets the completion state of all items in the set to not complete.
manager.resetAll();

ChecklistController can be used to remotely control checklist state without direct access to a ChecklistManager instance. ChecklistController can also be used when the controller is on a different VCockpit instrument from the manager. The controller offers an interface similar to that used to control state directly from the manager.

import { ChecklistController, EventBus } from '@microsoft/msfs-sdk';

const bus = new EventBus();

// Create a controller for the checklist set assigned to index 1.
const controller = new ChecklistController(1, bus);

// Toggles the completion state of the first item in the first list in the first group.
controller.toggle(0, 0, -1, 0);

// Resets the completion state of all items in the set to not complete.
controller.resetAll();

note

Checklist state can also be remotely controlled by publishing the event bus topics defined in ChecklistControlEvents. However, it is recommended to use ChecklistController instead, because it abstracts away much of the boilerplate involved with publishing the event bus topics.

State Provider

ChecklistStateProvider defines an interface for a provider of checklist state for a single checklist set. A default implementation of this interface is also available as DefaultChecklistStateProvider.

To use DefaultChecklistStateProvider, create an instance of it using the definition for a checklist set and the index assigned to the set's state. Then once the provider is initialized, the provided state object will automatically update when the set's state changes.

import { DefaultChecklistStateProvider } from '@microsoft/msfs-sdk';

// Create a provider of state for the checklist set defined by checklistSetDef, assigned an index of 1.
const provider = new DefaultChecklistStateProvider(1, bus, checklistSetDef);

// Initialize the provider.
provider.init();

// Subscribe to the completion state of the first list in the first group.
const list = provider.state.groups[0].lists[0];
list.isCompleted.sub(isCompleted => {
  console.log(`${list.name} is ${isCompleted ? '' : 'not '}completed!`);
}, true);

Introduction​

Checklist Structure​

Checklist Items​

Checklist Definitions​

Set Definition​

Group Definition​

List Definition​

Branch Definition​

Item Definition​

Declaring Checklist Definitions​

Checklist State​

Controlling State​

State Provider​

Introduction

Checklist Structure

Checklist Items

Checklist Definitions

Set Definition

Group Definition

List Definition

Branch Definition

Item Definition

Declaring Checklist Definitions

Checklist State

Controlling State

State Provider