PerfectForms™ SharePoint Integration„¢ - SharePoint Integration ... it is now possible to...

PerfectForms™ - SharePoint Integration – Accessing Lists Date of Last Revision: 6/15/11 Page 1 of 16

AUTHOR: KEITH LEWIS DATE: 6/15/2011

PerfectForms™ – SharePoint Integration Accessing Lists from PerfectForms

Contents

Introduction .................................................................................................................................................. 3

Purpose ..................................................................................................................................................... 3

Querying SharePoint using XPath – A Walkthrough ..................................................................................... 4

Create a Web Services Connection ........................................................................................................... 4

Create a Query Request Action ................................................................................................................. 5

Using the Connection ................................................................................................................................ 7

Improving Presentation – Sorting the Response ...................................................................................... 8

Querying By Field Values .......................................................................................................................... 9

Retrieving Only a Few Fields ................................................................................................................... 11

Advanced List Manipulation ....................................................................................................................... 12

Creating the Connection ......................................................................................................................... 12

Getting a List of the Available Lists ......................................................................................................... 12

Getting All Records in a List .................................................................................................................... 12

Getting Only Certain Records from a List ............................................................................................... 12

Adding a Row to a List ............................................................................................................................. 14

Appendix A – PerfectForms XPath .............................................................................................................. 15

SOAP Header and Body Elements ........................................................................................................... 15

Attributes ................................................................................................................................................ 15

Appendix B – Determining the GUID of a list in SharePoint ....................................................................... 16


Introduction

Purpose With the release of Version 2.0 of PerfectForms™, it is now possible to access the Microsoft® SharePoint API Web services from within your form. This document shows you how to use two of the SharePoint APIs from your form:

Querying lists using XPath (dspsts.asmx) – This is most useful when you have data held in SharePoint lists that you wish to use in your PerfectForms project, such as for populating drop-downs or lists. Although it requires knowledge of xpath, it can be used quite effectively with no knowledge of CAML.

Accessing and Manipulating Lists (list.asmx) – While it is possible to obtain data from SharePoint lists using dspsts.asmx, it is a query-only interface. List.asmx provides much richer functionality, but requires an understanding of CAML and how to produce a CAML query in PerfectForms.


Querying SharePoint using XPath – A Walkthrough In this section, we take you through configuring a connection and using it to populate a dropdown from data held in a SharePoint list. The list we are using is a list of departments in a fictional company:

Figure 1 – Departments List in SharePoint

PerfectForms cannot interpret the WSDL produced by dspsts.asmx so we have to manually configure the connection and its actions.

Create a Web Services Connection Complete the steps below to create a Web Services connection.

1. Enter the details for the connection.

Service URL http//yoursharepoint.yourdomain.com/_vti_bin/dspsts.asmx

URL Encode Params Yes

Use Proxy Yes (Currently required for authentication.)

2. Specify the Service WSDL information.

Implementation .NET

WSDL URL Leave this blank.


Use Proxy Yes (Currently required for Authentication)

3. Provide basic authentication details.

Username a user that has access to the SharePoint list(s) you wish to query

Password http//yoursharepoint.yourdomain.com/_vti_bin/dspsts.asmx?wsdl

4. Save the connection.

Create a Query Request Action Once the connection has been created, you must create a new action. To create this new action, complete the steps below.

1. Specify the type as “XML Result”. 2. Select “SOAP” under Service Method. This will produce the following error message:

Figure 2 – Error message getting WSDL from dspsts.asmx

3. Click OK on the error message dialog. The service operation will now be editable. Enter

“queryRequest”.

4. Under Send Parameters enter the following for a Simple Query: Name Service Parameter Name

RequestDocument *request@document

RequestMethod *request@method

RequestNamespace *request@xmlns

VersionsNamespace *versions@xmlns

Version *versions.version

Query dsQuery@select Table 1 – Send Parameters for a Simple Query


5. Apply Changes, then click “Test” and enter the following values to be used to query the Department List:

Name Value

RequestDocument content

RequestMethod query

RequestNamespace http://schemas.microsoft.com/sharepoint/dsp

VersionsNamespace http://schemas.microsoft.com/sharepoint/dsp

Version 1.0

Query1 /list[@id='{86C369DC-2D59-4A19-857C-C99912DC6B6B}'] Table 2 – Parameter Values to Query the Departments List

Apart from the query value, the values never change. To load from your own list, you will need to find the GUID for the list you wish to query (see Appendix B).

6. After entering the values listed above click “Connect”. The SOAP response will be displayed in the Result Log.

7. Close the Test Action form and click Auto Complete for the return parameters. You will be prompted for a sample response that has already been populated with the response from your previous test:

Figure 3 – SOAP Response Example Used to Auto Complete Return Fields

1 The query can be any XPath that refers to a list e.g. /list[@name=’Announcements’]


8. Click “OK” and return parameters will be added for every node in the SOAP response body. Many of these nodes will be of no use to us and can be deleted.

9. In this case, we want the following return parameters (so remove the others):

Name XPath2

Title dsQueryResponse.Departments.Departments_Row.Title

Manager dsQueryResponse.Departments.Departments_Row.Manager

Manager_x0020_Email dsQueryResponse.Departments.Departments_Row.Manager_x0020_Email

ID dsQueryResponse.Departments.Departments_Row.ID

Modified dsQueryResponse.Departments.Departments_Row.Modified

Table 3 – Return Parameters

Note: In the SharePoint list, the “Manager Email” column has a space in its name. Since this is not valid in the XML response, the space has been replaced with _x0020_ (the 16 bit hexadecimal character code for space). Some other characters are also escaped similarly. This is documented in the SharePoint – Dirty Characters blog.

Using the Connection

Once you have applied your changes, your new connection is ready for use on a form. Your form developer must supply the SharePoint query values using a formula as shown in the images below.

Figure 4 – Connect Command to Populate a Dropdown

2 PerfectForms uses a modified version of XPath to reference a node in an XML Document (See Appendix A)

http://blogs.msdn.com/b/senthilkumarmani/archive/2010/10/12/sharepoint-dirty-characters-x0020-x002f.aspx

http://blogs.msdn.com/b/senthilkumarmani/archive/2010/10/12/sharepoint-dirty-characters-x0020-x002f.aspx


Figure 5 Example of Using a Formula to Pass a Fixed Value

The values for each Send Parameter should be entered as shown in Table 2. In this example, the Department drop-down is populated with Title in its caption and ID in its Value.

Figure 6 – A Dropdown Populated from a SharePoint List

Improving Presentation – Sorting the Response As you can see, the departments are not listed alphabetically. We can ask SharePoint to sort the result set by a specified column. To do this, we add the following parameters to the SOAP Call:

Name Service Parameter Name

OrderName dsQuery.Query.OrderBy.OrderField@Name

OrderType dsQuery.Query.OrderBy.OrderField@Type

OrderDirection dsQuery.Query.OrderBy.OrderField@Direction


Table 1 – Additional Send Parameters to Sort the Result Set

Apply changes and test the action with the following values:

Name Value


RequestMethod query



Version 1.0

Query /list[@id='{86C369DC-2D59-4A19-857C-C99912DC6B6B}']

OrderName Title

OrderType xsd:string

OrderDirection ASC Table 5 – Parameter Values For Retrieving A Sorted Result Set

OrderName is the name of the field to sort by (remember to escape the spaces and other characters as necessary). OrderType is the data type of the Field you are sorting by. Possible values are documented in the Microsoft documentation for dspsts. OrderDirection can be either ‘ASC’ or ‘DESC’. Add these additional values to the Connect command in the form and preview:

Figure 7 – Departments Are Now Sorted

Querying By Field Values

In addition to populating a list or drop-down from a SharePoint list, you may also need to look up one or more entries from the list depending on the value of a field. Using our example, you may want to look up the staff in a department selected in the drop-down. To do this, we create another action on our connection in the same way as above. The new action has the following Service Parameters:


RequestDocument *request@document


RequestMethod *request@method

RequestNamespace *request@xmlns

VersionsNamespace *versions@xmlns

Version *versions.version

Query dsQuery@select

FieldName dsQuery.Query.Where.Eq.FieldRef@Name

Value dsQuery.Query.Where.Eq.Value

ValueType dsQuery.Query.Where.Eq.Value@Type

AllFields dsQuery.Query.Fields.AllFields

RowLimit dsQuery.Query@RowLimit This implements a simple where clause testing a single field for equality. More complex where clauses can be constructed using AND and OR constructs (see the Microsoft CAML Query Schema Web site page for additional information). Apply Changes and test with the following values:

Name Value


RequestMethod query



Version 1.0

Query /list[@id='{5108588E-7740-445B-8C4F-8AE0B11948E4}']

FieldName Department

Value Accounts

ValueType text Again, Auto Complete the Return Parameters and remove the unnecessary fields. In our example, we have the following return parameters:

Name XPath

Surname dsQueryResponse.Staff.Staff_Row.Title

Forename dsQueryResponse.Staff.Staff_Row.Forename

Extension dsQueryResponse.Staff.Staff_Row.Extension

Office dsQueryResponse.Staff.Staff_Row.Office

Full Name dsQueryResponse.Staff.Staff_Row.Full_x0020_Name

email dsQueryResponse.Staff.Staff_Row.email

http://msdn.microsoft.com/en-us/library/ms467521%28v=office.12%29.aspx


This can be sorted as shown above.

Retrieving Only a Few Fields The examples above will return all fields from the selected rows in the list. It is also possible to restrict the columns returned using the following Service Parameters.


Field1 dsQuery.Query.Fields.Field

Field1Name dsQuery.Query.Fields.Field@Name








Advanced List Manipulation While dspsts.asmx provides a simple interface that can only retrieve data from SharePoint, List.asmx has a far more feature-rich interface. However, for all but the simplest of operations, an understanding of CAML (Collaborative Application Markup Language) is required. For more information on CAML, you can review the Microsoft article titled Introduction to Collaborative Application Markup Language. The examples below are not exhaustive, but by following the examples, someone experienced in the use of the Lists.asmx API should be able to perform most operations using PerfectForms.

Creating the Connection PerfectForms is able to interpret the WSDL from lists.asmx, so creating a connection is straightforward. You can review this process in the Creating PerfectForms™ Connections topic of the PerfectForms Help Guide. You should, however, select “Use Proxy“ and supply credentials for Basic Authentication.

Getting a List of the Available Lists

Create an action on your Lists connection:

Type XML Result

Service Method SOAP

Operation GetListCollection Apply Changes and test the action, then auto-complete the Return Parameters. It should be noted that you may not need all the fields that are returned. You may remove any return parameters you feel are not needed.

Getting All Records in a List

Create an action on your Lists connection:

Type XML Result

Service Method SOAP

Operation GetListItems Add a single Send Parameter called “listName”. Apply Changes and test the action using the name of the list (do not escape any spaces, etc). Next auto-complete the Return Parameters and remove those that are not needed.

Getting Only Certain Records from a List

http://msdn.microsoft.com/en-us/library/ms426449.aspx

http://www.perfectforms.com/Documentation/manual/html/index.html


This example retrieves rows from a calendar list that fall between two dates. Create an action on your Lists connection:

Type XML Result

Service Method SOAP

Operation GetListItems


listName listName

DateFromRef query.Query.Where.And.Geq.FieldRef@Name

DateFromValue query.Query.Where.And.Geq.Value

DateFromType query.Query.Where.And.Geq.Value@Type

DateToRef query.Query.Where.And.Leq.FieldRef@Name

DateToValue query.Query.Where.And.Leq.Value

DateToType query.Query.Where.And.Leq.Value@Type This builds to the following CAML in the soap query: <query>

<Query>

<Where>

<And>

<Geq>

<FieldRef Name=”[DateFromRef]” />

<Value Type=”[DateFromType]”>

[DateFromValue]

</Value>

</Geq>

<Leq>

<FieldRef Name=”[DateToRef]” />

<Value Type=”[DateToType]”>

[DateToValue]

</Value>

</Leq>

</And>

</Where>

</Query>

</query>

Apply Changes and test using the name of the list (do not escape any spaces, etc) and values similar to those in the table below. Next, auto-complete the Return Parameters and remove those that are not needed.

Name Value

listName Calendar

DateFromRef EventDate

DateFromValue A date in the format YYYY-mm-ddThh:mm:ss

DateFromType DateTime

DateToRef EventDate

DateToValue A date in the format YYYY-mm-ddThh:mm:ss

DateToType DateTime


Adding a Row to a List Create an action on your Lists connection:

Type XML Result

Service Method SOAP

Operation UpdateListItems


listName listName

Value 1 updates.Batch.Method.Field

FieldName 1 updates.Batch.Method.Field@Name


FieldName 2 updates.Batch.Method.Field@Name


Field Name 3 updates.Batch.Method.Field@Name


Field Name 4 updates.Batch.Method.Field@Name

updates.Batch.Method@ID updates.Batch.Method@ID

updates.Batch.Method@Cmd updates.Batch.Method@Cmd

updates.Batch@OnError updates.Batch@OnError Apply Changes and test using the name of the list (do not escape any spaces, etc) and values similar to those in the table below. Next, auto-complete the Return Parameters and remove those that are not needed.

Name Value

listName Calendar

Value 1 A date in the format YYYY-mm-ddThh:mm:ss

FieldName 1 StartTime

Value 2 A date in the format YYYY-mm-ddThh:mm:ss

FieldName 2 EndTime

Value 3 An Event Name

Field Name 3 Title

Value 4 An Organiser

Field Name 4 BookedBy

updates.Batch.Method@ID 1

updates.Batch.Method@Cmd New

updates.Batch@OnError Continue


Appendix A – PerfectForms XPath In PerfectForms, all references to XPath refer to a proprietary language loosely based on the XPath standard. The main difference is that ‘/’ is replaced with ‘.’ and that all paths are absolute.

SOAP Header and Body Elements

A node in a SOAP Header is referenced to by prefixing the path with an asterisk. So for the following SOAP Envelope:

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Header>

<request document="content" method="query"

xmlns="http://schemas.microsoft.com/sharepoint/dsp" />

<versions xmlns="http://schemas.microsoft.com/sharepoint/dsp">

<version>1.0</version>

</versions>

</soap:Header>

<soap:Body>

<queryRequest xmlns="http://schemas.microsoft.com/sharepoint/dsp">

<dsQuery select="/list[@id='{86C369DC-2D59-4A19-857C-C99912DC6B6B}']”>

</dsQuery>

</queryRequest>

</soap:Body>

</soap:Envelope>

“*request” refers to request element in the SOAP Header. “dsQuery” refers to the dsQuery element in the SOAP body.

Attributes

Just as in standard XPath, attributes are indicated using an ‘@’ symbol. This symbol should not be prefixed by a period. In the above SOAP request, “*request@document” refers to the document attribute of the request element in the SOAP Header, which has a value of “content”. In addition, “dsQuery@select” refers to the select attribute of the dsQuery element in the body of the SOAP request.

<Fields>

<Field id=”field1”>Value1</Field>



</Fields>

An attempt to produce the above results in all fields having the same ID (the last value set). This has implications for updating SharePoint Lists and for specifying the fields that should be returned from a list.


Appendix B – Determining the GUID of a list in SharePoint While it is possible to use the Lists.asmx API to iterate the lists and determine the GUID of any given list, it is unlikely that your forms will need to determine the GUID at run-time. Doing so would degrade performance of your form. Alternatively, while accessing a list from a browser you can determine the GUID in a more straightforward manner:

1. Connect to your SharePoint portal. 2. Open the list you wish to access. 3. On the Settings menu select List Settings 4. The list customization page will display. 5. Look in the address bar and you will see the List ID:

6. Copy the GUID and substitute for the GUID’s given in this document.

Date post:	08-Jul-2018
Category:	Documents
Upload:	duongdieu
View:	227 times
Download:	0 times

PerfectForms™ SharePoint Integration„¢ - SharePoint Integration ... it is now possible to...

Documents