Mashing SharePoint Web Services

4
Your rating: None Average: 4 (2 votes)

Mashups and Microsoft SharePoint Part 2.4: Mashing SharePoint Web Services

This is the ninth in a many-part series about Mashups and Microsoft SharePoint.  You can read about the entire series at http://www.jackbe.com/enterprise-mashup/blog/mashing-sharepoint-introduction.

This section provides 2 examples of publishing a SharePoint Web Service with Presto, using Wires to Virtualize the Web Service and create a Mashup, and finally to expose the Mashup as a Mashlet.

So we have a 3 stage procedure:

  1. Publish the Web Service on Presto using Service Explorer.
  2. Create and publish a Mashup, virtualizing a Web Service Operation using Wires.
  3. Create and publish a Mashlet of the Mashup using MashletMaker.

Some of the SharePoint Web Service WSDLs do not fully describe the inputs and outputs to the service operations, for example the WSDL may describe an input parameter as a primitive string whereas the service is expects the client to provide a complex fragment of xml.

Preferabely the WSDL would fully describe operation inputs down to their primitive parts, Presto is dependent on the WSDL service description in order to build the various user interface components through which the user can enter input data.

The operations exposed by a SharePoint Web Service can be viewed in a Browser by entering the Web Service URL, the Web Service will return the Web Service Description in a browser readable form. Each listed operation provides a link to a description of the request and response message composition.

In some circumstances the WSDL will not fully describe the service operation input or output messages, as is the case with the SharePoint Search WSDL, MSDN can be used to track down the necessary detail.

SharePoint List Web Service

The Lists Web Service is probably one of the most useful Web Services SharePoint provides, it exposes various operations enabling us to request details of any identifiable list based service maintained by a SharePoint Site.

  • GetListCollection can be used to retrieve a summary list of all Lists maintained by a SharePoint Site
  • GetList can be used to retrieve the details of the Fields which compose a named List.
  • GetListItems can be used to retreive the content of a named List.

Publishing The Lists Web Service to Presto

Before publishing the Web Service to Presto we need to gather the following information, assuming we have a SharePoint Site named Jackbe :

  • A name to uniquely identify the published Presto Service, eg. SpJackbeLists, signifying Sharepoint Service, Jackbe Site, Lists Web Service.
  • The URL for the service WSDL, eg. http://www.mycompany.com/sites/MySite/_vti_bin/Lists.asmx?wsdl.
  • NT Lan Manager (NTLM) Username, password and domain.

Using Presto Service Explorer, we launch the WSDL publishing wizard and enter our details, select NTLM authentication and enter our user credentials. The screenshot below shows an example of the Service details entered in the Service Explorer Publishing Wizard:

Presto will access the service, read and validate the WSDL and prepare the Service as a Presto Published Service. If successful, the wizard will stop to allow us to configure role based access to the service as a whole and/or to individual operations, as illustrated in the screenshot below:

Having published the service, by default the service will be activated and ready to be invoked, we are now ready to use the service as a Mashable in Wires.

Note that if you try to create a Mashlet directly from the published Web Service using MashletMaker then you will probably find that when you select a Service Operation, GetList for example, MashletMaker will recommend that you virtualize the Operation using Wires becuase the Operation input parameters are complex.

Virtualization is process by which Wires is able to convert complex input parameters into one or more primitive datatype input parameters.

Create and Publish a Mashup

As a very simple example, we will expose the newly published service, GetListItems Operation as a mashup Service.

See Creating Mashups for further details explaining how to use Wires to create Mashups.

  • Having launched Wires, locate the newly published Service in the Service pallette.
  • Drag the service out onto the canvas and select the GetListItems operation from the drop down list.

The screenshot below shows the complex Input Parameter details for the GetListItems Operation.

  • Most of the parameters are optional and we can leave them blank, but we will virtualize the listName parameter by clicking the pipe icon which appears to the right of the input field when the mouse passes over. The virtualized input parameter will appear as a new block on the canvas, connected to the Service block.
  • We can test these 2 blocks by entering the name or GUID of a List in the Input Parameter block.
  • To complete the Mashup we connect the Service block to the Mashup Output block.
  • We can now save the Mashup, assigning a unique name to it, tagging and providing a description.
  • Having saved the Mashup we can publish it so that it becomes externally accessible.

The screenshot below shows the completed mashup.

Having published the Mashup we can now expose the Mashup as a Mashlet. Once the mashup is published, Wires provides us with a shortcut via a toolbar button to create a Mashlet from the current Mashup.

Create and Publish a Mashlet

The Mashup we created takes a single string input parameter which identifies the name of the list we wish to view.

On our example SharePoint Site, Jackbe, we have a Tasks List which maintains a summary of tasks assigned to various team members. This List is shown in the screenshot below, it only contains 2 entries, Task A and Task B.

We will create a Mashlet which exposes this List as a Mashlet so that the information can be made available to users outside the sharePoint environment.

  • Launch MashletMaker, either from within Wires or via the Presto Home page.
  • Select the virtualized GetListItem Mashup previously published.
  • Select the single operation exposed by the mashup, runMashup.
  • MashletMaker will display any inputs required by the Mashup, it should display the single input parameter, listName.
  • We enter the name of the List we which to view, in our case we'll enter the name Tasks.
  • MashletMaker will now prompt us to select the type of View we wish to use, select GridView.
  • MashletMaker will now invoke the service and prompt us to select which data columns are to appear in the GridView. In our example we select columns to display task Name, Id and Status.
  • Mashlet Maker will now render the mashlet as shown in the screenshot below.
  • We can now choose to publish the mashlet or further alter it by modifying mashlet appearance or role based security setting.

SharePoint Search Web Service

The Search Web Service enables us to perform search queries across a SharePoint Site. Here we'll demonstrate how we can use the Web Service Query Operation to search for occurances of a key word or phrase on a SharePoint Site and for those results to be made available in the form of an RSS Feed.

Publishing The Search Web Service to Presto

Before publishing the Web Service to Presto we need to gather the following information, assuming we have a SharePoint Site named Jackbe :

Using Presto Service Explorer, we launch the WSDL publishing wizard and enter our details, select NTLM authentication and enter our user credentials. The screenshot below shows an example of the Service details entered in the Service Explorer Publishing Wizard:

Presto will access the service, read and validate the WSDL and prepare the Service as a Presto Published Service. If successful, the wizard will stop to allow us to configure role based access to the service as a whole and/or to individual operations, as illustrated in the screenshot below:

Having published the service, by default the service will be activated and ready to be invoked, we are now ready to use the service as a Mashable in Wires.

Note that if you try to create a Mashlet directly from the published Web Service using MashletMaker then you will probably find that when you select a Service Operation, Query for example, MashletMaker will recommend that you virtualize the Operation using Wires becuase the Operation input parameters are complex.

Virtualization is process by which Wires is able to convert complex input parameters into one or more primitive datatype input parameters.

Create and Publish a Mashup

We will expose the newly published service, Query Operation as a mashup Service.

See Creating Mashups for further details explaining how to use Wires to create Mashups.

  • Having launched Wires, locate the newly published Service in the Service pallette.
  • Drag the service out onto the canvas and select the Query operation from the drop down list.

The screenshot below shows the complex Input Parameter details for the Query Operation, The Input Parameter expects the user to enter the queryXml as a string.

Unfortunately, the service WSDL schema does not define the content of the queryXml parameter, the parameter must specify a fragment of XML encapsualted as a QueryPacket. Here is an example :

    <QueryPacket xmlns='urn:Microsoft.Search.Query'>
       <Query>
           <SupportedFormats>
                <Format>urn:Microsoft.Search.Response.Document.Document</Format>
           </SupportedFormats>

           <Context>
                <QueryText language='en-US' type='STRING'>Jackbe</QueryText>
           </Context>
       </Query>
    </QueryPacket>

 

The only part we are interested in is the QueryText element content, Jackbe, in the above example.

With Wires being unable to help us build this fragment of XML we are forced to build the XML fragment and then cut and paste it as a string into the input field for the Seach block, as shown below. We can then invoke the search and see what search results are returned.

By default when the search is invoked the preview window will display the response document as a structured XML Tree, unfortunately, as with the Operation Input Parameter, the WSDL Schema does not go as far as defining the content of the Search Response QueryResult, it just defines it as an opaque string.

By switching to the Text view of the response we can see that the QueryResult contains a CDATA element which in turn contains a ResponsePacket element, encapsulating the Search Result.

We can use the Wires ExtractValue Action to extract this QueryResult value in order to process the Search Result in XML form, as shown in the screenshot below. Now the XML Tree View of the extracted SearchResult ResponsePacket shows us that the Search returned a list of Document elements encapsulating each search result item.

Going back to the Search Query Input Parameter, we dont really want to force the user to have to enter the entire fragment of XML each time they perform a search, ideally, we would provide a template Action which constructs the XML Fragment and inserts the Query Text.

We can add such a Template Action and add it to our Wires pallette relatively easily. Instructions on how to add a new Action to Wires are details in this MDC Blog entry by Kishore, it explains how we can create a new macro which we add to the global.emml-macros file, which is used by wires to populate the Action Pallette.

I've created the following macro, QueryPacketTemplate, which just takes a string input, which will be our query text, and creates a fragment of XML as a string, which we can then wire to out SpJackbeSearch Block in Wires.

    <macro name="QueryPacketTemplate">
        <output name="result" type="string"/>

        <presto-meta name="macrotype">user</presto-meta>

        <input name="query" type="string"/>
        <presto-meta name="type" variable="query" reference="xmldoc">template</presto-meta>

        <presto-meta name="label" variable="query">Query Text</presto-meta>

        <presto-meta name="help">
            <description>build Search Query</description>

            <parameters>
                <parameter name="query">Search Query Text</parameter>
            </parameters>
        </presto-meta>

        <variable name="resultStr" type="string"/>

        <script type="javascript">
        <![CDATA[
            var rgx=/\[([^\]]+)\]/g;
            query=query.replace(rgx,"{$item/$1/string()}");

            var resultStr = '<QueryPacket xmlns="urn:Microsoft.Search.Query">'+
                            '<Query>'+
                                '<SupportedFormats><Format>urn:Microsoft.Search.Response.Document.Document</Format></SupportedFormats>'+
                                '<Context>'+
                                    '<QueryText language="en-US" type="STRING">'+
                                        query +
                                    '</QueryText>'+
                                '</Context>'+
                            '</Query>'+
                        '</QueryPacket>';
        ]]>

        </script>
        <assign fromvariable="resultStr" outputvariable="result"/>
    </macro>

Presto must be restarted if the global.emml-macros file is updated.

The screenshot below shows the completed mashup, the new QueryPacketTemplate action is fed by an Input Parameter block which takes a simple string value as the query text.

Create and Publish Search Mashlet

We will create a Mashlet which exposes this Search Mashup as a Mashlet so that the search capability can be made available to users outside the SharePoint environment.

  • Launch MashletMaker, either from within Wires or via the Presto Home page.
  • Select the Search Mashup previously published.
  • Select the single operation exposed by the mashup, runMashup.
  • MashletMaker will display any inputs required by the Mashup, it should display the single input parameter, named Input.

Image:m-s-01.jpg

 

  • We enter a default query string, Jackbe.
  • MashletMaker will now prompt us to select the type of View we wish to use, select GridView.
  • MashletMaker will now invoke the service and prompt us to select which data columns are to appear in the GridView. In our example we select columns to display Title, Link and Date.

 

  • The Mashlet Preview and Preferences will now be displayed.
  • In the Mashlet Additional Preferences Section, we must change the preference disableRemotePaging from the default value of false to true, as shown in the screen shot below.
  • Click the Preview Changes button and the Mashlet should render.

 

  • We can now choose to publish the mashlet or further alter it by modifying mashlet appearance or role based security setting.

Ideally the Mashlet would be intelligent enough to convert the Search result Link URLs into clickable links.

 

This post is part of a many-part series about Mashups and Microsoft SharePoint.  You can read about the entire series at http://www.jackbe.com/enterprise-mashup/blog/mashing-sharepoint-introduction.