ruby-jss 0.6.3

data/lib/jss/api_object/updatable.rb

@@ -0,0 +1,117 @@
+### Copyright 2016 Pixar
+###  
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###  
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###  
+###    You may obtain a copy of the Apache License at
+###  
+###        http://www.apache.org/licenses/LICENSE-2.0
+###  
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+### 
+###
+
+###
+module JSS
+
+### A mix-in module providing object-updating via the JSS API.
+###
+
+
+
+  #####################################
+  ### Module Variables
+  #####################################
+
+  #####################################
+  ### Module Methods
+  #####################################
+
+  #####################################
+  ### Sub-Modules
+  #####################################
+
+  ###
+  ### A mix-in module that allows objects to be updated in the JSS via the API.
+  ###
+  ### When a JSS::APIObject subclass includes this module, instances of that
+  ### subclass can be modified in the JSS using the {#update} or {APIObject#save} methods.
+  ###
+  ### Such classes should define setter methods for any values that they wish to
+  ### modify, such as the {#name=} method defined here. Those setter methods must:
+  ### - ensure the correctness of the data they accept.
+  ### - set @need_to_update to true, indicating that the local object no longer
+  ###   matches the JSS, and the changes should be pushed to the server with {#update}
+  ###
+  ### Classes mixing this module *must* provide a #rest_xml instance method that returns the XML
+  ### String to be submitted to the API for object updating.
+  ###
+  ### @see APIObject#save
+  ###
+  module Updatable
+
+    #####################################
+    ###  Constants
+    #####################################
+
+    UPDATABLE = true
+
+    #####################################
+    ###  Attributes
+    #####################################
+
+
+    ### @return [Boolean] do we have unsaved changes?
+    attr_reader :need_to_update
+
+
+    #####################################
+    ###  Mixed-in Instance Methods
+    #####################################
+
+    ###
+    ### Change the name of this item
+    ### Remember to #update to push changes to the server.
+    ###
+    ### @param newname[String] the new name
+    ###
+    ### @return [void]
+    ###
+    def name= (newname)
+      raise JSS::UnsupportedError, "Editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless UPDATABLE
+      return nil if @name == newname
+      raise JSS::InvalidDataError, "Names can't be empty!" if newname.to_s.empty?
+      raise JSS::AlreadyExistsError, "A #{self.class::RSRC_OBJECT_KEY} named '#{newname}' already exsists in the JSS" if self.class.all_names(:refresh).include? newname
+      @name = newname
+      @rest_rsrc = "#{self.class::RSRC_BASE}/name/#{URI.escape @name}" if @rest_rsrc.include? '/name/'
+      @need_to_update = true
+    end #  name=(newname)
+
+    ###
+    ### Save changes to the JSS
+    ###
+    ### @return [Boolean] success
+    ###
+    def update
+      raise JSS::UnsupportedError, "Editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless UPDATABLE
+      return nil unless @need_to_update
+      raise JSS::NoSuchItemError, "Not In JSS! Use #create to create this #{self.class::RSRC_OBJECT_KEY} in the JSS before updating it." unless @in_jss
+      JSS::API.put_rsrc  @rest_rsrc, rest_xml
+      @need_to_update = false
+      @id
+    end # update
+
+  end # module Creatable
+
+end # module

data/lib/jss/api_object/uploadable.rb

@@ -0,0 +1,138 @@
+### Copyright 2016 Pixar
+###  
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###  
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###  
+###    You may obtain a copy of the Apache License at
+###  
+###        http://www.apache.org/licenses/LICENSE-2.0
+###  
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+### 
+###
+
+###
+module JSS
+
+  #####################################
+  ### Module Variables
+  #####################################
+
+
+  #####################################
+  ### Module Methods
+  #####################################
+
+  #####################################
+  ### Sub-Modules
+  #####################################
+
+  ###
+  ### A mixin module providing file-upload capabilities to JSSAPIObject subclasses.
+  ###
+  ### Classes mixing in this module are required to define a constant UPLOAD_TYPES
+  ### which is a Hash of :type => :resource pairs, like this:
+  ###
+  ###  UPLOAD_TYPES = {
+  ###     :icon => :mobiledeviceapplicationsicon
+  ###     :app => mobiledeviceapplicationsipa
+  ###     :attachment => mobiledeviceapplications
+  ###   }
+  ###
+  ### with one pair for each type of upload that the class can handle.
+  ### (most of them only handle one, usually :attachment)
+  ###
+  ### When the #upload method is called, one of the keys from that Hash must be specified
+  ###
+  ### Classes with only one upload type may want to redefine #upload to always call super with
+  ### that one type.
+  ###
+  ### ----
+  ###
+  ### Implementation Notes from
+  ### https://casperserver:8443/api/index.htm#!/fileuploads/uploadFiles_post
+  ###
+  ###   POST ...JSSResource/fileuploads/<resource>/<idType>/<id>
+  ###
+  ### You can POST different types of files by entering parameters for <resource>, <idType>, and <id>.
+  ### For example /JSSResource/fileuploads/computers/id/2.
+  ###
+  ### Attachments can be uploaded by specifying computers, mobiledevices, enrollmentprofiles, or
+  ### peripherals as the resource.
+  ###
+  ### Icons can be uploaded by specifying policies, ebooks, or mobiledeviceapplicationsicon as the resource.
+  ###
+  ### A mobile device application can be uploaded by using mobiledeviceapplicationsipa as the resource.
+  ###
+  ### A disk encryption can be uploaded by specifying diskencryptionconfigurations as the resource.
+  ###
+  ### idTypes supported are "id" and "name", although peripheral names are not supported.
+  ###
+  ### A sample command is:
+  ###   curl -k -u user:password https://my.jss:8443/JSSResource/fileuploads/computers/id/2 -F name=@/Users/admin/Documents/Sample.doc -X POST
+  ###
+  ###
+  ###
+  ###
+  module Uploadable
+
+    #####################################
+    ###  Constants
+    #####################################
+
+    UPLOAD_RSRC_PREFIX = "fileuploads"
+
+    #####################################
+    ###  Variables
+    #####################################
+
+
+    #####################################
+    ###  Methods
+    #####################################
+
+    ###
+    ### Upload a file to the JSS via the REST Resource of the
+    ### object to which this module is mixed in.
+    ###
+    ### @param type[Symbol] the type of upload happening.
+    ###   Must be one of the keys defined in the class's UPLOAD_TYPES Hash.
+    ###
+    ### @param local_file[String, Pathname] String or Pathname pointing to the
+    ###   locally-readable file to be uploaded.
+    ###
+    ### @return [String] The xml response from the server.
+    ###
+    def upload(type, local_file)
+
+      ### the thing's gotta be in the JSS, and have an @id
+      raise JSS::NoSuchItemError, 'Create this #{self.class::RSRC_OBJECT_KEY} in the JSS before uploading files to it.' unless @id and @in_jss
+
+      ### the type has to be defined in the class of self.
+      raise JSS::InvalidDataError, "#{self.class::RSRC_LIST_KEY} only take uploads of type: :#{self.class::UPLOAD_TYPES.keys.join(', :')}." unless self.class::UPLOAD_TYPES.keys.include? type
+
+      ### figure out the resource after the UPLOAD_RSRC_PREFIX
+      upload_rsrc = "#{UPLOAD_RSRC_PREFIX}/#{self.class::UPLOAD_TYPES[type]}/id/#{@id}"
+
+      ### make a File object to hand to REST.
+      file = File.new local_file.to_s, 'rb'
+
+      ### upload it!
+      JSS::API.cnx[upload_rsrc].post :name => file
+
+    end # def upload file
+
+  end # module FileUpload
+
+end # module JSS

data/lib/jss/api_object/user.rb

@@ -0,0 +1,272 @@
+### Copyright 2016 Pixar
+###  
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###  
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###  
+###    You may obtain a copy of the Apache License at
+###  
+###        http://www.apache.org/licenses/LICENSE-2.0
+###  
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+### 
+###
+
+###
+module JSS
+
+  #####################################
+  ### Module Variables
+  #####################################
+
+  #####################################
+  ### Module Methods
+  #####################################
+
+  #####################################
+  ### Classes
+  #####################################
+
+  ###
+  ### A User in the JSS.
+  ###
+  ### @see JSS::APIObject
+  ###
+  class User < JSS::APIObject
+
+    #####################################
+    ### Mix-Ins
+    #####################################
+    include JSS::Creatable
+    include JSS::Updatable
+    include JSS::Extendable
+
+    #####################################
+    ### Class Methods
+    #####################################
+
+    #####################################
+    ### Class Constants
+    #####################################
+
+    ### The base for REST resources of this class
+    RSRC_BASE = "users"
+
+    ### the hash key used for the JSON list output of all objects in the JSS
+    RSRC_LIST_KEY = :users
+
+    ### The hash key used for the JSON object output.
+    ### It's also used in various error messages
+    RSRC_OBJECT_KEY = :user
+
+    ### these keys, as well as :id and :name,  are present in valid API JSON data for this class
+    VALID_DATA_KEYS = [:position, :full_name, :email]
+
+    ### This class lets us seach for users
+    SEARCH_CLASS = JSS::AdvancedUserSearch
+
+    ### This is the class for relevant Extension Attributes
+    EXT_ATTRIB_CLASS = JSS::UserExtensionAttribute
+
+    #####################################
+    ### Attributes
+    #####################################
+
+    ### @return [String] The user's full name
+    attr_reader :full_name
+
+    ### @return [String] The user's email address
+    attr_reader :email
+
+    ### @return [String] The user's phone number
+    attr_reader :phone_number
+
+    ### @return [String] The user's position / job title
+    attr_reader :position
+
+    ### @return [String] The name of the user's LDAP server
+    attr_reader :ldap_server
+
+
+    ### @return [Array<Hash>]
+    ###
+    ### The sites associated with this user
+    ###
+    ### Each Hash has then :id and :name for one site
+    ###
+    attr_reader :sites
+
+
+    ### @return [Array<Hash>]
+    ###
+    ### The computers associated with this user
+    ###
+    ### Each Hash has then :id and :name for one computer
+    ###
+    attr_reader :computers
+
+
+    ### @return [Array<Hash>]
+    ###
+    ### The peripherals associated with this user
+    ###
+    ### Each Hash has then :id and :name for one peripheral
+    ###
+    attr_reader :peripherals
+
+    ### @return [Array<Hash>]
+    ###
+    ### The mobile devices associated with this user
+    ###
+    ### Each Hash has then :id and :name for one device
+    ###
+    ### @note This data is currently broken - the JSON output of the API only
+    ### returns one mobile device, and it isn't formatted in a standard way.
+    ###
+    attr_reader :mobile_devices
+
+    ### @return [Array<Hash>]
+    ###
+    ### The vpp assignments associated with this user
+    ###
+    ### Each Hash has then :id and :name for one assignment
+    ###
+    attr_reader :vpp_assignments
+
+    ### @return [Integer] the total number of vpp codes assigned to this user
+    attr_reader :total_vpp_code_count
+
+    #####################################
+    ### Constructor
+    #####################################
+
+    ###
+    ### See JSS::APIObject#initialize
+    ###
+    def initialize (args = {})
+      super
+
+      @full_name = @init_data[:full_name]
+      @email = @init_data[:email]
+      @phone_number = @init_data[:phone_number]
+      @position = @init_data[:position]
+      @ldap_server = JSS::APIObject.get_name @init_data[:ldap_server]
+      @sites = @init_data[:sites] ? @init_data[:sites]  : []
+
+      if @init_data[:links]
+        @computers = @init_data[:links][:computers]
+        @peripherals = @init_data[:links][:peripherals]
+        @mobile_devices = @init_data[:links][:mobile_devices]
+        @vpp_assignments = @init_data[:links][:vpp_assignments]
+        @total_vpp_code_count = @init_data[:links][:total_vpp_code_count]
+      end
+
+      parse_ext_attrs
+    end
+
+    #####################################
+    ### Public Instance Methods
+    #####################################
+
+
+    ###
+    ### Simple Setters
+    ###
+
+    ###
+    def full_name= (new_val)
+      @full_name = new_val
+      @need_to_update = true
+    end
+
+    ###
+    def email= (new_val)
+      @email = new_val
+      @need_to_update = true
+    end
+
+    ###
+    def phone_number= (new_val)
+      @phone_number = new_val
+      @need_to_update = true
+    end
+
+    ###
+    def position= (new_val)
+      @position = new_val
+      @need_to_update = true
+    end
+
+    ###
+    def ldap_server= (new_val)
+      raise JSS::InvalidDataError, "No LDAP server in the JSS named #{new_val}" unless JSS::LDAPServer.all_names.include? new_val
+      @ldap_server = new_val
+      @need_to_update = true
+    end
+
+    ###
+    ### Add this user to a site
+    ###
+    ### @param site[String] the name of the site
+    ###
+    ### @return [void]
+    ###
+    def add_site (site)
+      return nil if @sites.map{|s| s[:name]}.include? site
+      raise JSS::InvalidDataError, "No site in the JSS named #{site}" unless JSS::Site.all_names.include? site
+      @sites << {:name => site}
+      @need_to_update = true
+    end
+
+    ###
+    ### Remove this user from a site
+    ###
+    ### @param site[String] the name of the site
+    ###
+    ### @return [void]
+    ###
+    def remove_site (site)
+      return nil unless @sites.map{|s| s[:name]}.include? site
+      @sites.reject!{|s| s[:name] == site}
+      @need_to_update = true
+    end
+
+
+    #####################################
+    ### Private Instance Methods
+    #####################################
+    private
+
+    def rest_xml
+      doc = REXML::Document.new APIConnection::XML_HEADER
+      user = doc.add_element self.class::RSRC_OBJECT_KEY.to_s
+
+      user.add_element('name').text = @name
+      user.add_element('full_name').text = @full_name
+      user.add_element('email').text = @email
+      user.add_element('phone_number').text = @phone_number
+      user.add_element('position').text = @position
+
+      ldap = user.add_element('ldap_server')
+      ldap.add_element('name').text = @ldap_server
+
+      user << JSS::Site.xml_list(@sites)
+
+      user << ext_attr_xml
+
+      return doc.to_s
+    end
+
+  end # class user
+
+end # module