public.script.item

Function description

Introduced in Hello-IT v1.4.0

Goal

This function allow you to use a script as main implementation.

The script will be able to update the title, the state, hide or disable the menu item.

Settings

The settings dictionary contain all informations you can set to use this function. Here is a description of each.

Key	Type	Description
title	Translatable string (see: Label translation)	Item's title shown in the menu
optionalDisplay	Boolean	Will show the related item only if option key was pressed when Hello-IT menu was shown (supported in Hello-IT 1.4.0+)
script	String	Name of the script (extension included) located in /Library/Application Support/com.github.ygini.hello-it/CustomScripts
path	String	Full path for the script to run
repeat	Integer (optional)	Number of seconds between each periodic run, 0 mean no repeat mode, default is 60
options	Array of string (optional)	Array of string given as command line argument
network	Boolean (optional)	Specify that the script is network related and so, will be notified of any changes.

You must have script OR path key, but not both.

Sample settings

<dict>
	<key>functionIdentifier</key>
	<string>public.script.item</string>
	<key>settings</key>
	<dict>
		<key>script</key>
		<string>com.github.ygini.hello-it.hostname.sh</string>
		<key>repeat</key>
		<integer>60</integer>
		<key>options</key>
		<array>
			<string>-format</string>
			<string>%C</string>
		</array>
	</dict>
</dict>

More informations

Main implementation

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

Writing the script

Generic informations

Usage by Hello-IT

When the plugin call the script set in settings, it call it with at least a verb allowing the script to know the execution context.

Verb	Scenario
run	User clicked on the menu item
periodic-run	Script started by Hello-IT cron system
network	Hello-IT has detected a network change (only when network settings is enabled)
notification	The user clicked on your notification
title	Hello-IT is asking for the title to display on the menu item (during a refresh of the UI for example)

Interaction with Hello-IT from the script are done via stdout. A whole set of hitp- prefixed command is available and described below.

You simply write a new line to stdout matching this format: hitp-command: Value for Hello-IT.

Supported commands

Command	Supported value	Usage
hitp-title	Free form string	New title to show for the menu item
hitp-state	ok, warning, error, unavailable, none	State to report for the menu item
hitp-enabled	YES, NO	Enable or not the menu item (disabled ones will be visible but grayed out)
hitp-hidden	YES, NO	Hide or not the menu item
hitp-tooltip	Free form string	Update the tooltip for the menu item
hitp-notification	Free form string	Message to display as a system notification (starting 1.4.3)
hitp-open	URL string	A valid RFCs 2396, 1738 and 1808 URL to open (starting 1.5.0)

In addition to this list of command, you can also send logs to the system via Hello-IT. This will simplify the collection of logs by a common source in Console.app.

All logs command support a free form string as value:

• 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

More about the options and arguments

To explicit the run of your script, here is some example:

# options: -a 1 -v -S test


# on menu load or reload:
/path/to/your/script title -a 1 -v -S test
# on click:
/path/to/your/script run -a 1 -v -S test

# options: -a 1 -v -S test
# network: YES


# on menu load or reload:
/path/to/your/script title -a 1 -v -S test
# on click:
/path/to/your/script run -a 1 -v -S test
# on network change:
/path/to/your/script network -a 1 -v -S test

# options: -a 1 -v -S test
# network: YES
# repeat: 60


# on menu load or reload:
/path/to/your/script title -a 1 -v -S test
# on click:
/path/to/your/script run -a 1 -v -S test
# on network change:
/path/to/your/script network -a 1 -v -S test
# every 60 seconds:
/path/to/your/script run-periodic -a 1 -v -S test

Script with Hello-IT 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_SH_LIBRARY/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 Hello-IT detect a network change
function onNetworkAction {

}

### 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 the user click on your notification
function fromNotificationAction {
    
}

### 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

Environmental variables

Some additional informations are sent via environmental variables.

Variable	Value
HELLO_IT_SCRIPT_FOLDER	Path to the custom script folder /Library/Application Support/com.github.ygini.hello-it/CustomScripts
HELLO_IT_SCRIPT_SH_LIBRARY	Path to the bash folder library (To use that way: . "$HELLO_IT_SCRIPT_SH_LIBRARY/com.github.ygini.hello-it.scriptlib.sh")
HELLO_IT_OPTIONS_AVAILABLE	A yes or no value to tell of options has been set
HELLO_IT_OPTIONS	Access to the original options string as a variable (usable only when HELLO_IT_OPTIONS_AVAILABLE is set to yes)

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

To test your script you may need to fill some of those variables:

HELLO_IT_SCRIPT_SH_LIBRARY="/Applications/Utilities/Hello IT.app/Contents/PlugIns/ScriptedItem.hitp/Contents/Resources/scriptLibraries/bash" bash /Users/ygi/Desktop/test.sh run

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_SH_LIBRARY/com.github.ygini.hello-it.scriptlib.sh"

function sharedImplementation {	

}

function onClickAction {
    sharedImplementation $@
}

function onNetworkAction {
    sharedImplementation $@
}

function fromCronAction {
    sharedImplementation $@
}

function setTitleAction {
    sharedImplementation $@
}

main $@

exit 0

Don't forget that setTitleAction is called when Hello IT load or reload (so at login time or when the MDM change Hello IT settings).

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)

sendNotification send a notification message 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