Blog Series Part 2: Many Connection Types for the External Data Provider, there are
The External Data Provider is THE Swiss Army knife of the Toolset. Sure it connects to your external data, but did you realize all the connection types it supports and the possible properties you can specify with each? During this blog series we’ll cover all the connection types, the properties associated with them and also provide examples for you to reference going forward. This article assumes you have seen a connection file before and understand its format of an opening & closing <CorasWorks> parent element with each connection being stored as a <Data> element within.
This article will focus on my favorite connection type for building web 2.0 and enterprise mashup applications – Web Services.
When creating a web service connection type, effectively what we’re doing is telling our External Data Provider which web service to call through its documented endpoint and passing in the SOAP Action and Envelope for the web service method (also called operation) you want to execute.
Let’s look at a sample web service method provided out-of-the-box in SharePoint. This screenshot shows the details for the “GetUserInfo” operation of the “Users and Groups” web service in SharePoint. You can access this same page on any SharePoint environment (WSS v3 or MOSS) by appending the following to any Site’s URL: /_vti_bin/usergroup.asmx?op=GetUserInfo. You can also leave off the “?op=…” portion to see all the operations the User and Groups web service supports.
First, let’s briefly decode what we’re looking at – and need – from this web service. The key here is that just about any data source that supports SOAP web services, be it SharePoint, Dynamics CRM or even commercial web services like those offered by companies such as CDYNE, will have a page and/or documentation like this. For CorasWorks Data Integration Toolset customers, this means calling a web service is as easy as copy-pasting the three highlighted sections you see above.
In terms of your connection setup, the yellow text represents the Request URI, the orange your SOAP Action and the green section your SOAP Envelope. Let’s now see how this looks inside a Toolset web service connection; the sample below is for the web service method in the screenshot above.
|
<Data> <Name>YourConnectionName</Name> <Default>True/False</Default> <ConnectionType>WebService</ConnectionType> <Request>http://YourSite/_vti_bin/usergroup.asmx</Request> <SOAP> <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:Body> <GetUserInfo xmlns="http://schemas.microsoft.com/sharepoint/soap/directory/"> <userLoginName>%CWUserName%</userLoginName> </GetUserInfo> </soap:Body> </soap:Envelope> </SOAP> <SOAPAction>http://schemas.microsoft.com/sharepoint/soap/directory/GetUserInfo</SOAPAction> </Data> |
This is all you need in a connection to begin working with web services. You may notice that I left the “?op=” part off of my request URI; this is fine because, by virtue of my SOAP Action and envelope, the web service knows which method to execute. And don’t forget; a web service connection supports all the EDP variables and parameter replacement options an ADO connection does. In our example here, I’m using the EDP variable %CWUserName% to dynamically pass in the username of the currently logged in user when this connection is run.
And just like an ADO connection, here are all the optional properties you can set with a Web Service connection; the only ones not available on an ADO connection, are <ProtocolVersion> and <DecodeXML>:
|
Property Name / Element |
Property Use / Function |
|
<ProtocolVersion> |
Some older SOAP web services require the HTTP connection to be made via protocol 1.0. For these, use the <ProtocolVersion> property with the value “Version10”. You do not need to use this property unless you get an error in your EDP that the protocol version is wrong; the default value is “Version11”. |
|
<DecodeXML> |
Set this property to “True” if your web service call is returning XML embedded inside a single element. Otherwise, the default value is “False”. |
|
<OutputType> |
Default is “text/xml” however “text/html” & ”text/plain” are also supported. |
|
<XslStylesheet> |
Actual XSL to transform the response from your Provider. However, it is recommended to use an attached stylesheet (see next property) as opposed to including your XSL in line here. |
|
<XslStylesheetLocation> |
The URL to the location of an XSL stylesheet (can be .xml, .xsl or .xslt) to be applied for transforming the Provider response. This transform occurs *before* the data is rendered or passed on to another component. |
|
<ErrorRedirect> |
A URL to redirect a user/connection to when the connection called results in an error. |
|
<ReportErrors> |
A true/false flag to indicate whether errors are reported. If set to “true”, and an <ErrorRedirect> is specified, the error message will be attached to the redirect URL as: ErrorRedirectURL?Error=(Error Message) |
|
<RedirectTo> |
The URL to redirect this connection to upon successful completion. This is the ability to take the response from one connection and instantly pass it into another to complete a process or validate a response. If you specify a parameter in the RedirectTo, you can pass the value of the initial connection using a pre-defined variable called %Data%. Ex. http://site.net/subsite/providers/ADO.aspx? ConnectionName=SecondConnection&FirstValue=%Data% |
|
<RDConnection> |
The URL to pass the results of this connection into. This is different than a <RedirectTo> which literally forwards the request on to a new page/connection. With an <RDConnection>, the results of the first connection are passed into a second connection for use in processing said connection, and the results of the second connection are then returned to the first one. This is most useful when needing to send a collection of XML into a second connection since, with the RedirectTo, the entire response of the first connection is passed via query string variable; see the next property for setting the XML elements you wish to post into the second connection. |
|
<RDConnectionPost> |
A property for specifying (via XPath) the XML results from your first connection that you wish to post into a second connection, as well as the parameter names to use when posting them. The <RDConnectionPost> also supports setting a default value to pass for a parameter, should the XPath for the parameter value not exist within the first connection’s result. |
|
<Values> |
The Values element simply holds empty child nodes representing each and every parameter that you wish to pass into this connection. Thus, if you plan to pass in a parameter called “Department” into your connection, you would need a self-closing <Department /> element inside your <Values></Values> elements. This is to let the connection know to look for a GET/POST param with the name specified. There’s no limit to the number of params. |
|
<CacheOutput> |
A true/false value indicating whether or not the output from this connection should be cached. If set to “true”, you can use the following three properties to customize the cache label and/or duration. Absent any of the following properties, the default label will be TheConnectionName+”Output”+WebPartID with a duration of 200 mins. |
|
<CacheLabel> |
A text value to specify the cache label; if not specified, the default Web Part ID will be used for this portion of the cache identifier. |
|
<CacheAddUserID> |
A true/false value indicating whether or not to add the ID of the user running the connection to cache label; this is akin to a cache per user mechanism. If set to “true” the User’s ID will be added to the end of the cache label. |
|
<CacheDuration> |
An integer value indicating the cache duration in minutes. |
Just like yesterday’s post on making an ADO connection, you can download a sample connection file for a web service connection from the Building Block Exchange section of the CorasWorks Community forum here.
Check back tomorrow for Part 3 in the series – HTTP Post connections.
Buy:Nymphomax.Acomplia.Lipothin.Amoxicillin.Lasix.Ventolin.Buspar.SleepWell.Seroquel.Zocor.Benicar.Lipitor.Wellbutrin SR.Female Cialis.Female Pink Viagra.Zetia.Advair.Cozaar.Aricept.Prozac….