Class: Viewpoint::SPWS::Websvc::Lists

# File 'lib/viewpoint/spws/websvc/lists.rb', line 24

def initialize(spcon)
  @default_ns  = 'http://schemas.microsoft.com/sharepoint/soap/'
  @ws_endpoint = '_vti_bin/Lists.asmx'
  super
end

Instance Method Details

#add_list(name, desc, templ_id) ⇒ `Viewpoint::SPWS::List`

Add a List to this site.

Parameters:

name (String) —

A name for the List
desc (String) —

A description of the List
templ_id (Integer) —

The template type for this List. See the Microsoft docs for additional information.

Returns:

(Viewpoint::SPWS::List) —

The new List object

See Also:

http://msdn.microsoft.com/en-us/library/lists.lists.addlist(v=office.12).aspx

# File 'lib/viewpoint/spws/websvc/lists.rb', line 37

def add_list(name, desc, templ_id)
  soapmsg = build_soap_envelope do |type, builder|
    if(type == :header)
    else
      builder.AddList {
        builder.parent.default_namespace = @default_ns
        builder.listName(name)
        builder.description(desc)
        builder.templateID(templ_id)
      }
    end
  end
  soaprsp = Nokogiri::XML(send_soap_request(soapmsg.doc.to_xml))
  return soaprsp
  ns = {"xmlns"=> @default_ns}
  new_list(soaprsp.xpath('//xmlns:AddListResult/xmlns:List', ns).first)
end

#add_list_from_feature(name, desc, feature_id, templ_id) ⇒ `Viewpoint::SPWS::List`

Add a List to this site from a feature ID.

Parameters:

name (String) —

A name for the List
desc (String) —

A description of the List
feature_id (String) —

The GUID of the feature ID.
templ_id (Integer) —

The template type for this List. See the Microsoft docs for additional information.

Returns:

(Viewpoint::SPWS::List) —

The new List object

See Also:

http://msdn.microsoft.com/en-us/library/lists.lists.addlistfromfeature(v=office.12).aspx

# File 'lib/viewpoint/spws/websvc/lists.rb', line 63

def add_list_from_feature(name, desc, feature_id, templ_id)
  soapmsg = build_soap_envelope do |type, builder|
    if(type == :header)
    else
      builder.AddListFromFeature {
        builder.parent.default_namespace = @default_ns
        builder.listName(name)
        builder.description(desc)
        builder.featureID(feature_id)
        builder.templateID(templ_id)
      }
    end
  end
  soaprsp = Nokogiri::XML(send_soap_request(soapmsg.doc.to_xml))
  ns = {"xmlns"=> @default_ns}
  new_list(soaprsp.xpath('//xmlns:AddListResult/xmlns:List', ns).first)
end

#delete_list(name) ⇒ `Object`

TODO:

Work out the return value

Delete a list from this site.

Parameters:

name (String) —

Either the name or the GUID of the list

# File 'lib/viewpoint/spws/websvc/lists.rb', line 84

def delete_list(name)
  soapmsg = build_soap_envelope do |type, builder|
    if(type == :header)
    else
      builder.DeleteList {
        builder.parent.default_namespace = @default_ns
        builder.listName(name)
      }
    end
  end
  soaprsp = Nokogiri::XML(send_soap_request(soapmsg.doc.to_xml))
  #ns = {"xmlns"=> @default_ns}
end

#get_file(file_ref) ⇒ `String`

Retrieve a file from Sharepoint. This is not a standard Web Service method, buth rather a convenience method that is part of ViewpointSPWS.

Examples:

resp = listws.get_file(listitem.file_ref)
File.open(listitem.file_name,'w+') do |f|
  f.write(resp)
end

Parameters:

file_ref (String) —

The fileref property from a ListItem object

Returns:

(String) —

A String representing the bytestream of a file. You should be able to write it out to a file with something like this:

# File 'lib/viewpoint/spws/websvc/lists.rb', line 426

def get_file(file_ref)
  p1 = Pathname.new @spcon.site_base.request_uri
  p2 = Pathname.new "/#{file_ref}"
  target = p2.relative_path_from p1
  @spcon.get(target.to_s)
end

#get_list(list) ⇒ `Viewpoint::SPWS::List`

Retrieve a specific Sharepoint List

Parameters:

list (String) —

title or the GUID for the list

Returns:

(Viewpoint::SPWS::List)

See Also:

http://msdn.microsoft.com/en-us/library/lists.lists.getlist(v=office.12).aspx

# File 'lib/viewpoint/spws/websvc/lists.rb', line 148

def get_list(list)
  soapmsg = build_soap_envelope do |type, builder|
    if(type == :header)
    else
      builder.GetList {
        builder.parent.default_namespace = @default_ns
        builder.listName(list)
      }
    end
  end
  soaprsp = Nokogiri::XML(send_soap_request(soapmsg.doc.to_xml))
  ns = {"xmlns"=> @default_ns}
  new_list(soaprsp.xpath('//xmlns:GetListResult/xmlns:List', ns).first)
end

#get_list_collection(show_hidden = false) ⇒ `Object`

Returns all the lists for a Sharepoint site.

Parameters:

show_hidden (Boolean) (defaults to: false) —

Whether or not to show hidden lists. Default = false

See Also:

http://msdn.microsoft.com/en-us/library/lists.lists.getlistcollection(v=office.12).aspx

# File 'lib/viewpoint/spws/websvc/lists.rb', line 121

def get_list_collection(show_hidden = false)
  soapmsg = build_soap_envelope do |type, builder|
    if(type == :header)
    else
      builder.GetListCollection {
        builder.parent.default_namespace = @default_ns
      }
    end
  end
  soaprsp = Nokogiri::XML(send_soap_request(soapmsg.doc.to_xml))
  ns = {"xmlns"=> @default_ns}
  lists = []
  soaprsp.xpath('//xmlns:Lists/xmlns:List', ns).each do |l|
    lists << new_list(l)
  end
  if(!show_hidden)
    lists.reject! do |i|
      i.hidden?
    end
  end
  lists
end

#get_list_content_types(name, content_type_id = nil) ⇒ `Object`

TODO:

Work out the return value

Returns a collection of content type definition schemas

Parameters:

name (String) —

Either the name or the GUID of the list
content_type_id (String) (defaults to: nil) —

(nil) The content type ID. I’m still not clear on what specifying this value does. In my limitted testing it does not seem to have an effect on the output.

See Also:

http://msdn.microsoft.com/en-us/library/lists.lists.getlistcontenttypes(v=office.12).aspx

# File 'lib/viewpoint/spws/websvc/lists.rb', line 104

def get_list_content_types(name, content_type_id = nil)
  soapmsg = build_soap_envelope do |type, builder|
    if(type == :header)
    else
      builder.GetListContentTypes {
        builder.parent.default_namespace = @default_ns
        builder.listName(name)
        builder.contentTypeId(content_type_id)
      }
    end
  end
  soaprsp = Nokogiri::XML(send_soap_request(soapmsg.doc.to_xml))
end

#get_list_item_changes_since_token(list, token = nil, opts = {}) {|builder| ... } ⇒ `Hash`

Get List Items changes from a given change token

Examples:

The following example shows how to prepare a CAML Query with a block. It filters for all objects of ObjectType ‘0’ = Files

items = listws.get_list_items('Shared Documents',:recursive => true) do |b|
  b.Query {
    b.Where {
      b.Eq {
        b.FieldRef(:Name => 'FSObjType')
        b.Value(0, :Type => 'Integer')
      }
    }
  }
end

Parameters:

list (String) —

title or the GUID for the list
token (String) (defaults to: nil) —

(nil) The change token or nil to get all
opts (Hash) (defaults to: {})

Options Hash (opts):

:view_name (String) — default: '' —

GUID for the view surrounded by curly braces If nothing is passed it used the default of the View
:row_limit (String) — default: '' —

A String representing the number of rows to return.
:recursive (Boolean) — default: true —

If true look in subfolders as well as root
:date_in_utc (Boolean) — default: true —

If true return dates in UTC
:folder (String) — default: '' —

Filter document library items for items in the specified folder

Yields:

(builder) —

Yields a Builder object that can be used to build a CAML Query. See the example on how to use it.

Yield Parameters:

builder (Nokogiro::XML::Builder) —

The builder object used to create the Query

Returns:

(Hash) —

returns a Hash with the keys :last_change_token, which contains a String that holds a change token that may be used in subsequent calls, and :items which holds an Array of ListItem objects.

See Also:

http://msdn.microsoft.com/en-us/library/lists.lists.getlistitemchangessincetoken(v=office.12).aspx

# File 'lib/viewpoint/spws/websvc/lists.rb', line 277

def get_list_item_changes_since_token(list, token=nil, opts = {})
  # Set Default values
  opts[:recursive] = true unless opts.has_key?(:recursive)
  opts[:view_name] = '' unless opts.has_key?(:view_name)
  opts[:row_limit] = '' unless opts.has_key?(:row_limit)
  opts[:date_in_utc] = true unless opts.has_key?(:date_in_utc)
  opts[:folder] = '' unless opts.has_key?(:folder)

  soapmsg = build_soap_envelope do |type, builder|
    if(type == :header)
    else
      builder.GetListItemChangesSinceToken {
        builder.parent.default_namespace = @default_ns
        builder.listName(list)
        builder.viewName(opts[:view_name])
        builder.rowLimit(opts[:row_limit])

        if block_given?
          builder.query {
            builder.parent.default_namespace = ''
            yield builder
          }
        end

        builder.queryOptions {
          builder.QueryOptions {
            builder.parent.default_namespace = ''
            builder.Folder(opts[:folder])
            builder.ViewAttributes(:Scope => 'Recursive') if opts[:recursive]
            builder.DateInUtc('True') if opts[:date_in_utc]
            builder.IncludeAttachmentUrls('True')
          }
        }

        builder.changeToken(token)
        # @todo Is this worth supporting???
        #builder.contains()
      }
    end
  end
  soaprsp = Nokogiri::XML(send_soap_request(soapmsg.doc.to_xml))
  ns = {'xmlns:z' => "#RowsetSchema",
       'xmlns:rs' => "urn:schemas-microsoft-com:rowset",
       'xmlns'    => @default_ns,
  }
  items = []
  soaprsp.xpath('//rs:data/z:row', ns).each do |li|
    items << Types::ListItem.new(self, list, li)
  end
  changes = soaprsp.xpath('//xmlns:GetListItemChangesSinceTokenResult/xmlns:listitems/xmlns:Changes',ns).first
  {:last_change_token => changes['LastChangeToken'], :items => items}
end

#get_list_items(list, opts = {}) {|builder| ... } ⇒ `Object`

Get List Items based on certain parameters

Examples:

The following example shows how to prepare a CAML Query with a block. It filters for all objects of ObjectType ‘0’ = Files

items = listws.get_list_items('Shared Documents',:recursive => true) do |b|
  b.Query {
    b.Where {
      b.Eq {
        b.FieldRef(:Name => 'FSObjType')
        b.Value(0, :Type => 'Integer')
      }
    }
  }
end

Parameters:

list (String) —

title or the GUID for the list
opts (Hash) (defaults to: {})

Options Hash (opts):

:view_name (String) — default: '' —

GUID for the view surrounded by curly braces If nothing is passed it used the default of the View
:row_limit (String) — default: '' —

A String representing the number of rows to return.
:recursive (Boolean) — default: true —

If true look in subfolders as well as root
:date_in_utc (Boolean) — default: true —

If true return dates in UTC
:folder (String) — default: '' —

Filter document library items for items in the specified folder
:view_fields (Array<String,Symbol>) —

and array of String or Symbols that represent which fields to return with the query.

Yields:

(builder) —

Yields a Builder object that can be used to build a CAML Query. See the example on how to use it.

Yield Parameters:

builder (Nokogiro::XML::Builder) —

The builder object used to create the Query

See Also:

http://msdn.microsoft.com/en-us/library/lists.lists.getlistitems(v=office.12).aspx

# File 'lib/viewpoint/spws/websvc/lists.rb', line 190

def get_list_items(list, opts = {})
  # Set Default values
  opts[:recursive] = true unless opts.has_key?(:recursive)
  opts[:view_name] = '' unless opts.has_key?(:view_name)
  opts[:row_limit] = '' unless opts.has_key?(:row_limit)
  opts[:date_in_utc] = true unless opts.has_key?(:date_in_utc)
  opts[:folder] = '' unless opts.has_key?(:folder)

  soapmsg = build_soap_envelope do |type, builder|
    if(type == :header)
    else
      builder.GetListItems {
        builder.parent.default_namespace = @default_ns
        builder.listName(list)
        builder.viewName(opts[:view_name])
        builder.rowLimit(opts[:row_limit])

        if block_given?
          builder.query {
            builder.parent.default_namespace = ''
            yield builder
          }
        end

        if(opts[:view_fields])
          builder.viewFields {
            builder.ViewFields {
              builder.parent.default_namespace = ''
              opts[:view_fields].each do |f|
                builder.FieldRef(:Name => f.to_s.camel_case)
              end
            }
          }
        end

        builder.queryOptions {
          builder.QueryOptions {
            builder.parent.default_namespace = ''
            builder.Folder(opts[:folder])
            builder.ViewAttributes(:Scope => 'Recursive') if opts[:recursive]
            builder.DateInUtc('True') if opts[:date_in_utc]
            builder.IncludeAttachmentUrls('True')
          }
        }
        # @todo Is this worth supporting???
        #builder.webID(parms[:web_id])
      }
    end
  end
  soaprsp = Nokogiri::XML(send_soap_request(soapmsg.doc.to_xml))
  ns = {'xmlns:z' => "#RowsetSchema"}
  items = []
  soaprsp.xpath('//z:row', ns).each do |li|
    items << Types::ListItem.new(self, list, li)
  end
  items
end

#update_list_items(list, updates = {}) {|builder| ... } ⇒ `Object`

Adds, deletes, or updates the specified items in a list

Examples:

The following example shows how to prepare a Batch request with a block. It updates a Task item to Status ‘Completed’.

item_id = 95
listws.update_list_items('Task List') do |b|
  b.Method(:ID => 1, :Cmd => 'Update') do
    b.Field(item_id,:Name => 'ID')
    b.Field("Completed", :Name => 'Status')
  end
end

How to Add and Delete via passed parameters

updates = [
  {:id => "New", :command => "New", :title => "Test Task"},
  {:id => 'New',:command => 'New', :title => 'Test Task 2'},
  {:id => 98,:command => 'Delete'},
]
resp = listws.update_list_items('Task List',:item_updates => updates)

Parameters:

list (String) —

title or the GUID for the list
updates (Hash) (defaults to: {})

Options Hash (updates):

:view_name (String) — default: '' —

GUID for the view without curly braces If nothing is passed it used the default of the View
:on_error (String) — default: 'Continue' —

What to do if an error ocurrs. It must be either ‘Return’ or ‘Contiue’
:list_version (String) — default: '' —

The version of the list we wish to modify
:version (String) — default: '' —

The version of Sharepoint we are acting on
:item_updates (Array<Hash>) —
An array of Hashes that specify what to update. Each hash needs an :id key to specify the item ID and a :command key that specifies “New”, “Update” or “Delete”. All other keys are field names in either CamelCase or ruby_case with values to set them to. =>
```
[{:id => 95, :command => 'Update', :status => 'Completed',
=> 107, :command => 'Update', :title => "Test"]}
```

Yields:

(builder) —

Yields a Builder object that can be used to build a Batch request. See the example on how to use it. For more information on Batch requests: @see msdn.microsoft.com/en-us/library/dd585784(v=office.11).aspx

Yield Parameters:

builder (Nokogiro::XML::Builder) —

The builder object used to create the Batch

See Also:

http://msdn.microsoft.com/en-us/library/lists.lists.updatelistitems(v=office.12).aspx
Operation http://msdn.microsoft.com/en-us/library/ms437562(v=office.12).aspx

# File 'lib/viewpoint/spws/websvc/lists.rb', line 367

def update_list_items(list, updates = {})
  # Set Default values
  updates[:view_name] = '' unless updates.has_key?(:view_name)
  updates[:on_error] = 'Continue' unless updates.has_key?(:on_error)
  updates[:list_version] = '' unless updates.has_key?(:list_version)
  updates[:version] = '' unless updates.has_key?(:version)

  soapmsg = build_soap_envelope do |type, builder|
    if(type == :header)
    else
      builder.UpdateListItems {
        builder.parent.default_namespace = @default_ns
        builder.listName(list)

        builder.updates {
          builder.Batch(:ViewName => updates[:view_name],
                        :OnError  => updates[:on_error],
                        :ListVersion  => updates[:list_version],
                        :Version  => updates[:version]) {
            builder.parent.default_namespace = ''

            # First format passed item_updates
            updates[:item_updates] && updates[:item_updates].each_with_index do |iu,idx|
              iu = iu.clone
              builder.Method(:ID => "VP_IDX#{idx}", :Cmd => iu.delete(:command)) do
                builder.Field(iu.delete(:id), :Name => 'ID')
                iu.each_pair do |k,v|
                  builder.Field(v, :Name => k.to_s.camel_case)
                end
              end
            end

            # Now include block-passed updates
            if block_given?
              yield builder
            end
          }
        }
      }
    end
  end

  soaprsp = Nokogiri::XML(send_soap_request(soapmsg.doc.to_xml))
  parse_update_list_items(list, soaprsp)
end

Class: Viewpoint::SPWS::Websvc::Lists

Overview

Constant Summary

Constants included from WebServiceBase

Constants included from Viewpoint::SPWS

Instance Attribute Summary

Attributes included from WebServiceBase

Attributes included from Viewpoint::SPWS

Instance Method Summary collapse

Methods included from Viewpoint::SPWS

Constructor Details

#initialize(spcon) ⇒ Lists

Instance Method Details

#add_list(name, desc, templ_id) ⇒ Viewpoint::SPWS::List

#add_list_from_feature(name, desc, feature_id, templ_id) ⇒ Viewpoint::SPWS::List

#delete_list(name) ⇒ Object

#get_file(file_ref) ⇒ String

#get_list(list) ⇒ Viewpoint::SPWS::List

#get_list_collection(show_hidden = false) ⇒ Object

#get_list_content_types(name, content_type_id = nil) ⇒ Object

#get_list_item_changes_since_token(list, token = nil, opts = {}) {|builder| ... } ⇒ Hash

#get_list_items(list, opts = {}) {|builder| ... } ⇒ Object

#update_list_items(list, updates = {}) {|builder| ... } ⇒ Object

#initialize(spcon) ⇒ `Lists`

#add_list(name, desc, templ_id) ⇒ `Viewpoint::SPWS::List`

#add_list_from_feature(name, desc, feature_id, templ_id) ⇒ `Viewpoint::SPWS::List`

#delete_list(name) ⇒ `Object`

#get_file(file_ref) ⇒ `String`

#get_list(list) ⇒ `Viewpoint::SPWS::List`

#get_list_collection(show_hidden = false) ⇒ `Object`

#get_list_content_types(name, content_type_id = nil) ⇒ `Object`

#get_list_item_changes_since_token(list, token = nil, opts = {}) {|builder| ... } ⇒ `Hash`

#get_list_items(list, opts = {}) {|builder| ... } ⇒ `Object`

#update_list_items(list, updates = {}) {|builder| ... } ⇒ `Object`