Welcome to Jook’s documentation!¶

Install Jook¶

You can install Jook from the Pyhon Package Index:

$ pip install jook

Basic Usage¶

Jook allows you to create Python objects that can fire off HTTP requests that mock webhook events from a Jamf Pro server.

Getting started is easy:

>>> import jook
>>> computer = jook.Computer('http://localhost', 'ComputerAdded')
>>> computer.fire()

Jook supports both JSON and XML formats for data to send (JSON is the default):

>>> computer = jook.Computer('http://localhost', 'ComputerCheckIn', mode='xml')
>>> computer.to_xml()
'<?xml version="1.0" encoding="UTF-8" ?><JSSEvent><webhook><webhookEvent>ComputerCheckIn</webhookEvent>...</JSSEvent>'
>>> computer.to_json()
'{"webhook": {"webhookEvent": "ComputerCheckIn", "id": 1, "name": ""}, "event": {...}'

Create objects in randomize mode to generate unique data with every fire:

>>> rand_comp = jook.Computer('http://localhost', 'ComputerInventoryCompleted', randomize=True)
>>> rand_comp.data
{'webhook': {...}, 'event': {..., 'udid': '0699A579-2835-4E5F-8847-944D9A477DDD', 'serialNumber': 'CPFQ2MXCG5ND', ...}}
>>> rand_comp.data
{'webhook': {...}, 'event': {..., 'udid': '1ABE2310-4396-4ABC-AAA9-5B48E6CFC7F5', 'serialNumber': 'C1FK9EXSFKQT', ...}}

Create DeviceData and LocationData objects to pass into webhooks to control the data sent in the mock events:

>>> my_device = DeviceData('computer')
>>> my_device.serial_number
'CPFQMEE3HYFH'
>>> comp1 = Computer('http://localhost', 'ComputerAdded', device=my_device)
>>> comp1.device.serial_number
'CPFQMEE3HYFH'
>>> comp2 = Computer('http://localhost', 'ComputerCheckIn', device=my_device)
>>> comp1.device.serial_number
'CPFQMEE3HYFH'

Set events to run in a loop with a set delay. This example sets a timer delay of five seconds and then starts a loop of 10 fire calls:

>>> computer = jook.Computer('http://localhost', 'ComputerCheckIn', timer=5)
>>> computer.start_timer(repeat=10)

Base Webhook Object¶

class jook.models.webhooks.BaseWebhook(url, event, webhook_id=1, webhook_name='Webhook', mode='json', randomize=False, timer=0, *args, **kwargs)[source]¶

The base webhook object.

Contains all shared methods used by child objects.

Parameters:

url (str) – The target URL (must contain the scheme)
event (str) – The type of webhook event. The available event types are defined in the valid_event attribute for the object.
mode (str) –
The type of data to send when calling fire().

Can only be ‘json’ or ‘xml’
randomize (bool) –
Values for the webhook object’s data are randomly generated every time when set to True.

If False certain values are generated during the object’s creation and stored. These values will be the same each time fire() is called.

If True those values will be set to None and generated at the time fire() is called.
timer (int) – An optional value in seconds to specify the delay when using start_timer().
webhook_id (int) – An optional ID value for the webhook event.
webhook_name (str) – An optional name for the webhook event.

Raises:

InvalidEvent –
InvalidMode –
InvalidURL –
TypeError –

data¶

This method generates the object data in JSON or XML format which is set by the data_type attributes.

This method should be overridden by children that inherit this object.

The data object contains the event specific key-values. It is then updated with the key-values from _base_data.

fire()[source]¶: Send a POST request containing the object’s data in the specified data type to the stored URL.

start_timer(repeat=1)[source]¶

Start a series of :method: fire calls delayed by the value of timer in seconds for the number of times specified by repeat.

Parameters:	repeat (int) – Number of times to execute :method: `fire`

to_json()[source]¶

Return the object’s data as JSON.

Returns:	JSON string
Return type:	str

to_xml()[source]¶

Return the object’s data as XML.

Returns:	XML string
Return type:	str

Device Events¶

Base Device Object¶

class jook.models.webhooks.BaseDevice(*args, **kwargs)[source]¶

Base class for computer and mobile device webhooks.

If randomize has been set to True and a DeviceData object has not been passed, the instantiated DeviceData object will be created with the randomized argument set.

Parameters:	device (DeviceData) – location (LocationData) –

Computer Events¶

class jook.models.webhooks.Computer(*args, **kwargs)[source]¶

The base BaseWebhook object for ‘Computer’ events.

If randomize has been set to True and a DeviceData object has not been passed, the instantiated DeviceData object will be created with the randomized argument set.

Parameters:	device (DeviceData) – location (LocationData) –

data¶

Return data for the object as a dictionary.

Returns:	`data` as a dictionary object
Return type:	dict

Mobile Device Events¶

class jook.models.webhooks.MobileDevice(*args, **kwargs)[source]¶

The base Webhook object for ‘Mobile Device’ events.

If randomize has been set to True and a DeviceData object has not been passed, the instantiated DeviceData object will be created with the randomized argument set.

Parameters:	device (DeviceData) – location (LocationData) –

data¶

Return data for the object as a dictionary.

Returns:	`data` as a dictionary object
Return type:	dict

Device Data Sets¶

Device Data¶

class jook.models.data_sets.DeviceData(device_type='computer', mac_address=None, mac_address_alt=None, serial_number=None, uuid=None, randomize=False)[source]¶

An object representing device identifiers for computer and monbile device webhooks.

Instantiate a DeviceData object.

Pass values for the different attributes to manually customize the data.

If no arguments are passed the initial values are randomly generated and saved.

Parameters:

device_type (str) – The type of device to determine how certain identifiers are generated. Must be``computer`` or mobile.
mac_address (str) –
mac_address_alt (str) –
serial_number (str) –
uuid (str) –
randomize (bool) – If True, no initial values will be set (passed args will be ignored) and a random value will be generated each time an attribute is called.

mac_address¶: Return the value for mac_address.

mac_address_alt¶: Return the value for mac_address_alt.

serial_number¶: Return the value for serial_number.

set_mac_address(mac_address=None)[source]¶

Set the value for mac_address.

If a value is not passed a randomized value will be stored.

set_mac_address_alt(mac_address=None)[source]¶

Set the value for mac_address_alt.

If a value is not passed a randomized value will be stored.

set_serial_number(serial_number=None)[source]¶

Set the value for serial_number.

If a value is not passed a randomized value will be stored.

set_uuid(uuid=None)[source]¶

Set the value for uuid.

If a value is not passed a randomized value will be stored.

uuid¶: Return the value for uuid.

Location Data¶

jook.models.data_sets.LocationData¶: alias of Location

Jamf Pro Server Events¶

class jook.models.webhooks.JamfPro(*args, **kwargs)[source]¶

The base Webhook object for ‘JSS’ events.

Parameters:

institution (str) – The name of the organization the server is registered to (defaults to ‘Example Org’).
host_address (str) – The IP address of the originating server (defaults to 10.0.0.1).
web_app_path (str) – The root path of the web app for the server (defaults to /).
is_master (bool) – Is the originating server a cluster master (defaults to True).
server_url (str) – The URL of the originating server (defaults to https://jss.example.org).

Patch Title Events¶

class jook.models.webhooks.PatchTitle(*args, **kwargs)[source]¶

The base webhook object for ‘Patch Title’ events.

Parameters:

jss_id (int) – ID of the Patch Title in Jamf Pro (defaults to 1).
patch_name (str) – The Patch Title name (defaults to ‘Flash’).
patch_version (str) – The new Patch Title version (defaults to 1).
report_url (str) – The URL to the Patch Title’s report in Jamr Pro (Defaults to ‘https://jss.example.org/patch.html?id=‘ + the JSS ID).
timestamp (int) – The UNIX timestamp of when the Patch Title was updated. If not provided, or not a valid timestamp, it will be set to the current time.