Web Service Data Provider

Web Service Data Provider

General Info

This data provider can be used to fetch information from a web service. An argument designer is provided in order to specify the input parameters of the web service to call. The web service data provider properties are the following:
  1. Url: The URL of the web method to invoke.
  2. Field for control search: applicable when this kind of provider is used for obtaining Lookup Values for a Combobox control. It is used for extra filtering according to the search term that is specified by the user within the combobox, as shown below:

The Search term specified by the user within the Combobox is passed in the specified input parameter. In the above example, if our web service contained an input argument "CountryName" then the "Fr" string would be used as an input value. Therefore the "Field for control search" property would have the value of "CountryName".
This functionality is particularly useful on large lists where the provider would return thousands of records, in order to perform filtering of the items on the server (within the web method itself). This logic prevents the unorthodox process of fetching all the records from the server first, and then applying the filters on the client side, which could cause huge performance issues. Please note though, that the exact handling of the input value (and the search operators applied) is dependent on the implementation of the web service itself. The data provider is agnostic of the internal operations of the web service that is invoked.
  1. Schema Name: the JSON property under which the values are returned from the web service. By default "d" is used, since this is the root property in script-enabled asmx web services. However in other implementations, this property could differ. 
  2. Method: The http verb/method used to perform the operation (GET or POST). If empty, "POST" is assumed. 
  3. With Credentials: Indicates whether or not cross-site Access-Control requests should be made using credentials such as cookies, authorization headers or TLS client certificates. Setting withCredentials has no effect on same-site requests.
  4. Criteria: You can add, remove and re-order parameters using the list editor on the bottom of the page (Field Name: the parameter name, Field Value: the parameter value)
You can use a formula/expression for values that need to be evaluated during runtime. In order to do that, make sure that the value is preceded with an equals (=) sign, for example:
=form.GetControl("Title").GetValue()

Limitations and Cross Domain Considerations

The web service should return a JSON response. If the web service you want to invoke has a different response type (for example SOAP/XML), you shouldn't use this data provider
Unless you are invoking a web service that provided by SharePoint API, the most common scenario would be that the web service is hosted in a different domain that your SharePoint site. By default, browsers prohibit this kind of interaction, unless certain conditions are satisfied. More specifically, the web service should return the following custom HTTP response headers:

HTTP Header
Value
Access-Control-Allow-Origin
*
Access-Control-Allow-Credentials
true
Access-Control-Allow-Headers
Content-Type, PFCompress
Access-Control-Allow-Methods
GET, POST, PUT, OPTIONS

If your web service is developed in ASP .NET technology, the above could be accomplished with the following web.config entries:
 
<system.webServer>
    <httpProtocol>
      <customHeaders>
        <add name="Access-Control-Allow-Origin" value="*" />
        <add name="Access-Control-Allow-Credentials" value="true"/>
        <add name="Access-Control-Allow-Headers" value="Content-Type, PFCompress" />
        <add name="Access-Control-Allow-Methods" value="GET, POST, PUT, OPTIONS" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>



Example

Let's assume you have a web service hosted at http://localhost:27544/Service1.asmx and you need to invoke the GetPersonsByJobTitle web method in order to obtain a list of employees (return type: array of String) and feed the lookup values in a Combobox. Our web method has the following signature: 

string[] GetPersonsByJobTitle(string JobTitle)

In this scenario, you would create a Web Service Data Provider in the "Lookup Values" property of the control::





Watch how the JobTitle parameter is set to be retrieved from an existing control within the form. The value could also be static (if you wanted to get the persons with a specific job title). Our final resut would be the following:


See Also

For more info about the concept of Data Providers, their usage and their common properties (Name, OnDataLoaded, Condition, etc) see Basic Concepts: Intro to Data Providers