Configuration

Configuration file

Octory mainly uses this plist file to adapt its interface and its behavior. By editing it, you can deeply customize the application, like choosing its components to display, specify which apps should be monitored, and what MDM to use.

Note: All the groups marked as ℹ️ Optional are not required to launch Octory. However, when you specify an optional group, the keys marked as required have to be specified.




Admin (Dictionary)

Let you enter the admin mode This allows you to access actions in the Admin menu bar. Here are the actual features.

Dictionary key name: Admin

Key Type Explanation Is Required
IsAdminModeEnabled Boolean If set to true, the Admin menu item in the menu bar is accessible, and so are the shortcuts.
Note: Do not forget to set the key to false after you tried you configuration and before to install it on an end-user machine.
⚠️
IsMenuBarSemiTransient Boolean If set to true and using the MenuBar for the window OnScreen key, the menu bar window will stay visible unless you click in another screen or you right-click the menu bar icon. Useful for editing

Input (Dictionary)

ℹ️ Optional

Lets you configure the properties of the input variables files, where all the values entered by the user will be found. You can read Input components to get more info.

Note: As this group is optional, it can be omitted. In this case, the file path will be /Users/jdoe/Octory/Octory_inputs.json and the file format will be JSON. But if you use this group, you cannot omit the FileFormat key.

Dictionary key name: Input

Key Type Possible values/Examples Explanation Is Required
FileFormat String PLIST, JSON Lets you specify the file format you want to use to save the input variables ⚠️
FilePath String - Let you specify the path of the file where Octory will write in.
Note: Prefer absolute paths, and avoid special characters like ~. For the tilde, you should use the ${USER_NAME} placeholder which Octory will populate.
About the input file path

You need to specify the full path to the file, for example: /tmp/user_input.json or /Users/Shared/enrollment_inputs.plist. The extension of the file has to match the FileFormat key. Note that you may need to give the right to the end-user to write in some directories if necessary, for Octory to be able to save the file in those directories.


Font styles (Dictionary)

ℹ️ Optional

You can define here custom font configurations which will be available in any place where you can use font configurations. To use a font configuration defined here, you just need to add the key Style in the font configuration dictionary, and to give as value the name of the key. A font configuration can have a style and implement other properties, like setting the color. Note that if a font configuration uses a style but also specifies properties which exist in the style, the properties in the style will be overridden.

To use them in a font configuration elsewhere in the plist, simply set the key Style to the name of the style you want to use.

You can define default fonts that will be used in Octory by default if possible when no other font configuration is specified.

Dictionary key name: FontStyles

Key Type Explanation Is Required
DefaultPrimary Font configuration Used when displaying simple text
DefaultSecondary Font configuration Used when displaying text which is less important, like details
Example

We defined here two font styles: Title and Body:


    <dict>
      <key>Title</key>
      <dict>
        <key>SystemFontWeight</key>
        <string>Bold</string>
        <key>Size</key>
        <integer>30</integer>
      </dict>
        <key>Body</key>
        <dict>
            <key>SystemFontWeight</key>
            <string>Regular</string>
      </dict>
    </dict>
    

You can use a font style to define another font style. Do note that if you specify a style A for a font that is already used as a style B in the style A, Octory will ignore one of the style to avoid infinite loops.

Example:

    <dict>
        <key>Title</key>
        <dict>
            <key>SystemFontWeight</key>
            <string>Bold</string>
            <key>Size</key>
            <integer>30</integer>
            <key>Style</key>
            <string>Title2</string>
        </dict>
        <key>Title2</key>
        <dict>
            <key>Style</key>
            <string>Title</string>
            <key>Color</key>
            <dict>
                <key>Style</key>
                <string>Main</string>
        </dict>
    </dict>
    

Color styles (Dictionary)

ℹ️ Optional

You can define here custom colors which will be available in any place where you can use colors. To use a font configuration defined here, you just need to add the key Style in the font configuration dictionary, and to give as value the name of the key. A color can have a style and implement other properties, like setting the alpha. Note that if a color uses a style but also specify properties which exist in the style, the properties in the style will be overridden.

To use styles in a colors elsewhere in the plist, simply set the key Style to the name of the style you want to use.

You can define default colors that will be used in Octory by default if possible when no other color is specified.

Dictionary key name: ColorStyles

Key Type Explanation Is Required
DefaultBorder Color The default color to apply to containers and components borders
Example

We defined here two colors: Main and Secondary:


    <dict>
        <key>Main</key>
        <dict>
            <key>DarkMode</key>
            <string>#819ABE</string>
            <key>LightMode</key>
            <string>#ED682580</string>
        </dict>
        <key>Secondary</key>
        <dict>
            <key>DarkMode</key>
            <string>#000000</string>
            <key>LightMode</key>
            <string>#50607F</string>
        </dict>
    </dict>
    

You can use a color style to define another color style. Do note that if you specify a style A for a font that is already used as a style B in the style A, Octory will ignore one of the style to avoid infinite loops.


ℹ️ Optional

Lets you customize some properties relative to the navigation view. This view is at the bottom of the window and display the navigation buttons. The last slide will display a Quit button instead of the Next button, whose text will differ. This Quit button will make the app to terminate. It will be enabled only if all the application monitors specified in the monitors are installed. And it will allow to quit the app only if the current slide is valid.

Dictionary key name: Navigation

Key Type Explanation Is Required
IsHidden Boolean If set to true, the navigation view will be hidden (useful when displaying one slide in full screen for example). Default is false
PreviousButtonText String The text of the previous button (left)
NextButtonText String The text of the next button (right)
PreviousButtonTextColor Color The text color of the previous button (left)
NextButtonTextColor Color The text color of the previous button (right)
QuitButtonText String Let you customize the text of the Quit button which appears on the last slide, replacing the next button
InstallationIncompleteQuitText String The text displayed in an alert when the user clicks the Quit button despite all applications/packages are not installed.
UserCanQuitIfInstallationIsIncomplete Boolean If set to true, this key allows the user to quit the app with the Quit Button or the Quit shortcut even if all applications/packages are not installed. Default is false.
Note: If the user closes Octory window, the behavior you specified is ignored and the app is terminated with no conditions. To avoid that, checkout IsClosable key in Window

App Termination (Dictionary)

ℹ️ Optional

Groups all the keys to customize the app termination behavior.
Note
This group is optional. It can be omitted. In this case. the classic shortcut to quit the app will be enabled, and no script will be executed when the app terminates.

Dictionary key name: AppTermination

Key Type Explanation Is Required
QuitShortcutIsEnabled Boolean If set to true, the classic ⌘Q is enabled to let the user quit the app. Otherwise, the shortcut is ⌃⌘⌥Q ⚠️
IncompleteInstallationScriptPath String A path to a script to execute.
Note: When Octory terminates, the installation is complete if all the application monitors. If the installation is incomplete, the script specified at this path will be executed
⚠️
CompleteInstallationScriptPath String A path to a script to execute.
Note: When Octory terminates, the installation is complete if all the application monitors. If the installation is complete, the script specified at this path will be executed
⚠️


Note
The following commands in a script allow you to restart and shutdown the computer, while not requiring the root rights:

Thus, you can use these commands at the end of the scripts to be executed when the application terminates. This solution - rather than doing it in Octory internally - ensures that your scripts will be executed to the end, before the computer restart or shutdown. Simple scripts to restart and shutdown are included in the Octory download file.


General (Dictionary)

ℹ️ Optional

All the variables that can be used to populate strings. See the Variables section to know more about how to use them.

Dictionary key name: General

Key Type Explanation Is Required
Variables Dictionary Contains the variables to use in the rest of the configuration file

You can use other variables when defining one variable as long you respect those rules :

Examples

    <dict>
        <key>ResourcesPath</key>
        <string>Users/${USER_NAME}/Desktop/Octory</string>
        <key>ApplicationIconsPath</key>
        <string>${ResourcesPath}/ApplicationIcons</string>
    </dict>
    

To avoid: variables definition infinite loop


    <dict>
        <key>FIRST_VAR</key>
        <string>Hello ${SECOND_VAR}</string>
        <key>SECOND_VAR</key>
        <string>How are you ${FIRST_VAR}</string>
    </dict>
    

Window (Dictionary)

Groups all the keys associated to the window configuration

Dictionary key name: Window

Key Type Possible keys Explanation Is Required
Title String - The title of the window in the title bar. If this key is omitted, no title is displayed in the title bar
IsTitleBarHidden Boolean If set to true, the title bar will be hidden. Default is false
MinimumSize Size - The minimum size at which the window can be resized. Default is 600 x 800
MaximumSize Size - The maximum size at which the window can be resized. Default is 768 x 1280
MenuBarSize Size - The size of the window when using the MenuBar value for OnScreen key. Default is 600 x 800
IsClosable Boolean - true: the window can be closed by the user. Default is true
IsMovable Boolean - true: the window can be moved/dragged by the user. Default is true
IsResizable Boolean - true: the window wan be resized by the user (accordingly with the specified sizes). Default is true
ScreenIndex Int - Let you specify the index of the screen where the window should appear. If not specified, it's the current screen that is chosen
Position Window position - Let you specify where the window should appear
OnScreen String Simple, BlurredBackground, FullScreen, MenuBar Specify how the Octory window should appear on screen.
Note: When BlurredBackground or FullScreen are specified, the other keys in the Window dictionary are ignored, except for the MaximumSize, which is used to configure the window with BlurredBackground. For MenuBar option, see the MenuBarSlide
⚠️
MenuBarIconPath String - Let you specify the icon to use for the menu bar icon. Provide an icon with a height of 20 pixels.
PRO

Window position (Dictionary)

Let you specify a window position on the screen

Key Type Possible keys Explanation Is Required
Horizontal String Left, Center, Right Position the window horizontally ⚠️
Vertical String Top, Center, Bottom Position the window vertically ⚠️
Padding Number - Add padding to the side of the window. Default is 20

Command line

You can override the value for the OnScreen key in the plist by launching the app with an argument: -w or --window and the name of the OnScreen value you want. For example


    /path/to/Octory.app/Contents/MacOS/Octory -w MenuBar
    

or


    open /path/to/Octory.app --args -w MenuBar
    

will set the app window as MenuBar no matter what is in the plist.


Slides (Array)

Array key name: Slides

Contains all the slides that will be displayed to the user. See the Slides section to learn how to use slides. You can also checkout the preset Plist files.


Specify here the slide you want to use when displaying the application with the MenuBar value for the OnScreen key.


Monitoring (Dictionary)

ℹ️ Optional

You choose in this section how to monitor applications and packages installation, or file presence. The supported installer currently are Jamf, AirWatch (Wokspace ONE) and Munki, and applications installed with VPP (or from the App Store more generally).

Note To use Munki monitoring, set the Monitor Installer key as AirWatch and specify the paths to the corresponding Munki log files in the keys AirWatchInstallLogPath and AirWatchManagedSoftwareUpdateLogPath

Dictionary key name: Monitoring

Key Type Explanation Is Required
JamfLogPath String Lets you override the path to the Jamf log file path. Default is /var/log/jamf.log
AirWatchInstallLogPath String Lets you override the path to the AirWatch Install log file path. Default is /Library/Application Support/AirWatch/Data/Munki/Managed Installs/Logs/Install.log
AirWatchManagedSoftwareUpdateLogPath Number Lets you override the path to the AirWatch ManagedSoftwareUpdate log file path. Default is /Library/Application Support/AirWatch/Data/Munki/Managed Installs/Logs/Install.log
Monitors Monitors Array Specify here the files, applications or packages installations you want Octory to monitor. See the Monitoring section for more info. You can also checkout the preset Plist files . ⚠️
InstallationCompleteSoundNameOrFilePath String Play a sound when all the monitors are installed. Can be the name of a system sound or the path to a sound file (MP3, MP4, WAV). You can find the system sounds list at /System/Library/Sounds/.

Note To use Munki monitoring, set the Installer key as AirWatch and specify the paths to the corresponding Munki log files in the keys ``


Conditions (Dictionary)

PRO

Write here the conditions you want to reuse in other conditions in the plist. You can use user inputs variables or dynamic placeholders to specify those conditions.

Dictionary key name: Conditions

Examples

With UserRole as an input variable asked to the user, and the DEVICE_NAME dynamic placeholder. The ~= operand tests if the right operand is a prefix of the left operand.


    <dict>
        <key>UserIsConsultant</key>
        <string>UserRole == "Consultant"</string>
        <key>ComputerIsLaptop</key>
        <string>DEVICE_NAME ~= "LMAC"</string>
        <key>ComputerIsDesktop</key>
        <string>DEVICE_NAME ~= "DMAC"</string>
    </dict>
    

You can then use the conditions defined here in a Text Component for example, without writing again all the condition:


    <dict>
        <key>Type</key>
        <string>Text</string>
        <key>Condition</key>
        <string>UserIsConsultant</string>
        <key>Text</key>
        <string>You are a consultant!</string>
    </dict>
    

The component will only appear when the condition is evaluated as true.


API Requests (Dictionary)

PRO

Dictionary key name: APIRequests

You can define here all the api requests you want Octory to make with a SendRequest action

You can also define some useful key that will be needed for the requests:

Key Type Possible values Explanation Is Required
JamfBaseURL String - The base URL of your Jamf API. Example: https://mycompany.jamfcloud.com/JSSResource/
JamfProBaseURL String - The base URL of your Jamf Pro API. Example: https://mycompany.jamfcloud.com/uapi/
AirwatchBaseURL String - The base URL of your Airwatch (Workspace ONE) API. Example: https://vn569.awmdm.com/API/
DefaultMDMApi String Jamf, JamfPro, AirWatch When defining a api request, you can specify the MDM API to target to Octory. This way, Octory will process the request accordingly to the MDM API requirements. You can specify here a default MDM API to use when it is omitted
Models api request Array The API Requests you want to reuse in Actions ⚠️

Examples


    <dict>
        <key>JamfBaseURL</key>
        <string>https://mycompany.jamfcloud.com/JSSResource/</string>
        <key>DefaultMDMApi</key>
        <string>Jamf</string>
        <key>Models</key>
        <dict>
            <key>ComputerName</key>
            <dict>
                <key>Endpoint</key>
                <string>computers/id/20</string>
                <key>VariableReadingPaths</key>
                <dict>
                    <key>ComputerName</key>
                    <string>computer->general->name</string>
                </dict>
            </dict>
            <key>UserName</key>
            <dict>
                <key>Endpoint</key>
                <string>accounts</string>
                <key>VariableReadingPaths</key>
                <dict>
                    <key>UserName</key>
                    <string>accounts->users->[0]->name</string>
                </dict>
            </dict>
            <key>TerminationSuccess</key>
            <dict>
                <key>Endpoint</key>
                <string>computers/id/20</string>
                <key>Method</key>
                <string>PUT</string>
                <key>Body</key>
                <dict>
                    <key>computer</key>
                    <dict>
                        <key>extension_attributes</key>
                        <dict>
                            <key>extension_attribute</key>
                            <dict>
                                <key>id</key>
                                <string>7</string>
                                <key>value</key>
                                <string>${INSTALLATION_COMPLETE}</string>
                            </dict>
                        </dict>
                    </dict>
                </dict>
            </dict>
        </dict>
    </dict>
    </plist>
    
    

Action Sets (Array)

PRO

Dictionary key name: ActionSets

Specify here the action sets you want Octory to trigger.

Examples


    <array>
        <dict>
            <key>Type</key>
            <string>Chained</string>
            <key>Triggers</key>
            <array>
                <string>Launch</string>
            </array>
            <key>Actions</key>
            <array>
                <dict>
                    <key>Type</key>
                    <string>SendRequest</string>
                    <key>Request</key>
            <string>ComputerName</string>
                </dict>
                <dict>
                    <key>Type</key>
                    <string>SendRequest</string>
                    <key>Request</key>
            <string>UserName</string>
                </dict>
            </array>
        </dict>
        <dict>
            <key>Type</key>
            <string>Parallel</string>
            <key>Triggers</key>
            <array>
                <string>Termination</string>
            </array>
            <key>Actions</key>
            <array>
                <dict>
                    <key>Type</key>
                    <string>SendRequest</string>
                    <key>Request</key>
            <string>TerminationSuccess</string>
                </dict>
            </array>
        </dict>
        <dict>
            <key>Type</key>
            <string>Chained</string>
            <key>Triggers</key>
            <array>
                <string>Update(ComputerName)</string>
            </array>
        <key>Condition</key>
        <string>ComputerName != ""</string>
            <key>Actions</key>
            <array>
                <dict>
                    <key>Type</key>
                    <string>ExecuteScript</string>
            <key>Script</key>
            <string>WriteComputerName</string>
                </dict>
            </array>
        </dict>
    </array>