The Microsoft Windows Communication foundation (WCF) enables web services to be created for both .NET Framework applications and various Microsoft products such as SharePoint, Navision, Dynamics, etc.
This FAQ provides an example of constructing a call to a web service provided by SharePoint as an example of the principles. It is intended for users that are familiar with WebMaker.
Note: WebMaker Design Studio assumes that any WSDL or Schema documents are public, and not hidden by some sort of authentication. The actual runtime service defined by the WSDL contract can operate under some forms of authentication. For further details on this area, please read "Microsoft Windows Communication foundation (WCF) and Authentication considerations".
IMPORTANT NOTE: Please be aware that there is a patch available in this area for WebMaker 3.1.2 users. Please consider installing before proceeding: MVC_3.1.2.0003: WSDL Import using Soap1.2 + Microsoft WCF Import Schema fixes and this step is not required.
Ensuring Application Map is setup
Before consuming the .NET Web Service it is important to establish that your Page has an Action that links to a Controller that has already been defined. It you don't already have one in place, then it is useful to setup a Controller, and then an Action that is linked from the Page to the Controller. This should be setup on the Application Map screen within FormMaker prior to proceeding with the steps below.
Depending on the nature of your Application you will need to make a decision on where the processing will need to be created. The Controller to be used could be one that has other capabilities as well, such as updating a SQL Database, or calling other Web Services. This initial setup means that WebMaker can generate the necessary Rules processing, as you progress through the series of steps below.
Obtaining the SharePoint WSDL location
The first step is to select the WSDL file that contains the contract details of the SharePoint Web Service to be used. SharePoint provides a number of Web Services and supporting operations. This tutorial will look at the "Lists" service and how to perform an operation to "GetListItems" details from SharePoint.
Each SharePoint installation will have the WSDL files located at:
http://YourServerName/_vti_bin/Lists.asmx?wsdl
You will need to identify your Sharepoint server name address and construct the URL. If the URL is correct then if it is placed in a Browser address line, it will display the WSDL file. Take a copy of the URL value that is successful, as this is required at a later stage.
Obtaining the WSDL Contract Details
The next step is to go to the Page Structure Tab in FormMaker for your page that needs to display the SharePoint data. The next step is to select the WSDL needed to help design the page, and to prepare the processing that calls the Web Service and returns the required data. On the right hand panel select the Data Source Tab, and select the Service Definition option. This will open up a window that allows you to select the WSDL that will be used.
Click on the Upload from URL option at the top of the screen, and paste the URL recorded above into the Enter URL: field. This step will attempt to default a WSDL name for the file to be uploaded into WebMaker, but this should be edited to something more useful, such as: SharePointLists.wsdl
Note: Please make sure the file extension is in lowercase as above.
Press the Upload option and WebMaker will load the WSDL into the local repository for use.
IMPORTANT NOTE: WebMaker v3.1.2 or lower may have issues if the WSDL contains definitions for both soap 1.1 and soap 1.2 bindings. This can be checked by viewing/editing the WSDL file. Generally, if the file contains and xmlns :s oap12 definition within the wsdl:definitions section, then it will be necessary to comment out parts of the WSDL definitions.
There will be two sets of entries for the wsdl:port and the wsdl:binding elements. The ones with Soap12 reference should be commented. Please see the attached "Lists" WSDL for an example of what needs to be commented out.
Alternatively, install the MVC_3.1.2.0003: WSDL Import using Soap1.2 + Microsoft WCF Import Schema fixes and this step is not required.
Finally, click on the name you entered and it will return you to the previous window and show you a drop-down list of the operations that are available for the SharePoint Web Service. For this example select the "GetListItems" operation, and it will then display the details of the fields that have to be sent in the Web Service Request, along with details of the fields that can be returned from the Service.
For this service some of the Web Service request fields are optional, but the main value that must be populated is the "listName".
Paint the Form Fields from the Web Service
At this point the fields from the Request Message should be pulled onto the Form from the Data Source Tab, along with the response details. This will automatically create the request fields and the data bindings that map to the Web Service. You will see a popup, which asks you to tick the action that you want to use. This is used to decide where the processing rules should de created.
This may not be the final result you want, but it will be easier to setup and test.
You may find you want to rename these request fields, or even hide them with default values depending on your requirement. For this example you would need to type a value (may be as a default) of the SharePoint List you want to process. You will now need to add a button with an event that submits the form data to the controller that calls the SharePoint web service.
Note: It is unfortunate that most .NET Web Service WSDL response details will not be displayed fully in the Data Source section. Most .NET WSDLs simply don't contain any details of the actual fields that are returned. So, in order to work round this .NET limitation of the WSDL definitions, you will need to define the field details manually at a latter stage.
WebMaker works most effectively when a full WSDL contract is provided with all fields defined. WebMaker allows the fields to be dragged onto a form and setup automatically with a ll the data bindings, validation, formatting, etc. if the field definitions are in the WSDL. However, it is still relatively simple to setup a set of data bindings manually. An alternative approach is that sometimes separate XML Schemas (XSD) can be used to define the page details.
Test the Web Service Calls assembled correctly
At this point you could Generate the Application, Deploy it, and then run it via the Test Dashboard. As the project is generated, WebMaker will have generated various controller processing nodes and various rules to handle all the operations supported by the WSDL. These rules are specific to each operation and they look for precise soap:Body message content, so only the relevant rule will be fired.
The application would display the first page with the List name field. Enter the name of the list you wish to retrieve and then press your button to submit the request. This will not work fully as the security authentication mechanism has not been setup yet.
However, from the Test Dashboard logs you will see a Message sent to the SOAP Web Service for the "GetListItems", and a returned SOAP Fault stating that the request FAILED with a 401 UNAUTHORIZED.
Background on Authentication
There are various levels of security that can be used to secure Microsoft Windows based Web Services. When you use Microsoft platform security, which assumes a tightly-coupled Microsoft???-? Windows???-? operating system environment, for example, on a corporate intranet then:
Setting up the Windows specific Authentication details
If Windows IIS Web Server platform authentication is required, the web service request will result in a FAILED HTTP/SOAP call returning status 401 UNAUTHORIZED, access denied response. In this case it will be necessary to setup specific details that are passed in the HTTP Header to the Web Service to enable the authentication, which could be: Basic, Digest, NTLM. Therefore, it is necessary to setup all the appropriate security details so WebMaker and the SharePoint Web Service can negotiate the security mechanism to be used based on the IIS Web Server setup.
The first stage is to go to the Application Map page of FormMaker. You need to click on the controller that is called from the page you setup for the call to the Web Service using the WSDL. When clicking on the controller icon, you will see right hand panel appear with a link for the Controller Rules, which will contain the calls to the actual SharePoint Web Service Access Service. In this example the value would be "Lists".
Click on the View Controller Rules link, which will open up a new Browser Tab showing the rules within the controller. Open up the Rule that says it is calling the "Call_GetList_operation...". Within the rule you will find the a call the Invoke Service node that handles the call to the Access Service that actually call the SharePoint "Lists" external Web Service. Click on the View Target Rules for the "...Lists-Access_Service". This will open up another set of Rules that contain the actual request and response message calls to the actual SharePoint web service. The Access Service contains the handling for all the operations supported by the web service.
This Rule sheet consists of a lot of rules that have been automatically generated from the WSDL, but many are not being used for this particular example. You could choose to disable all the Priority "20" rules that you are not going to use, but there is no need too. In this example, you could disable all except the "ListsSoap_GetListItems_GetListItemsSoapIn_Rule". You can always reenable them at a later point.
The next step is to add the specific details required to set the HTTP Header Authentication details required by the Windows IIS Server authentication. At the top of the rules list, the first rule places the SOAP Envelope details required for all SOAP based messages.
After this rule, add a new rule that will add the authentication details. The simplest initial approach is to add the setting of various details as a block of fields. This is the quickest way to set it up initially in order to ensure that the authentication operates correctly.
Add a new rule with a name of "Apply Authentication". then add an Action of "Insert", with a name of "Add Security Details". The next step is to set the "to_location" of where the details will be inserted into the XML factbase being assembled, and then the actual XML fragment to insert at that location.
The "to_location" should simply be set to "/*", which means to place it directly under the top level SOAP:Envelope element, at the same level as SOAP:Body containing the actual message content you need to send to the Sharepoint Web Service. Note: The exact location does not really matter, as the data is used by WebMaker and then discarded before actually sending the SOAP message to SharePoint.
The "fragment" example content in the rule should be deleted and replaced with the fragment below:
You will need to edit the various security fields and replace them with the appropriate values for the IIS Server authentication needed to access the web services. Replace the various (...) text above to add the appropriate values for your environment. The port will be 80 or 443 depending on whether the SharePoint server is HTTP or HTTPS for its access. The client is the name of the server you are calling from. For some forms of security it may only be necessary to have a subset of the fields, but as we don't know the security to be used, all details are setup.
For further reference material, please refer to the product documentation:
WebMaker Documentation and search for "Remote Service Security"
The final step is to adjust a couple of the pre-configured Access Service Rules to handle the additional HTTP Security Details that have been added, so that the SharePoint Web Service response details are handled in the same manner that is expected for a standard SOAP based message.
There are two rules to edit:
Both rules require a similar condition to be altered for the "Check_for_header_content" condition.
Normally these rules check to see if there is any content in the SOAP Header and then handle the message slightly differently. In this case we want to alter the check to ignore if any HTTPHeader related details are present. So, the xpath conditions for the "Check_no_header_content" condition should be changed for each rule as follows:
The final step is to save the changes for the rules for the Access Service.
Switch on Advanced Features for Web Service Call
As this web service call needs security mechanisms that are HTTP based, rather than strict SOAP / WS-* based standards, it is necessary to alter the actual Web Service Call deployment. When WebMaker processed the WSDL to setup much of the rules processing, it was not able to create the security processing as it is not defined in the WSDL contract.
To setup the security processing it is necessary to go back to the main WebMaker Design Studio Tab, where you will find a navigational image Deploy and Publish. This link will open up a new Tab with a window that allows advanced features to be setup for Web Service Calls to other Web Services.
In the list of Web Service Calls there will be an entry for the "Lists_Proxy_ListsSoap" Service call. It is necessary to click on the row to edit the details, changing the "Service Type" to "HTTP Service", and ticking the Advanced Features flag. The row should be amended and closed, followed by a click of the Deploy Project button. This will switch on the features that handle the security checking when the SOAP messages are sent to the SharePoint IIS Server.
Once deployed you should be able to Generate the Application, Deploy and Test. The Test Dashboard logs should show the successful setting up of the Security Details passed to the SharePoint Web Service.
Testing and Assisting with Displaying the Response Details
Once the security details are correct, you should see a response in the Test Dashboard logs. Once you see the successful response returned, it is useful to view the XML message for the "outgoing" message from the Page Controller. This will show the actual data that would be returned from the Web Service call.
It is often useful to click on the Copy XML link, and then return to FormMaker to the Data Bindings Tab. On the Page Display Bindings Tab you will see an XML document which is an example of the data returned to the Page for rendering. It may be useful to Edit the document and Paste in the XML just copied. This may then assist in setting up specific bindings for the fields you wish to display on the Page. This last step is not required if the WSDL defined all the detailed fields for the Web Service response. In this case the fields would have been dragged onto the Page in the same manner as the request fields.
Troubleshooting
Below are some of the more common issues that are encountered:
Security Field values - The most likely problem to occur is that the Security field values are not quite correct, and not accepted by the SharePoint Web Service. It may take a few attempts.
Namespace Values with a # - Some Windows Web Service operations may have a namespace that is returned with a hash character at the beginning "#...". There are some conflicts between providers as to whether this should be allowed. If you encounter this secenario, then it will be necessary to edit the data bindings for the Display Page Bindings and alter the values manually to cater for this case.
If a data binding matches an element that uses a namespace value with a "#", then you will need to remove the name of the element and append the following:
*[local-name() = 'element name' and namespace-uri() = '#Particular Namespace Value']
For example:
Before: ...tns:GetListItemsResult/tns:listitems/rs:data/ns1:row
After: ...tns:GetListItemsResult/tns:listitems/rs:data/*[local-name() = 'row' and namespace-uri() = '#RowsetSchema']
Root element missing error - If you encounter an error of this type in the web service response, then you may need to take further action. If there are optional parameters for the web service request call, and all the fields were dragged on to the page, you may need to remove some of them. By default WebMaker generates a place holder for each field dragged onto the page, as it assumes you will want to use them. For example, if you are only want to specify the ListName field as defined above, then you need to remove all the other elements under the GetListItems element in the action submission binding document for your action.
Further Considerations
The example described above is the simplest case for implementing a call to a .NET Web Service. There may be other scenarios that may need to be considered:
Relocate Security Details to the Controller - The example above places the "Security Details" rule in the "Access Service". The example assumes that the User credentials are fixed for all users as it is a "shared" logon to the SharePoint Web Services. You may find that you would like to place it into the Controller that calls the Access Service, before the call to Invoke the Access Service. This is probably advisable if the Username and Password vary depending on some other data defined or available in the Controller, possibly from a Page. If this is the case then after the "Security Details" Rule is setup, you may add a couple of further "Assign" actions to the Rule to set the Username and Password values appropriately by binding to other field elements that exist.
Caching of security details - If the Username and Password are captured on another screen then you may wish to use the "Cache" facilities to store the details within a "Session" Cache and then retrieve them in the Access Service or Controller as appropriate. Please reference the "Cache" features in the product documentation.
Other SharePoint Services Available
SharePoint overs a wide range of services with supporting WSDL files. These can be used in the same manner as described above to interact with SharePoint. The URL to identify most services follows the pattern:
http://YourServerName]/_vti_bin/Lists.asmx?wsdl
To use one of the other services, edit the "Lists" part of the URL, and replace it with the name of the other services. If you use this URL, you will be able to extract the WSDL file that can be used as the contract for consuming the Web Service.
The exact details of the request parameters are best reviewed by accessing MSDN for the appropriate SharePoint Web Service Name. Search on the internet for "MSDN SharePoint Web Services", or click on this link the MSDN documentation.
This FAQ provides an example of constructing a call to a web service provided by SharePoint as an example of the principles. It is intended for users that are familiar with WebMaker.
Note: WebMaker Design Studio assumes that any WSDL or Schema documents are public, and not hidden by some sort of authentication. The actual runtime service defined by the WSDL contract can operate under some forms of authentication. For further details on this area, please read "Microsoft Windows Communication foundation (WCF) and Authentication considerations".
IMPORTANT NOTE: Please be aware that there is a patch available in this area for WebMaker 3.1.2 users. Please consider installing before proceeding: MVC_3.1.2.0003: WSDL Import using Soap1.2 + Microsoft WCF Import Schema fixes and this step is not required.
Ensuring Application Map is setup
Before consuming the .NET Web Service it is important to establish that your Page has an Action that links to a Controller that has already been defined. It you don't already have one in place, then it is useful to setup a Controller, and then an Action that is linked from the Page to the Controller. This should be setup on the Application Map screen within FormMaker prior to proceeding with the steps below.
Depending on the nature of your Application you will need to make a decision on where the processing will need to be created. The Controller to be used could be one that has other capabilities as well, such as updating a SQL Database, or calling other Web Services. This initial setup means that WebMaker can generate the necessary Rules processing, as you progress through the series of steps below.
Obtaining the SharePoint WSDL location
The first step is to select the WSDL file that contains the contract details of the SharePoint Web Service to be used. SharePoint provides a number of Web Services and supporting operations. This tutorial will look at the "Lists" service and how to perform an operation to "GetListItems" details from SharePoint.
Each SharePoint installation will have the WSDL files located at:
http://YourServerName/_vti_bin/Lists.asmx?wsdl
You will need to identify your Sharepoint server name address and construct the URL. If the URL is correct then if it is placed in a Browser address line, it will display the WSDL file. Take a copy of the URL value that is successful, as this is required at a later stage.
Obtaining the WSDL Contract Details
The next step is to go to the Page Structure Tab in FormMaker for your page that needs to display the SharePoint data. The next step is to select the WSDL needed to help design the page, and to prepare the processing that calls the Web Service and returns the required data. On the right hand panel select the Data Source Tab, and select the Service Definition option. This will open up a window that allows you to select the WSDL that will be used.
Click on the Upload from URL option at the top of the screen, and paste the URL recorded above into the Enter URL: field. This step will attempt to default a WSDL name for the file to be uploaded into WebMaker, but this should be edited to something more useful, such as: SharePointLists.wsdl
Note: Please make sure the file extension is in lowercase as above.
Press the Upload option and WebMaker will load the WSDL into the local repository for use.
IMPORTANT NOTE: WebMaker v3.1.2 or lower may have issues if the WSDL contains definitions for both soap 1.1 and soap 1.2 bindings. This can be checked by viewing/editing the WSDL file. Generally, if the file contains and xmlns :s oap12 definition within the wsdl:definitions section, then it will be necessary to comment out parts of the WSDL definitions.
There will be two sets of entries for the wsdl:port and the wsdl:binding elements. The ones with Soap12 reference should be commented. Please see the attached "Lists" WSDL for an example of what needs to be commented out.
Alternatively, install the MVC_3.1.2.0003: WSDL Import using Soap1.2 + Microsoft WCF Import Schema fixes and this step is not required.
Finally, click on the name you entered and it will return you to the previous window and show you a drop-down list of the operations that are available for the SharePoint Web Service. For this example select the "GetListItems" operation, and it will then display the details of the fields that have to be sent in the Web Service Request, along with details of the fields that can be returned from the Service.
For this service some of the Web Service request fields are optional, but the main value that must be populated is the "listName".
Paint the Form Fields from the Web Service
At this point the fields from the Request Message should be pulled onto the Form from the Data Source Tab, along with the response details. This will automatically create the request fields and the data bindings that map to the Web Service. You will see a popup, which asks you to tick the action that you want to use. This is used to decide where the processing rules should de created.
This may not be the final result you want, but it will be easier to setup and test.
You may find you want to rename these request fields, or even hide them with default values depending on your requirement. For this example you would need to type a value (may be as a default) of the SharePoint List you want to process. You will now need to add a button with an event that submits the form data to the controller that calls the SharePoint web service.
Note: It is unfortunate that most .NET Web Service WSDL response details will not be displayed fully in the Data Source section. Most .NET WSDLs simply don't contain any details of the actual fields that are returned. So, in order to work round this .NET limitation of the WSDL definitions, you will need to define the field details manually at a latter stage.
WebMaker works most effectively when a full WSDL contract is provided with all fields defined. WebMaker allows the fields to be dragged onto a form and setup automatically with a ll the data bindings, validation, formatting, etc. if the field definitions are in the WSDL. However, it is still relatively simple to setup a set of data bindings manually. An alternative approach is that sometimes separate XML Schemas (XSD) can be used to define the page details.
Test the Web Service Calls assembled correctly
At this point you could Generate the Application, Deploy it, and then run it via the Test Dashboard. As the project is generated, WebMaker will have generated various controller processing nodes and various rules to handle all the operations supported by the WSDL. These rules are specific to each operation and they look for precise soap:Body message content, so only the relevant rule will be fired.
The application would display the first page with the List name field. Enter the name of the list you wish to retrieve and then press your button to submit the request. This will not work fully as the security authentication mechanism has not been setup yet.
However, from the Test Dashboard logs you will see a Message sent to the SOAP Web Service for the "GetListItems", and a returned SOAP Fault stating that the request FAILED with a 401 UNAUTHORIZED.
Background on Authentication
There are various levels of security that can be used to secure Microsoft Windows based Web Services. When you use Microsoft platform security, which assumes a tightly-coupled Microsoft???-? Windows???-? operating system environment, for example, on a corporate intranet then:
- The Web server (IIS) provides Basic, Digest and NTLM based authentication.[/*]
- HTTPS - SSL may be used to provide message integrity and confidentiality.[/*]
Setting up the Windows specific Authentication details
If Windows IIS Web Server platform authentication is required, the web service request will result in a FAILED HTTP/SOAP call returning status 401 UNAUTHORIZED, access denied response. In this case it will be necessary to setup specific details that are passed in the HTTP Header to the Web Service to enable the authentication, which could be: Basic, Digest, NTLM. Therefore, it is necessary to setup all the appropriate security details so WebMaker and the SharePoint Web Service can negotiate the security mechanism to be used based on the IIS Web Server setup.
The first stage is to go to the Application Map page of FormMaker. You need to click on the controller that is called from the page you setup for the call to the Web Service using the WSDL. When clicking on the controller icon, you will see right hand panel appear with a link for the Controller Rules, which will contain the calls to the actual SharePoint Web Service Access Service. In this example the value would be "Lists".
Click on the View Controller Rules link, which will open up a new Browser Tab showing the rules within the controller. Open up the Rule that says it is calling the "Call_GetList_operation...". Within the rule you will find the a call the Invoke Service node that handles the call to the Access Service that actually call the SharePoint "Lists" external Web Service. Click on the View Target Rules for the "...Lists-Access_Service". This will open up another set of Rules that contain the actual request and response message calls to the actual SharePoint web service. The Access Service contains the handling for all the operations supported by the web service.
This Rule sheet consists of a lot of rules that have been automatically generated from the WSDL, but many are not being used for this particular example. You could choose to disable all the Priority "20" rules that you are not going to use, but there is no need too. In this example, you could disable all except the "ListsSoap_GetListItems_GetListItemsSoapIn_Rule". You can always reenable them at a later point.
The next step is to add the specific details required to set the HTTP Header Authentication details required by the Windows IIS Server authentication. At the top of the rules list, the first rule places the SOAP Envelope details required for all SOAP based messages.
After this rule, add a new rule that will add the authentication details. The simplest initial approach is to add the setting of various details as a block of fields. This is the quickest way to set it up initially in order to ensure that the authentication operates correctly.
Add a new rule with a name of "Apply Authentication". then add an Action of "Insert", with a name of "Add Security Details". The next step is to set the "to_location" of where the details will be inserted into the XML factbase being assembled, and then the actual XML fragment to insert at that location.
The "to_location" should simply be set to "/*", which means to place it directly under the top level SOAP:Envelope element, at the same level as SOAP:Body containing the actual message content you need to send to the Sharepoint Web Service. Note: The exact location does not really matter, as the data is used by WebMaker and then discarded before actually sending the SOAP message to SharePoint.
The "fragment" example content in the rule should be deleted and replaced with the fragment below:
<xg:HttpHeader xmlns:xg="http://www.hyfinity.com/xgate">
<security preemptive="false" xmlns="http://www.hyfinity.com/xgate">
<username>YourUsername...</username>
<password>YourPassword...</password>
<host>YourSharePointServerName...</host>
<realm>YourSharePointServerName...</realm>
<port>80</port>
<client>YourServerName...</client>
</security>
</xg:HttpHeader>You will need to edit the various security fields and replace them with the appropriate values for the IIS Server authentication needed to access the web services. Replace the various (...) text above to add the appropriate values for your environment. The port will be 80 or 443 depending on whether the SharePoint server is HTTP or HTTPS for its access. The client is the name of the server you are calling from. For some forms of security it may only be necessary to have a subset of the fields, but as we don't know the security to be used, all details are setup.
For further reference material, please refer to the product documentation:
WebMaker Documentation and search for "Remote Service Security"
The final step is to adjust a couple of the pre-configured Access Service Rules to handle the additional HTTP Security Details that have been added, so that the SharePoint Web Service response details are handled in the same manner that is expected for a standard SOAP based message.
There are two rules to edit:
- Handle_Success_Response_no_Header[/*]
- Handle_Success_Response_with_Header[/*]
Both rules require a similar condition to be altered for the "Check_for_header_content" condition.
Normally these rules check to see if there is any content in the SOAP Header and then handle the message slightly differently. In this case we want to alter the check to ignore if any HTTPHeader related details are present. So, the xpath conditions for the "Check_no_header_content" condition should be changed for each rule as follows:
- Handle_Success_Response_no_Header - not(/soap:Envelope/soap:Header/*[namespace-uri() != 'http://www.hyfinity.com/xgate'])[/*]
- Handle_Success_Response_with_Header - soap:Envelope/soap:Header/*[namespace-uri() != 'http://www.hyfinity.com/xgate'] [/*]
The final step is to save the changes for the rules for the Access Service.
Switch on Advanced Features for Web Service Call
As this web service call needs security mechanisms that are HTTP based, rather than strict SOAP / WS-* based standards, it is necessary to alter the actual Web Service Call deployment. When WebMaker processed the WSDL to setup much of the rules processing, it was not able to create the security processing as it is not defined in the WSDL contract.
To setup the security processing it is necessary to go back to the main WebMaker Design Studio Tab, where you will find a navigational image Deploy and Publish. This link will open up a new Tab with a window that allows advanced features to be setup for Web Service Calls to other Web Services.
In the list of Web Service Calls there will be an entry for the "Lists_Proxy_ListsSoap" Service call. It is necessary to click on the row to edit the details, changing the "Service Type" to "HTTP Service", and ticking the Advanced Features flag. The row should be amended and closed, followed by a click of the Deploy Project button. This will switch on the features that handle the security checking when the SOAP messages are sent to the SharePoint IIS Server.
Once deployed you should be able to Generate the Application, Deploy and Test. The Test Dashboard logs should show the successful setting up of the Security Details passed to the SharePoint Web Service.
Testing and Assisting with Displaying the Response Details
Once the security details are correct, you should see a response in the Test Dashboard logs. Once you see the successful response returned, it is useful to view the XML message for the "outgoing" message from the Page Controller. This will show the actual data that would be returned from the Web Service call.
It is often useful to click on the Copy XML link, and then return to FormMaker to the Data Bindings Tab. On the Page Display Bindings Tab you will see an XML document which is an example of the data returned to the Page for rendering. It may be useful to Edit the document and Paste in the XML just copied. This may then assist in setting up specific bindings for the fields you wish to display on the Page. This last step is not required if the WSDL defined all the detailed fields for the Web Service response. In this case the fields would have been dragged onto the Page in the same manner as the request fields.
Troubleshooting
Below are some of the more common issues that are encountered:
Security Field values - The most likely problem to occur is that the Security field values are not quite correct, and not accepted by the SharePoint Web Service. It may take a few attempts.
Namespace Values with a # - Some Windows Web Service operations may have a namespace that is returned with a hash character at the beginning "#...". There are some conflicts between providers as to whether this should be allowed. If you encounter this secenario, then it will be necessary to edit the data bindings for the Display Page Bindings and alter the values manually to cater for this case.
If a data binding matches an element that uses a namespace value with a "#", then you will need to remove the name of the element and append the following:
*[local-name() = 'element name' and namespace-uri() = '#Particular Namespace Value']
For example:
Before: ...tns:GetListItemsResult/tns:listitems/rs:data/ns1:row
After: ...tns:GetListItemsResult/tns:listitems/rs:data/*[local-name() = 'row' and namespace-uri() = '#RowsetSchema']
Root element missing error - If you encounter an error of this type in the web service response, then you may need to take further action. If there are optional parameters for the web service request call, and all the fields were dragged on to the page, you may need to remove some of them. By default WebMaker generates a place holder for each field dragged onto the page, as it assumes you will want to use them. For example, if you are only want to specify the ListName field as defined above, then you need to remove all the other elements under the GetListItems element in the action submission binding document for your action.
Further Considerations
The example described above is the simplest case for implementing a call to a .NET Web Service. There may be other scenarios that may need to be considered:
Relocate Security Details to the Controller - The example above places the "Security Details" rule in the "Access Service". The example assumes that the User credentials are fixed for all users as it is a "shared" logon to the SharePoint Web Services. You may find that you would like to place it into the Controller that calls the Access Service, before the call to Invoke the Access Service. This is probably advisable if the Username and Password vary depending on some other data defined or available in the Controller, possibly from a Page. If this is the case then after the "Security Details" Rule is setup, you may add a couple of further "Assign" actions to the Rule to set the Username and Password values appropriately by binding to other field elements that exist.
Caching of security details - If the Username and Password are captured on another screen then you may wish to use the "Cache" facilities to store the details within a "Session" Cache and then retrieve them in the Access Service or Controller as appropriate. Please reference the "Cache" features in the product documentation.
Other SharePoint Services Available
SharePoint overs a wide range of services with supporting WSDL files. These can be used in the same manner as described above to interact with SharePoint. The URL to identify most services follows the pattern:
http://YourServerName]/_vti_bin/Lists.asmx?wsdl
To use one of the other services, edit the "Lists" part of the URL, and replace it with the name of the other services. If you use this URL, you will be able to extract the WSDL file that can be used as the contract for consuming the Web Service.
The exact details of the request parameters are best reviewed by accessing MSDN for the appropriate SharePoint Web Service Name. Search on the internet for "MSDN SharePoint Web Services", or click on this link the MSDN documentation.
Attachment