Class: Jamf::ManagedSoftwareUpdates::Plan

Inherits:
OAPISchemas::ManagedSoftwareUpdatePlan show all
Extended by:
Filterable
Includes:
CollectionResource, Immutable
Defined in:
lib/jamf/api/jamf_pro/api_objects/managed_software_updates/plan.rb

Overview

A ManagedSoftwareUpdate Plan contains the details for installing managed software updates via MDM/DDM on a device. When plans are created for a group there will be one for every member of the group

Constant Summary collapse

SEARCH_RESULT_OBJECT =

The OAPI object class we get back from a ‘list’ query to get the whole collection, or a subset of it. It contains a :results key which is an array of data for objects of the parent class.

Jamf::OAPISchemas::ManagedSoftwareUpdatePlans
POST_OBJECT =

The OAPI object class we send with a POST request to make a new member of the collection in Jamf. This is often the same as the parent class.

Jamf::OAPISchemas::ManagedSoftwareUpdatePlanPost
GROUP_POST_OBJECT = 
Jamf::OAPISchemas::ManagedSoftwareUpdatePlanGroupPost
LIST_PATH =

The path for GETting the list of all objects in the collection, possibly filtered, sorted, and/or paged REQUIRED for all collection resources

GET_PATH, POST_PATH, PUT_PATH, PATCH_PATH, and DELETE_PATH are automatically assumed from the LIST_PATH if they follow the standards:

  • GET_PATH = “#LIST_PATH/id”

    • fetch an object from the collection

  • POST_PATH = LIST_PATH

    • create a new object in the collection

  • PUT_PATH = “#LIST_PATH/id”

    • update an object passing all its values back. Most objects use this or PATCH but not both

  • PATCH_PATH = “#LIST_PATH/id”

    • update an object passing some of its values back Most objects use this or PUT but not both

  • DELETE_PATH = “#LIST_PATH/id”

    • delete an object from the collection

If those paths differ from the standards, the constants must be defined here

"#{MANAGED_SW_UPDATES_PATH}/plans"
GROUP_PLANS_PATH =

GETting this resource provides a list of existing group plans POSTing to this resource will initiate a new plan targeting a group of devices

"#{LIST_PATH}/group"
FILTER_KEYS =

Must define this when extending Filterable

%i[
  planUuid device.deviceId device.objectType updateAction versionType specificVersion maxDeferrals recipeId forceInstallLocalDateTime state
].freeze
GROUP_TYPES = 
{
  computer: 'COMPUTER_GROUP',
  mobile_device: 'MOBILE_DEVICE_GROUP'
}.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#cnx ⇒ Jamf::Connection (readonly) Originally defined in module JPAPIResource

Returns the API connection thru which we deal with this resource.

Returns:

  • (Jamf::Connection) —

    the API connection thru which we deal with this resource.

#delete_path ⇒ String (readonly) Originally defined in module CollectionResource

Returns The path for deleting a this item from the collection in the JPAPI.

Returns:

  • (String) —

    The path for deleting a this item from the collection in the JPAPI

#get_path ⇒ String (readonly) Originally defined in module JPAPIResource

Returns The path for fetching this thing from the JPAPI

this gets set in the constructor in the CollectionResource or SingletonResource mixins.

Returns:

  • (String) —

    The path for fetching this thing from the JPAPI

    this gets set in the constructor in the CollectionResource or SingletonResource mixins

#post_path ⇒ String (readonly) Originally defined in module CollectionResource

Returns The path for creating a new item in the collection in the JPAPI.

Returns:

  • (String) —

    The path for creating a new item in the collection in the JPAPI

#update_path ⇒ String (readonly) Originally defined in module JPAPIResource

Returns The path for updating this thing from the JPAPI

this gets set in the constructor in the CollectionResource or SingletonResource mixins

We use ‘update_path’ because some items are updated via a PUT_PATH and others via a PATCH_PATH. When this gets set, it will contain the appropriate one.

Returns:

  • (String) —

    The path for updating this thing from the JPAPI

    this gets set in the constructor in the CollectionResource or SingletonResource mixins

    We use ‘update_path’ because some items are updated via a PUT_PATH and others via a PATCH_PATH. When this gets set, it will contain the appropriate one.

Class Method Details

.declarations(planUuid, cnx: Jamf.cnx) ⇒ Array<Jamf::OAPISchemas::DssDeclaration>

Get the declarations for a plan

Parameters:

  • plan_uuid (String) —

    the UUID of the plan to get declarations for

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    the connection to use, defaults to Jamf.cnx

Returns:



125
126
127
128
129
 
# File 'lib/jamf/api/jamf_pro/api_objects/managed_software_updates/plan.rb', line 125

def self.declarations(planUuid, cnx: Jamf.cnx)
  cnx.jp_get("#{LIST_PATH}/#{planUuid}/declarations")[:declarations].map do |declaration|
    Jamf::OAPISchemas::DssDeclaration.new(declaration)
  end
end

.event_store(planUuid, cnx: Jamf.cnx) ⇒ Array<Hash>

get the events for a plan

BUG ? : At lease thru Jamf Pro 11.17.1, this endpoint returns a double-wrapped JSON object The first one is a Hash with one key :events, which is a String containing the JSON for the actual events - an Array of Hashes, which don’t have an OAPI schema.

Those Hashes look like this, but aren’t consistent

{:type=>".QueueAvailableOsUpdatesCommand",
:eventSentEpoch=>1749158978751,
:managementUUID=>"a94b11f0-c870-4006-82fe-e7afa981d61c",
:processManagerUUID=>"a4b45b0a-4a46-4a52-8322-ab4f9895ab21",
:availableOSUpdateDelay=>300},

{:id=>4238,
:type=>".AvailableOsUpdateRequestCompletedEvent",
:deviceObjectId=>1,
:managementUUID=>"a94b11f0-c870-4006-82fe-e7afa981d61c",
:eventReceivedEpoch=>1749159337161,
:processManagerUUID=>"a4b45b0a-4a46-4a52-8322-ab4f9895ab21",
:availableOSUpdatesDto=>
{:deviceObjectId=>1,
  :managementUUID=>"a94b11f0-c870-4006-82fe-e7afa981d61c",
  :availableOsUpdates=>
  [{:build=>"",
    :preview=>false,
    :version=>"16.4",
    :critical=>false,
    :productKey=>"082-41241",
    :installSize=>0,
    :productName=>"",
    :downloadSize=>882235914,
    :majorOSUpdate=>false,
    :firmwareUpdate=>false,
    :restartRequired=>false,
    :humanReadableName=>"Command Line Tools for Xcode",
    :allowsInstallLater=>true,
    :appIdentifiersToClose=>[],
    :configurationDataUpdate=>false},
    {:build=>"",
    :preview=>false,
    :version=>"5299",
    :critical=>false,
    :productKey=>"082-54857",
    :installSize=>0,
    :productName=>"",
    :downloadSize=>1256157,
    :majorOSUpdate=>false,
    :firmwareUpdate=>false,
    :restartRequired=>false,
    :humanReadableName=>"XProtectPlistConfigData",
    :allowsInstallLater=>true,
    :appIdentifiersToClose=>[],
    :configurationDataUpdate=>true}],
  :eventReceivedEpoch=>1749159337161
  }
 }

note that some have id’s and some don’t. Some have response data (like the available OS updates) which can contain a more complex data structure.

NOTE: This may be intentional, but is not documented in the JPAPI docs. The endpoint is “events” but what’s returned is an ‘event store’. Its possible that the data comes from Apple as JSON and Jamf is just passing it through. Awaiting clarification from Jamf on this.

In any case, this method will unwrap the JSON and return the events as an Array of Hashes

Parameters:

  • plan_uuid (String) —

    the UUID of the plan to get events for

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    the connection to use, defaults to Jamf.cnx

Returns:



205
206
207
208
209
210
211
212
 
# File 'lib/jamf/api/jamf_pro/api_objects/managed_software_updates/plan.rb', line 205

def self.event_store(planUuid, cnx: Jamf.cnx)
  data = cnx.jp_get("#{LIST_PATH}/#{planUuid}/events")
  if data[:events].is_a?(String) && data[:events].start_with?('{"events":')
    JSON.parse data[:events], symbolize_names: true
  else
    data[:events]
  end
end

.filter_keys ⇒ Object Originally defined in module Filterable

.group_plans(group_id:, type:, cnx: Jamf.cnx) ⇒ Array<Jamf::ManagedSoftwareUpdates::Plan>

Get an Array of all plans for a given group, either computer or mobile device.

Parameters:

  • group_id (Integer) —

    the ID of the group to get plans for

  • type (Symbol) —

    the type of group, either :computer or :mobile_device

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    the connection to use, defaults to Jamf.cnx

Returns:

Raises:

  • (ArgumentError) 


105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/jamf/api/jamf_pro/api_objects/managed_software_updates/plan.rb', line 105

def self.group_plans(group_id:, type:, cnx: Jamf.cnx)
  gtype = GROUP_TYPES[type.to_sym]
  raise ArgumentError, "Invalid group type: #{type}, must be one of :#{GROUP_TYPES.keys.join ', :'}" unless gtype

  plans = Jamf.cnx.jp_get("#{GROUP_PLANS_PATH}/#{group_id}?group-type=#{gtype}")[:results]
  plans.map do |plan_data|
    plan_data[:cnx] = cnx
    plan_data[:instantiate_me] = true
    new(**plan_data)
  end
end

Instance Method Details

#declarations ⇒ Array<Jamf::OAPISchemas::DssDeclaration>

get the declarations for this plan

Returns:



221
222
223
 
# File 'lib/jamf/api/jamf_pro/api_objects/managed_software_updates/plan.rb', line 221

def declarations
  self.class.declarations(planUuid, cnx: cnx)
end

#delete ⇒ Object Originally defined in module CollectionResource

Raises:

#event_store ⇒ Array<Jamf::OAPISchemas::DssDeclaration>

get the events for this plan

Returns:



229
230
231
 
# File 'lib/jamf/api/jamf_pro/api_objects/managed_software_updates/plan.rb', line 229

def event_store
  self.class.event_store(planUuid, cnx: cnx)
end

#exist? ⇒ Boolean Originally defined in module CollectionResource

Returns:

  • (Boolean)

#initialize(**data) ⇒ Object Originally defined in module CollectionResource

Constructor

#pretty_print_instance_variables ⇒ Array Originally defined in module JPAPIResource

Remove large cached items from the instance_variables used to create pretty-print (pp) output.

Returns:

  • (Array) —

    the desired instance_variables

#save ⇒ Object Originally defined in module JPAPIResource

TODO: error handling

Raises:

#to_s ⇒ String Originally defined in module CollectionResource

A meaningful string representation of this object

Returns: