How to: Automate List Addition

  • Article

In order to function properly, your solution might require the addition of a list to your customer’s Microsoft Office Live Small Business subscription. You can add the list automatically as part of the deployment of your solution.

This article describes how this process was completed in the Microsoft Office Live Time Card code sample. To access the code referenced below, download the Microsoft Office Live: Time Card code sample. Unless you select a different location, these files are downloaded to C:\Microsoft Office Live Developer Resources\Time Card Sample.

The following table lists the steps involved in automating the addition of a list and the functions and methods in the Time Card sample that accomplish each step:

Step Time Card example
Create script triggered when the solution is opened. initializeTimerList and createTimerList methods of the TaskTimer function
Add the list using Web services provided by Microsoft Windows SharePoint Services. addList method of the WssSoap function
Configure the list using Web services provided by Windows SharePoint Services. onAddListComplete function

Script triggered by opening the solution

You can include in your solution a script that triggers the automatic addition of a list.

The Time Card code sample uses a list to store time card records. In the Time Card code sample, the Time Card list is automatically added to the customer’s subscription the first time that the customer opens the Time Card. The trigger to add the list includes the following methods for the TaskTimer function in the tasktimer.js file:

  • initializeTimerList
  • createTimerList

The initializeTimerList method

The initializeTimerList method is the method that triggers the addition of the list when Time Card opens. This method uses a SharePoint Web Services call to get the collection of lists contained in the current Office Live Small Business subscription. It then searches this collection to see if the timecard list is included. If the list is not included, the initializeTimerList method calls the createTimerList method, passing a Tasks list ID for use in defining the Lookup field for the new list.

Syntax

TaskTimer.prototype.initializeTimerList = function()

Example
  this.initializeTimerList();

The createTimerList method

The createTimerList method is designed to call the addList method of the WssSoap function, which is discussed later in this article.

Syntax

TaskTimer.prototype.createTimerList = function(strTasksListID);

Parameters

Name Required/Optional Data Type Description
strTasksListID Required string ID for the Project Tasks list to be used as a Lookup field in the new list.
Example
  var oTaskTimer = this;
oTaskTimer.createTimerList(strTasksListID);

Add a list using the Lists Web service

A list is added to an Office Live Small Business subscription by calling the AddList method in the Lists Web service provided by Windows SharePoint Services. For more information about this method, see Lists.AddList Method.

The solution developer must package a SOAP request to talk to the Web service. The Office Live Small Business Developer team has created sample functions with methods designed to package SOAP requests to Web services. These functions are available as part of the download for several code samples. The Microsoft Office Live Time Card code sample download includes the file olsharedlibv1.js that contains an example of these types of functions.

The WssSoap function in the olsharedlibv1 file has an addList method designed to package the SOAP request needed to talk to the Lists Web service.

Syntax

WssSoap.prototype.addList = function(strListName, strDescription, iTemplateID, fCallback)

Parameters

Name Required/Optional Data Type Description
strListName Required string A string that contains the title of the list.
strDescription Required string A string that contains a description for the list.
iTemplateID Required enum An enumerated value that specifies the list template to use. Following is a list of possible values for the ID:
  • ANNOUNCEMENTS
  • CONTACTS
  • CUSTOMLIST
  • CUSTOMLISTDSVIEW
  • DATASOURCES
  • DISCUSSIONBOARD
  • DOCUMENTLIBRARY
  • EVENTS
  • FORMLIBRARY
  • ISSUES
  • LINKS
  • PICTURELIBRARY
  • SURVEY
  • TASKS
fCallback Required string The callback function to execute on completion.
Example

The Time Card code sample uses a list to store time card records. The call below requests the addition of a list of the type CUSTOMLIST titled Time Card List and requests that the function onAddListComplete, which is discussed below, is executed after the list is added.

   
    this.oWssSoap.addList(TimeCardResources.LISTNAME_TIMECARD, "Time Card List", 
        this.oWssSoap.eListTypeIDs.CUSTOMLIST, onAddListComplete);

Configure the list using the Lists Web service

The onAddListComplete function configures the list as needed by the Time Card sample. This function is contained within the createTimerList method for the TaskTimer function in the tasktimer.js file.

The onAddListComplete function is called by the addList method for the WssSoap function when it has finished adding the list. This function configures the list to support the solution by doing the following:

  1. Ensures that the list was created correctly.
  2. Creates an XML node that adds two new fields, hides the list, and incorporates the ID passed from initializeTimerList.
  3. Calls the updateList method of the WssSoap function from the file olsharedlibv1 to update the list based on the XML node.

Syntax

function onAddListComplete(addListResponse)

Parameters

Name Required/Optional Data Type Description
addListResponse Required SOAP request object Object that includes properties on the status of the request.