Using the URL Protocol

  • Article

Using the URL Protocol

There are two ways to use URL protocol to send commands to a server running SharePoint Team Services from Microsoft. You can send single methods and parameters by embedding them in a URL, or you can use CAML batch functionality to send multiple requests per transaction. The following table lists commands and parameters that can be used and that have corresponding methods in the RPC protocol. For more information, click the command to see the related RPC method topic.

Command (Cmd=) Description Parameters
DeleteField Deletes a field from a list. ID, Scope, Field, owshiddenversion
Display Runs a database query and returns XML or HTML. ID, Scope, XMLDATA
DisplayPost Renders the CAML assigned to the PostBody parameter. ID, PostBody, URLBase
ExportList Exports the schema of a list in CAML format. ID, Scope
GetProjSchema Requests the XML schema for a team Web site. ID
ImportList Creates a new list based upon the XML schema that is specified in the method. ID, Title, RootFolder, ListSchema
ModListSettings Changes the properties of a list. ID, Scope, OldListTitle, NewListTitle, Description, ReadSecurity, WriteSecurity, SchemaSecurity, owshiddenversion
NewField Adds a new field to a list. ID, Scope, FieldXML, AddToDefaultView, owshiddenversion
NewList Creates a new list of a specified type, such as Contacts, Discussions, or Survey. ID, ListTemplate, LangID
NewViewPage Adds a new view page to a team Web site. ID, Scope, PageURL, DisplayName, HiddenView
RenderView Requests the contents of a view for a list. ID, View, Scope, URLBase
ReorderFields Changes the order in which fields in a list are displayed on the list's data entry form. ID, Scope, ReorderedFields, owshiddenversion
SiteProvision Adds the default set of lists to an existing team Web site. ID, CreateLists
UpdateField Modifies the schema of an existing field in a list. ID, Scope, FieldXML, owshiddenversion

In addition to the above RPC-related commands, the following commands and parameters can also be used:

Command (Cmd=) Description Parameters
Delete Deletes an item in a list.
  • ID — the item's ID as listed in the database table.
  • List — the name of the database table that contains the item.
  • NextUsing — the page to open once the command has been executed.
DeleteList Deletes a list.
  • List — the name of the database table that contains the item.
  • NextUsing — the page to open once the command has been executed.
Save Saves a new list or saves modifications to an existing list.
  • ID — the item's ID as listed in the database table. Set to New for new list items.
  • List — the name of the database table that contains the item.
  • NextUsing — the page to open once the command has been executed.

The following parameters can also be used in the protocol:

  • FileDialogFilterValue to set filters for a view and to return from a document library the list of all files of a specified type according to file extension (for example, *.doc, *.ppt, or *.xls).
  • FilterFieldn to specify the name of a field in the database, where n is an integer that is limited only by the number of fields allowed in the database table or by the length allowed for the URL field.
  • FilterValuen to specify the string value on which to filter a field, where n is an integer that is limited only by the length allowed for the URL field.
  • SortField to specify the name of the field on which to sort.
  • SortDir to indicate an ascending (asc) or descending (desc) sort order.
  • Using to specify a particular file containing CAML for the server to evaluate and render.

Embedding a SharePoint Team Services method in a URL

Embedding a request in a URL is a basic mechanism for issuing a method and its parameters to a server running SharePoint Team Services. The syntax for using this mechanism is as follows:

http://[Web_name/]_vti_bin/owssvr.dll?Cmd=Method_name[&Parameter1=Value1&Parameter2=Value2...]

The following example creates a new Custom list named "Employees" on a site called STSWeb1:

http://STSWeb1/_vti_bin/owssvr.dll?Cmd=NewList&ListTemplate=100&Title=Employees&LangID=1033

This example displays the Discussions list as a CAML file:

http://STSWeb1/_vti_bin/owssvr.dll?Cmd=Display&List=Discussions&XMLDATA=TRUE

The next example exports the Discussions list to a Microsoft Excel worksheet. Note that the unique GUID for the associated view must be assigned to the View parameter.

http://STSWeb1/_vti_bin/owssvr.dll?CS=109&Using=_layouts/query.iqy&List=Discussions&View={4442B73A-8E2B-4edc-A272-94E3615008C5}&CacheControl=1

Using CAML batch functionality to send multiple requests through a form

You can post multiple requests by using the CAML batch functionality and creating a form that includes a text area (PostBody) for posting the requests. Create a form like the following in an HTML file, where the action attribute contains the URL command being posted to the server:

<FORM method="POST" action="http://STSServer1/_vti_bin/owssvr.dll?Cmd=DisplayPost">
  <TEXTAREA rows="18" name="PostBody" cols="72"></TEXTAREA>
  <INPUT type="submit" value="Submit">
  <INPUT type="reset" value="Reset">
</FORM>

Here, the DisplayPost command requests the server to render CAML contained in the PostBody variable, which is defined by the above text area.

Next, open the form in your browser and enter a block of CAML that uses the Batch element, such as follows:

<ows:Batch OnError="Return">
  <Method ID="A1"> 
    <SetList>Announcements</SetList> 
    <SetVar Name="ID">New</SetVar> 
    <SetVar Name="Cmd">Save</SetVar> 
    <SetVar Name="urn:schemas-microsoft-com:office:office#Title">New Program Manager</SetVar> 
    <SetVar Name="urn:schemas-microsoft-com:office:office#Body">Congratulations to Jane for her promotion!</SetVar> 
    <SetVar Name="urn:schemas-microsoft-com:office:office#Expires">2001-09-14T00:00:00Z</SetVar>
  </Method> 
  <Method ID="A2"> 
    <SetList>Announcements</SetList> 
    <SetVar Name="ID">New</SetVar> 
    <SetVar Name="Cmd">Save</SetVar> 
    <SetVar Name="urn:schemas-microsoft-com:office:office#Title">Sales rise by 10%</SetVar> 
    <SetVar Name="urn:schemas-microsoft-com:office:office#Body">The accounting office has released its quarterly report. Check it out!</SetVar> 
    <SetVar Name="urn:schemas-microsoft-com:office:office#Expires">2001-12-18T00:00:00Z</SetVar>
  </Method> 
</ows:Batch>

When submitted, this sample adds two records to the Announcements list in the database, registering their field values in the Microsoft Office namespace.

For more information on how to use CAML, see the CAML Schema Reference.