public.script.item

Introduction

This function allow you to use a script as main implementation. The script will be able to update the menu item title and the state. It will also be able to disable the menu item.

Main implementation

The main implementation of this function is made in the ScriptedItem plugin in the main project.

When the plugin call the script set in settings, it call it with two arguments.

The first one is the command, it allow complex plugins to know the execution context. Supported values are:

• "run", when the user clicks on the item
• "periodic-run", when a repeat setting is used (each periodic call is called that way, you don't have to manage your own cron system), must be specified in seconds in between each run as integer type

<key>periodic-run</key>
<integer>60</integer>

• "title" during the application launch to set the title of the menu item.

The second argument will be a plist of settings set by the sys admin, encoded in base64.

During the execution, the script must use the stdout to talk with the Hello IT application. This is required to update item state.

To update item's settings, the script must write specific line starting by "hitp-:" on stdout.

Supported values are:

• hitp-title to update the item title ;
• hitp-state to update the item state, supported values are:
• ok ;
• warning ;
• error ;
• unavailable ;
• none ;
• hitp-enabled to disable or enable the menu item, supported values are:
• YES ;
• NO ;
• hitp-hidden to hide or not the menu item, supported values are:
• YES ;
• NO ;
• hitp-tooltip to update the item tool tip ;
• hitp-log-emerg to log an emergency message ;
• hitp-log-alert to log an alert message ;
• hitp-log-crit to log a critical message ;
• hitp-log-err to log an error message ;
• hitp-log-warning to log a warning message ;
• hitp-log-notice to log a notice message ;
• hitp-log-info to log an info message ;
• hitp-log-debug to log a debug message ;

During one run, the script can update all necessary values any number of time.

A script output example could be:

hitp-enabled: NO
hitp-title: Operation in progress...
Some random output by other command who will be ignored
hitp-state: ok
hitp-title: Regular title
hitp-enabled: YES
hitp-tooltip: Hello World

Settings

The settings must be organized in a dictionary who must contain one of this key:

• "script" the name of the script (extension included) located in /Library/Application Support/com.github.ygini.hello-it/CustomScripts ;
• "path" a string representing the script location ; And may contain:
• "repeat" an integer representing the number of seconds between each tries, 0 mean no repeat mode, the default is 0 ;
• "options" an array of string given to the script as it is ;
• "args" a dictionary of arguments to pass to the script as a base64 encoded XML plist ;
• "network" a boolean value to use the global network state feature (see plugin creation documentation), the network state update will be sent to the script as a third argument when this settings is set to YES.

In the end, your script will be run like that:

options: -a 1 -v -S test
/path/to/your/script run -a 1 -v -S test

args: <plist>
/path/to/your/script run base64_data

options: -a 1 -v -S test
args: <plist>
network: 1
/path/to/your/script run -a 1 -v -S test base64_data

options: -a 1 -v -S test
network: 1
/path/to/your/script run -a 1 -v -S test 0_or_1

args: <plist>
network: 1
/path/to/your/script run base64_data 0_or_1

options: -a 1 -v -S test
args: <plist>
network: 1
/path/to/your/script run -a 1 -v -S test base64_data 0_or_1

Use the shared bash lib

The script based item is a really complex item, it can be used to handle many complexe scenario. The original idea was to allow people to contribute to Hello IT by building new module in an other language.

But many people use it to simple package custom action like cleaning Office temp files or triggering a Chef run.

To simplify the use for IT purpose a shared lib is built-in Hello IT since v1.2.4 and can be used with the following canevas:

#!/bin/bash

### The following line load the Hello IT bash script lib
. "$HELLO_IT_SCRIPT_FOLDER/com.github.ygini.hello-it.scriptlib.sh"

### This function is called when the user click on your item
function onClickAction {
    
}

### This function is called when you've set Hello IT to run your script on a regular basis
function fromCronAction {
    
}

### This function is called when Hello IT need to know the title to display
### Use it to provide dynamic title at load.
function setTitleAction {
    
}

### The only things to do outside of a bash function is to call the main function defined by the Hello IT bash lib.
main $@

exit 0

About args and options

When using the Hello IT bash lib, you can access to your script settings in different ways.

The global network state info is available via the $HELLO_IT_NETWORK_STATE variable.

args info are stored in a plist file path is stored in $HELLO_IT_PLIST_PATH.

options array is accessible via $@ variable inside setTitleAction, fromCronAction, onClickAction.

All action doing the same

If for all actions you want to do the same things, the following implementation is recommended:

#!/bin/bash

. "$HELLO_IT_SCRIPT_FOLDER/com.github.ygini.hello-it.scriptlib.sh"

function sharedImplementation {	

}

function onClickAction {
    sharedImplementation $@
}

function fromCronAction {
    sharedImplementation $@
}

function setTitleAction {
    sharedImplementation $@
}

main $@

exit 0

Don't forget that setTitleAction is called when Hello IT start (so at login time).

Interact with Hello IT

The Hello IT bash lib provide custom function to interact with Hello IT

updateTitle update item title with first argument (don't forget quotes)

updateState update item state with first argument. The first argument must be on of the following:

• ${STATE[0]} --> OK (Green light)
• ${STATE[1]} --> Warning (Orange light)
• ${STATE[2]} --> Error (Red light)
• ${STATE[3]} --> Unavailable (Empty circle)
• ${STATE[4]} --> No state to display (Nothing at all)

setEnabled enable or not the item to be clicked (first arg must be YES or NO)

setHidden hide or not the item (first arg must be YES or NO)

updateTooltip update item tooltip with first argument (don't forget quotes)

Logs

To provide logs to Hello IT use one of the following function:

• emergencyLog
• alertLog
• criticalLog
• errorLog
• warningLog
• noticeLog
• infoLog
• debugLog