Getting started with Octory

What you will learn in this tutorial

Launching the application with a preset

Once you downloaded the presets folder and unzipped it, create a directory named Octory at /Library/Application Support. Then copy or move the application into this folder, as well as the Presets folder. Your final folder should look like this (small tips: you can right click on the top folder to see its parent folders).

Now it is time to try out some presets! Launch the and move to the folder:

cd /Library/Application\ Support/Octory/

You can ask the application to start with a specific configuration file. For security reasons, only admin users should have the write permission on those files. Learn more.
To be compliant while you are editing the file, you can change the permissions as below - assuming you have admin privileges.

chown "`whoami`":admin -R Presets
find Presets/ -type d -exec chmod 777 {} +
find Presets/ -type f -exec chmod 644 {} +

We will start with the Form preset. To start the application with a specific configuration file, you can use the option -c or --configuration followed by the path to the configuration file. As mentioned above, the application will look for this file only in two directories. To pass this option to the application, you can either use the open command with the --args option:

open --args -c Presets/Form/Octory.plist

Or launch the application executable at / -c Presets/Form/Octory.plist 

In this tutorial, we will only use the open command. Go on an run the command mentioned above:

open --args -c Presets/Form/Octory.plist

The application window should appear and looks like this:

Almost all the window behaviours are customisable. We will see how to change this. For now, it appears in the top right corner, is not movable, has no title bar nor a navigation view.

It was pretty easy, isn’t it? You can try the other presets the same way. If you take a look in their respective folders, you can see they contain a small description, as well as screenshots of the application window. Go on and try them out! I’ll wait before explaining how to customise the application window πŸ˜‰. To test the School preset, you would have to simply run:

open --args -c Presets/School/Octory.plist

When launching the application with the presets "Webview_blurred_background" or "Webview_fullscreen" you will not be able to terminate the application because of the monitors installation which might not be complete. To quit the app, enter the shortcut βŒ₯⌘M to simulate the completion of the installation thanks to the Admin menu which is On in those presets. You can then use ⌘Q to exit.

Customise application window

It is now time for us to customise the form preset. We will be playing with the window option.

You might want to copy somewhere the presets folder, as we will modify it.

If you open the file Presets/Form/Octory.plist, you can see it has several sections: FontStyles, ColorStyles, Admin…

The plist software editor is PLIST Editor. You are free to use another one. This tutorial will only contain screenshots of PLIST Editor and Atom.
You might want to use the folding option of you text editor when using a classic one. You can find this option in Atom under Edit β†’ Folding.

Here with PLIST Editor
Here with PLIST Editor
Here with Atom
Here with Atom

We will only modify the Window and Slides section. To get more information about the other sections, please refer to the documentation.

If you develop the Window section, it will show several attributes.

The MinimumSize and MaximumSize keys are mainly used in coordination with the OnScreen key. They let you specify the sizes the window should adopt. For example, we are here using the value Simple for the OnScreen key, which means that the window is displayed as a classic macOS window. By changing the values Height and Width inside the sizes, you can set the limits when resizing the window. To see that in action, we will set the key IsTitleBarHidden to False. This key prevent many interactions with the window, like its resizable behaviour.

If you restart the application now, you should see a title bar and be able to resize the window, as well as move it.
Lets make the window have a minimum size of 640 x 1024 and a maximum size of 900 x 1440:

Now restart the app. Its initial size has changed, as it uses by default the minimum size. Now, let’s prevent the window to be resized, while still keeping the title bar. This could be useful when you want to display relative information about what you want the application to achieve. To do so, simply add the boolean key IsResizable to the Window section, with a value set to False.

Restart the app. It should prevent you from resizing the window now. Thus, to make sure the window has one size only, make the minimum size equal to the maximum size. This way, when you restart the app, you ensure that it has the size you want.

Ok, so now the app is not resizable, great! But it does not seem really appealing when the window appears on the top right now. On a MacBook, we should rather try to make it appear on the center of the screen. To do so, develop the Position dictionary key in the Window section. You should see it has a Vertical and Horizontal keys. To center the window, simply write Center for both keys value.

Restart the app. The window should now appears on the center of the screen. But you are still able to move it, right? If you want to disable this behaviour, simply add the boolean key IsMovable with a False value to the Window section, like we did for the IsResizable key.

Last but not least, if you want to add custom title to the window title bar, add the string key Title.

And here we are!

Export the user inputs

Until now, we have been playing with the window, but it could be even more useful if we are able to retrieve the user inputs. It is a form preset after all!

We will see how to save the user inputs into a file. Then we will see how to send those inputs to your MDM with Octory Pro.

You can save the user inputs into a Plist or a Json file. When you have an input component in a the configuration file, the application will automatically save its value inside a file. This event will be triggered when the application is terminated, when the user clicks the Next navigation button, or when adding a SaveInputs action to a button. For this tutorial, we will add a Quit button, which will make the application be terminated, saving the user inputs to a file in the process.

To do so, develop the Navigation section in the configuration file. You should see a boolean key named IsHidden with a True value. Please give this key a False value now.

Reload the application interface with the Admin menu and the option Reload the interface or directly with ⌘R. A bottom view should appear with a single button on the right, displaying “Quit”. When you click on this button, the application will try to exit, saving the user inputs in the process. To be able to see that in action, choose a random value in the popup button “What is your level?”, copy the following 555-555-555 into the text field below “What is your Mac asset tag?”, and check the “I agree” box. We will come back to inputs validation in another tutorial.

Now clicks on the “Quit” button. The application should terminate. To find the generated user inputs file, go to your home directory. You should find there an Octory folder, and inside it a file named Octory_inputs.json. If you open it, you should see all the user inputs.

To end this tutorial, let’s see how you can customise the file format and path to save those inputs.

Add a new section in the configuration file, named Input. Make it a dictionary.

PLIST Editor
PLIST Editor

The sections order does not matter, as the root key is a dictionary. Thus, you can insert the Input section wherever you want, as long as it is a direct child of the root key.

This section has only two children keys. The required FileFormat string key allows you to choose the format of the file where the inputs will be saved. You can choose the PLIST or JSON value. You can then choose where to store the file and which name it should have with the string key FilePath. Note that that the value of this key should be a full path to the file, with its extension. We will use those keys to save the user inputs in /User/Shared/ with a Plist format, and naming the file User_inputs. To do so, add the key FileFormat and give the value PLIST. Then add the key FilePath and give it the value /Users/Shared/User_input.plist. Your Input section should look like this.

PLIST Editor
PLIST Editor

Now, please fill all the required field as we did previously.

Choose a random value in the popup button “What is your level?”, copy the following 555-555-555 into the text field below “What is your Mac asset tag?”, and check the “I agree” box.

When you click the “Quit” button now, the file User_inputs should be generated in the folder /Users/Shared/.

You can now export this file to your MDM, or read its content for later uses.

Extend the preset with Octory Pro

We just saw how to retrieve the user inputs into a file. We will see how we can directly send those values to your MDM with API actions.

Develop the section named APIRequests then develop the following: Models β†’ SendForm. This section allows you to define API Requests to be reused in the overall configuration file. Here, we have defined a request to send all the user input to the URL, which you should change when sending the request to your MDM. When doing so, you should add the MDM string key to let the application know how to communicate with it. For example, when you want to send the user inputs to your Jamf Pro API, you would end up with a similar request:

There are several ways to send this request. In this preset, we have already implemented one. The request will be sent when the user clicks the “Send” button. If you develop the following: Slides β†’ Item 0 β†’ Containers β†’ Item 0 β†’ Components β†’ Item 14, you should see a Button Component.

The dictionary key OnClick allows you to specify a set of actions to execute when the user clicks the button. If you develop OnClick β†’ Actions, you should see an array of three items.

Each item is an action which will be executed. If you pay attention to the Type key just below the OnClick key, you should see the value Chained, which means that those actions will be executed one after another. If you wanted to execute those actions concurrently, you would rather give the Type key the Parallel value.

If you develop the first item, you should see it has two children keys: Type and Request. The Type key allows you to specify the type of action you want to execute. There are several possible values for this key, like DisplayAlert, PlaySound… You can find the full list here.

As we specified a SendRequest value for the Type key, the application needs to know which request it should send. Hence the presence of the Request key, with its value set to SendForm: the name we gave to the request in the APIRequests section. Note that you could override some parts of the request SendForm when using it - like its Endpoint key - as we will see in another tutorial.

Finally, if you develop the two other actions (Item 1 and Item 2), you should see we are asking to the application to execute two bash commands, one after the other as the Type key below the OnClick key is set to Chained.

The first command will retrieve the application PID and store it into a variable named OctoryPID. The second action will kill the application by reading the PID contained in the variable OctoryPID.

To summarise what a click on the “Send” button does with Octory Pro: it will send the user inputs to a specific endpoint to your MDM Api, wait for the result, then kill the application. Would the request failed, for example if your MDM Api is unreachable, you could decide not to execute the remaining actions (kill the application) by adding the boolean key ContinueAfterFailure and set its value to False.


Alexis Bridoux
Octory Lead developer & Product owner