viewpoint-spws 0.5.0

data/lib/viewpoint/spws/spws_client.rb

@@ -0,0 +1,107 @@
+=begin
+  This file is part of ViewpointSPWS; the Ruby library for Microsoft Sharepoint Web Services.
+
+  Copyright © 2011 Dan Wanek <dan.wanek@gmail.com>
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+=end
+
+# This class is the glue between the Models and the Web Service.
+class Viewpoint::SPWSClient
+  include Viewpoint::SPWS
+
+  # Initialize the SPWSClient instance.
+  # @param [String] endpoint The SPWS endpoint we will be connecting to
+  # @param [String] user The user to authenticate as. If you are using
+  #   NTLM or Negotiate authentication you do not need to pass this parameter.
+  # @param [String] pass The user password. If you are using NTLM or
+  #   Negotiate authentication you do not need to pass this parameter.
+  def initialize(endpoint, user = nil, pass = nil)
+    @con = Connection.new(endpoint)
+    @con.set_auth(user,pass) if(user && pass)
+  end
+
+  def copy_ws
+    @copyws ||= Websvc::Copy.new(@con)
+  end
+
+  def lists_ws
+    @listsws ||= Websvc::Lists.new(@con)
+  end
+
+  def usergroup_ws
+    @usergroupws ||= Websvc::UserGroup.new(@con)
+  end
+
+
+  # ========= List Accessor Proxy Methods ========= 
+
+  # Available list types that can be used for #add_list
+  LIST_TYPES = {
+    :custom_list      => 100,
+    :document_library => 101,
+    :survey           => 102,
+    :links            => 103,
+    :announcements    => 104,
+    :contacts         => 105,
+    :events           => 106,
+    :tasks            => 107,
+    :discussion_board => 108,
+    :picture_library  => 109,
+    :datasources      => 110,
+    :form_library     => 115,
+    :issues           => 1100,
+    :custom_list_for_datasheet => 120,
+  }
+
+  # Retrieve all of the viewable lists for this site.
+  def get_lists
+    lists_ws.get_list_collection
+  end
+
+  # Retrieve a List object
+  # @param [String] list title or the GUID for the list
+  def get_list(list)
+    lists_ws.get_list(list)
+  end
+
+  # Add a List to this site
+  # @param [String] name A name for the List
+  # @param [String] desc A description of the List
+  # @param [Integer] list_type The list template id. Use the LIST_TYPES Hash.
+  def add_list(name, desc, list_type)
+    lists_ws.add_list(name, desc, list_type)
+  end
+
+  # Delete a list from this site.
+  # @param [String] list title or the GUID for the list
+  def delete_list(list)
+    lists_ws.delete_list(list)
+  end
+
+  # ========= UserGroup Accessor Proxy Methods ========= 
+
+  # Retrieve a user by e-mail
+  # @param [String] user either in e-mail form or DOMAIN\login form. If you
+  #   specify an e-mail there is an additional web service call that needs
+  #   to be made so if you're worried about performance use the DOMAIN\login
+  #   form.
+  # @return [Viewpoint::SPWS::Types::User]
+  def get_user(user)
+    if user =~ /@/
+      ulh = usergroup_ws.get_user_login_from_email [user]
+      user = ulh[user]
+    end
+    usergroup_ws.get_user_info user
+  end
+end

data/lib/viewpoint/spws/types.rb

@@ -0,0 +1,27 @@
+=begin
+  This file is part of ViewpointSPWS; the Ruby library for Microsoft Sharepoint Web Services.
+
+  Copyright © 2011 Dan Wanek <dan.wanek@gmail.com>
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+=end
+
+module Viewpoint::SPWS
+  module Types
+    PRIORITY  = {:high => '(1) High', :normal => '(2) Normal', :low => '(3) Low'}.freeze
+
+    STATUS    = {:not_started => 'Not Started', :in_progress => 'In Progress',
+      :completed => 'Completed', :deferred => 'Deferred',
+      :waiting => 'Waiting on someone else'}.freeze
+  end
+end

data/lib/viewpoint/spws/types/document_library.rb

@@ -0,0 +1,41 @@
+=begin
+  This file is part of ViewpointSPWS; the Ruby library for Microsoft Sharepoint Web Services.
+
+  Copyright © 2011 Dan Wanek <dan.wanek@gmail.com>
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+=end
+
+# This class represents a Sharepoint List returned from the Lists Web Service with a
+# ServerTemplate id of 101 (DocumentLibrary).
+# @see http://msdn.microsoft.com/en-us/library/ms774810(v=office.12).aspx
+class Viewpoint::SPWS::Types::DocumentLibrary < Viewpoint::SPWS::Types::List
+  include Viewpoint::SPWS::Types
+
+  # @param [Viewpoint::SPWS::Websvc::List] ws The webservice instance this List spawned from
+  # @param [Nokogiri::XML::Element] xml the List element we are building from
+  def initialize(ws, xml)
+    @copy_ws = Viewpoint::SPWS::Websvc::Copy.new(ws.spcon)
+    super
+  end
+
+  # Add a Document to this List
+  # @param [Hash] opts parameters for this Document
+  # @option opts [String] :file Path to the file to upload
+  # @return [Viewpoint::SPWS::Types::ListItem] The newly added Task
+  def add_file!(opts)
+    raise "Valid file argument required" unless(opts[:file] && File.exists?(opts[:file]))
+    fqpath = "#{self.path}/#{File.basename(opts[:file])}"
+    @copy_ws.copy_into_items(opts[:file], [fqpath])
+  end
+end

data/lib/viewpoint/spws/types/list.rb

@@ -0,0 +1,107 @@
+=begin
+  This file is part of ViewpointSPWS; the Ruby library for Microsoft Sharepoint Web Services.
+
+  Copyright © 2011 Dan Wanek <dan.wanek@gmail.com>
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+=end
+
+# This class represents a Sharepoint List returned from the Lists Web Service
+# @see http://msdn.microsoft.com/en-us/library/ms774810(v=office.12).aspx
+class Viewpoint::SPWS::Types::List
+  include Viewpoint::SPWS::Types
+
+  attr_reader :guid, :title, :description, :created, :modified, :server_template,
+    :feature_id, :root_folder
+
+  # @param [Viewpoint::SPWS::Websvc::List] ws The webservice instance this List spawned from
+  # @param [Nokogiri::XML::Element] xml the List element we are building from
+  def initialize(ws, xml)
+    @ws             = ws
+    @guid           = xml['ID']
+    @title          = xml['Title']
+    @description    = xml['Description']
+    @hidden         = (xml['Hidden'] == 'True')
+    @created        = DateTime.parse(xml['Created'])
+    @modified       = DateTime.parse(xml['Modified'])
+    @last_deleted   = DateTime.parse(xml['LastDeleted'])
+    @item_count     = xml['ItemCount']
+    @server_template= xml['ServerTemplate'].to_i
+    @feature_id     = xml['FeatureId']
+    @root_folder    = xml['RootFolder']
+    #@xmldoc         = xml
+    @list_path      = nil
+  end
+
+  # Return the full-qualified path of this List
+  def path
+    return @list_path if @list_path
+    site = @ws.spcon.site_base
+    @list_path = "#{site.scheme}://#{site.host}"
+    @list_path << ":#{site.port}" unless(site.port == 80 || site.port == 443)
+    @list_path << @root_folder
+  end
+
+  # Add a ListItem
+  # @param [Hash] opts options for List creation.
+  def add_item!(opts)
+    op = { :command => 'New', :id => 'New' }
+    opts.keys.each do |k|
+      case k
+      when :priority
+        op[k] = PRIORITY[opts[:priority]]
+      when :status
+        op[k] = STATUS[opts[:status]]
+      when :percent_complete
+        op[k] = opts[k] * 0.01
+      else
+        op[k] = opts[k]
+      end
+    end
+
+    resp = @ws.update_list_items(@guid, :item_updates => [op])
+    resp[:new].first
+  end
+
+  # Delete this List
+  def delete!
+    @ws.delete_list(@guid)
+  end
+
+  # Return the items in this List
+  def items
+    @ws.get_list_items(@guid)
+  end
+
+  # @param [String] item_id The item id for the item you want to retrieve
+  def get_item(item_id)
+    addl_fields = %w{LinkTitle Body AssignedTo Status Priority DueDate PercentComplete}
+
+    i = @ws.get_list_items(@guid, :recursive => true, :view_fields => addl_fields) do |b|
+      b.Query {
+        b.Where {
+          b.Eq {
+            b.FieldRef(:Name => 'ID')
+            b.Value(item_id, :Type => 'Counter')
+          }
+        }
+      }
+    end
+    raise "Returned more than one item for #get_item" if(i.length > 1)
+    i.first
+  end
+
+  def hidden?
+    @hidden
+  end
+end

data/lib/viewpoint/spws/types/list_item.rb

@@ -0,0 +1,248 @@
+=begin
+  This file is part of ViewpointSPWS; the Ruby library for Microsoft Sharepoint Web Services.
+
+  Copyright © 2011 Dan Wanek <dan.wanek@gmail.com>
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+=end
+
+# This class represents a Sharepoint ListItem returned from the Lists Web Service
+# @see 
+class Viewpoint::SPWS::Types::ListItem
+  include Viewpoint::SPWS::Types
+
+  attr_reader :id, :body, :file_name, :file_ref, :editor, :guid, :object_type
+  attr_reader :created_date, :modified_date, :due_date
+  attr_reader :title, :link_title, :status, :priority, :percent_complete
+
+  # @param [Viewpoint::SPWS::Websvc::List] ws The webservice instance this ListItem spawned from
+  # @param [String] list_id The list id that this item belongs to
+  # @param [Nokogiri::XML::Element] xml the List element we are building from
+  def initialize(ws, list_id, xml)
+    @ws = ws
+    @list_id = list_id
+    @pending_updates  = [] # a place to store updates before #save! is called
+    @update_keys      = {} # the variables to update after #save!
+    parse_xml_fields(xml)
+  end
+
+  # Save any pending changes
+  def save!
+    return true if @pending_updates.empty?
+    resp = @ws.update_list_items(@list_id, :item_updates => @pending_updates)
+    # @todo check for success before emptying Arry
+    update_local_vars resp[:update][0]
+    @pending_updates.clear
+    true
+    resp
+  end
+
+  # Pass a block of updates that will be committed in one transaction
+  # @example
+  #   li.update! do |l|
+  #     l.rename 'New Name'
+  #     l.set_priority :low
+  #     l.set_status :waiting
+  #   end
+  def update!
+    yield self if block_given?
+    save!
+  end
+
+  # Delete this ListItem
+  def delete!
+    del = [{ :id => @id, :command => 'Delete',
+      :file_ref => full_file_ref }]
+    @ws.update_list_items(@list_id, :item_updates => del)
+  end
+
+
+  # Set a new title for this Item
+  # @param [String] title The new title
+  def rename(title)
+    raise "There is already a pending rename" if @update_keys[:@title]
+    upd = { :id => @id, :command => 'Update',
+      :title => title,
+    }
+    @pending_updates << upd
+    @update_keys[:@title]       = 'ows_Title'
+    @update_keys[:@link_title]  = 'ows_LinkTitle'
+    title
+  end
+
+  # Set a new title for this Item
+  # @see #rename
+  def rename!(title)
+    rename(title)
+    save!
+  end
+
+  # Set the priority of this Item
+  # @param [Symbol] priority The new priority. It must be one of these values:
+  #   :high, :normal, :low
+  def set_priority(priority)
+    raise "Invalid priority it must be one of: #{PRIORITY.keys.join(', ')}" unless PRIORITY[priority]
+    raise "There is already a pending priority change" if @update_keys[:@priority]
+    upd = { :id => @id, :command => 'Update',
+      :priority => PRIORITY[priority],
+    }
+    @pending_updates << upd
+    @update_keys[:@priority] = 'ows_Priority'
+    priority
+  end
+
+  # Set the priority of this Item
+  # @see #set_priority
+  def set_priority!(priority)
+    set_priority priority
+    save!
+  end
+
+  # Set the status of this Item
+  # @param [Symbol] status The new status. It must be one of these values:
+  #   :not_started, :in_progress, :completed, :deferred, :waiting
+  def set_status(status)
+    raise "Invalid status it must be one of: #{STATUS.keys.join(', ')}" unless STATUS[status]
+    raise "There is already a pending status change" if @update_keys[:@status]
+    upd = { :id => @id, :command => 'Update',
+      :status => STATUS[status],
+    }
+    @pending_updates << upd
+    @update_keys[:@status] = 'ows_Status'
+    status
+  end
+
+  # Set the status of this Item
+  # @see #set_status
+  def set_status!(status)
+    set_status(status)
+    save!
+  end
+
+  # Set the percentage complete of this item.
+  # @param [Fixnum] pct the percent complete of this item
+  def set_percent_complete(pct)
+    if(!(0..100).include?(pct))
+      raise "Invalid :percent_complete #{topts[:percent_complete]}"
+    end
+    raise "There is already a pending percent complete change" if @update_keys[:@percent_complete]
+
+    upd = { :id => @id, :command => 'Update',
+      :percent_complete => pct,
+    }
+    @pending_updates << upd
+    @update_keys[:@percent_complete] = 'ows_PercentComplete'
+    pct
+  end
+
+  # Set the percentage complete of this item.
+  # @see #set_percent_complete
+  def set_percent_complete!(pct)
+    set_percent_complete pct
+    save!
+  end
+
+  # Assign this item to a user
+  # @param [Viewpoint::SPWS::Types::User] user The user to assign this ListItem
+  # @todo should I return the String representation of the user or the Types::User?
+  def assign(user)
+    raise "There is already a pending assignment" if @update_keys[:@assigned_to]
+    upd = { :id => @id, :command => 'Update',
+      :AssignedTo => "#{user.id};##{user.login_name}",
+    }
+    @pending_updates << upd
+    @update_keys[:@assigned_to] = 'ows_AssignedTo'
+    user
+  end
+
+  # Assign this item to a user
+  # @see #assign
+  def assign!(user)
+    assign(user)
+    save!
+  end
+
+  private
+
+  # Return the full FileRef with the site URL attatched
+  def full_file_ref
+    uri =  @ws.spcon.site_base
+    url = "#{uri.scheme}://#{uri.host}"
+    url << ":#{uri.port}" unless (uri.port == 80 || uri.port == 443)
+    url << "/#{@file_ref}"
+  end
+
+  # update the local variables after a #save!.
+  # Changed variables are tracked in @update_keys
+  # @param [Hash] resp The response Hash from a #save!
+  def update_local_vars(resp)
+    @update_keys.each_pair do |k,v|
+      set_field k, v, resp
+    end
+    @update_keys.clear
+  end
+
+  # Parse the fields out of the passed XML document.
+  # @param[Nokogiri::XML::Element] xml
+  def parse_xml_fields(xml)
+    @xmldoc = xml
+    set_field   :@id, 'ows_ID'
+    set_field   :@file_name, 'ows_LinkFilename'
+    set_field   :@meta_info, 'ows_MetaInfo'
+    set_field   :@link_title, 'ows_LinkTitle'
+    set_field   :@body, 'ows_Body'
+    set_field   :@title, 'ows_Title'
+    set_field   :@status, 'ows_Status'
+    set_field   :@priority, 'ows_Priority'
+    set_field   :@percent_complete, 'ows_PercentComplete'
+    set_field   :@due_date, 'ows_DueDate'
+    set_field   :@assigned_to, 'ows_AssignedTo'
+    set_field   :@file_ref, 'ows_FileRef'
+    set_field   :@editor, 'ows_Editor'
+    set_field   :@guid, 'ows_UniqueId'
+    set_field   :@object_type, 'ows_FSObjType'
+    set_field   :@created_date, 'ows_Created'
+    set_field   :@modified_date, 'ows_Modified'
+    set_field   :@created_date, 'ows_Created_x0020_Date' unless @created_date
+    set_field   :@modified_date, 'ows_Last_x0020_Modified' unless @modified_date
+    @xmldoc = nil
+  end
+
+  # Parse a Sharepoint field or managed field
+  # @param [Symbol] vname The instance variable we will set the value to if it exists
+  # @param [String] fname The field name to check for
+  # @param [#[]] mapsrc A dictionary or Hash like item that contains variable data.
+  def set_field(vname, fname, mapsrc = @xmldoc)
+    newvar = nil
+    field = mapsrc[fname]
+    if field
+      if(field =~ /;#/)
+        newvar = mapsrc[fname].split(';#').last
+      else
+        newvar = field
+      end
+      newvar = transform(newvar)
+    end
+    instance_variable_set vname, newvar
+  end
+
+  # Run misc transforms on data
+  def transform(newvar)
+    case newvar
+    when /[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}/ # Transform DateTime
+      return DateTime.parse(newvar)
+    else
+      return newvar
+    end
+  end
+end