Module: JSS::Creatable

Included in:
AdvancedSearch, Building, Category, Computer, ComputerInvitation, Department, DirectoryBinding, DockItem, ExtensionAttribute, Group, IBeacon, MobileDevice, MobileDeviceApplication, NetworkSegment, Package, PatchExternalSource, PatchPolicy, PatchTitle, Peripheral, PeripheralType, Policy, Printer, RemovableMacAddress, RestrictedSoftware, Script, Site, User, WebHook
Defined in:
lib/jss.rb,
lib/jss/api_object/creatable.rb

Overview

A mix-in module that allows objects to be created in the JSS via the API.

When a JSS::APIObject subclass includes this module, that subclass can be instantiated with :id => :new, and :name => “some_new_name”.

Classes mixing this module must provide a #rest_xml instance method that returns the XML String to be submitted to the API for object creation.

The instance can be used to set desired values for the new object, and once everything's good, use #create to create it in the JSS.

If a Creatable object requires more data than just a :name for creation, the subclass may want to redefine #initialize to require those data before calling super, or may want to redefine #create or #rest_xml to check the data for consistency, and then call super

It is also wise to have the individual setter methods do data validation

See Also:

Constant Summary collapse

CREATABLE =

Constants

true

Instance Method Summary collapse

Instance Method Details

#clone(new_name, api: nil) ⇒ APIObject

make a clone of this API object, with a new name. The class must be creatable

Parameters:

  • name (String) —

    the name for the new object

  • api (JSS::APIConnection) (defaults to: nil) —

    the API in which to create the object Defaults to the API used to instantiate this object

Returns:

  • (APIObject) —

    An uncreated clone of this APIObject with the given name

Raises:



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/jss/api_object/creatable.rb', line 101

def clone(new_name, api: nil)
  api ||= @api
  raise JSS::UnsupportedError, 'This class is not creatable in via ruby-jss' unless creatable?
  raise JSS::AlreadyExistsError, "A #{self.class::RSRC_OBJECT_KEY} already exists with that name" if \
    self.class.all_names(:refresh, api: api).include? new_name

  orig_in_jss = @in_jss
  @in_jss = false
  orig_id = @id
  @id = nil
  orig_rsrc = @rest_rsrc
  @rest_rsrc = "#{self.class::RSRC_BASE}/name/#{CGI.escape new_name.to_s}"
  orig_api = @api
  @api = api

  new_obj = dup

  @in_jss = orig_in_jss
  @id = orig_id
  @rest_rsrc = orig_rsrc
  @api = orig_api
  new_obj.name = new_name

  new_obj
end

#create ⇒ Integer

Create a new object in the JSS.

Parameters:

  • api (JSS::APIConnection) —

    the API in which to create the object Defaults to the API used to instantiate this object

Returns:

  • (Integer) —

    the jss ID of the newly created object

Raises:



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/jss/api_object/creatable.rb', line 74

def create
  raise JSS::UnsupportedError, "Creating or editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless creatable?

  raise AlreadyExistsError, "This #{self.class::RSRC_OBJECT_KEY} already exists. Use #update to make changes." if @in_jss

  @api.post_rsrc(rest_rsrc, rest_xml) =~ %r{><id>(\d+)</id><}
  @id = Regexp.last_match(1).to_i
  @in_jss = true
  @need_to_update = false
  @rest_rsrc = "#{self.class::RSRC_BASE}/id/#{@id}"

  # clear any caches for this class
  # so they'll re-cache as needed
  @api.flushcache self.class::RSRC_LIST_KEY

  @id
end