Importing/Consuming Webservices

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Overview

Importing a Webservice into a project

Description and properties of a Webservice

Using a Webservice

Distributing a WINDEV application that uses a Webservice

Related examples

See also

Importing/Consuming Webservices

Overview

WINDEV, WEBDEV and WINDEV Mobile allow you to directly import Webservices into your applications.

A Webservice is a set of entry points made available to the users in order to perform different processes. For example, a service for remote access provides the processes used to access the data. The exchanges of information with a Webservice are performed in XML format and they use the SOAP (Simple Object Access Protocol) and HTTP protocols.

From the description in WSDL format (Web Services Description Language) of this service, WINDEV, WEBDEV or WINDEV Mobile will automatically generate the WLanguage types and functions corresponding to the programming interface of Webservice.

To use the Webservice, all you have to do is use the functions generated during the import.

This help page presents:

How to import a Webservice into a project.
How to update the description of a Webservice in a project.
How to use a Webservice in a project.
How to distribute a WINDEV application that uses a Webservice.

Versions 17 and later

This feature is now available for Android applications.

This feature is now available for iPhone/iPad applications.

Using a Webservice in an Android project is available from Android version 2.2.

New in version 17

This feature is now available for Android applications.

This feature is now available for iPhone/iPad applications.

Using a Webservice in an Android project is available from Android version 2.2.

This feature is now available for Android applications.

This feature is now available for iPhone/iPad applications.

Using a Webservice in an Android project is available from Android version 2.2.

Versions 18 and later

This feature is now available for applications in Windows Store apps mode.

New in version 18

This feature is now available for applications in Windows Store apps mode.

Importing a Webservice into a project

Import

To import a Webservice:

On the "Project" tab, in the "Project" group, expand "Import" and select "A Webservice".
The Webservice import wizard starts.
In the wizard, the presentation screen is displayed. Go to the next step.
Specify the location of the WSDL. This file corresponds to the webservice description. It contains the description of each function found in the Webservice as well as their parameters.
Two methods can be used to locate the WSDL:
- from a URL, HTTP address where the WSDL is found.
  Remarks:
  - You have the ability to specify the username and the password if an authentication is required.
  - Versions 22 and later
    The "Proxy" button is used to configure the proxy options if necessary.
    New in version 22
    The "Proxy" button is used to configure the proxy options if necessary.
    The "Proxy" button is used to configure the proxy options if necessary.
- from an XML file found on the current computer.
Remark: We do not advise you to check "Import in mode compatible with version 14". In this case, the management of the calls to the Webservice is more complex and the new types are not supported (arrays, structure, etc.). For more details, see Importing Webservices in compatible mode.
Validate the wizard. A message is displayed, indicating that the import is ended.
The Webservice is automatically added into the "Project explorer" pane (in the "Webservices" branch). It is ready to use.

"Project explorer" pane: viewing a webservice

The imported Webservice is in the "Webservices" folder of the "Project explorer" pane:

Webservice in the 'Project explorer' pane

The structure includes:

the name of the Webservice.
the name of each function.
the name of a structure containing either the call parameters, or the return values.
the name of each variable in the structure.

Description and properties of a Webservice

Updating the description of a Webservice

When a Webservice evolves (corrections, new versions, etc.), its description may also evolve.

To update the description of a Webservice in your project:

Select the Webservice in the "Project explorer" pane.
Select "Update" from the popup menu.

Remark: The Webservices imported by using the compatibility mechanism with the earlier versions cannot be updated.

Properties of a Webservice modifiable in the editor

To modify the properties of a Webservice in the editor:

Select the Webservice in the "Project explorer" pane.
Select "Description" in the context menu.
The window of properties is displayed. The following properties can be modified in this window:
- The import address of Webservice: it is the URL used to reach the WSDL describing the Webservice.
- The username and the password used to import the WSDL.

Using a Webservice

Principle

To use a Webservice, you must:

Declare 2 variables: a variable used to specify the call parameters and a variable used to retrieve the response.
Initialize each variable of the call structure.
Important: the order of assignment of variables is used in the XML generated in the SOAP request. It is therefore necessary to assign the variables in the order specified in the documentation of the webservice function.
Call the Webservice function by passing the call variable as parameter and retrieve the response variable in return.

Example:

trackingSearch is trackSearch
trackingSearchRes is resultTrackSearch
trackingSearch.accountNumber = 99999999
trackingSearch.consigneesCountry = "FR"
trackingSearch.consigneesZipCode = "37100"
trackingSearch.sendersRef = "111111"
trackingSearchRes = TrackingServiceWSService.trackSearch(trackingSearch)

IF ErrorOccurred() THEN
Trace("Failed to call the Webservice: " + ErrorInfo(errFullDetails))
ELSE
Trace("Webservice successfully run")
END

In most cases, the result returned by the Webservice is in XML format. Therefore, the XML functions must be used to decode the response.

Versions 26 and later

Asynchronous Webservice call

In some cases, the call to a Webservice may take too long. It may be necessary to make an asynchronous call to the Webservice, using the following syntax:

AFTER <Result> = <Webservice call procedure> DO
<Code executed only if the Webservice has been executed and has sent the response>
END
<Code executed directly after the call to the Webservice>

Using this syntax, you can prevent the call to the Webservice from blocking the application. The program continues to run even if the Webservice has not yet responded.

The previous example becomes:

trackingSearch is trackSearch
trackingSearchRes is resultTrackSearch
trackingSearch.accountNumber = 99999999
trackingSearch.consigneesCountry = "FR"
trackingSearch.consigneesZipCode = "37100"
trackingSearch.sendersRef = "111111"

AFTER trackingSearchRes = TrackingServiceWSService.trackSearch(trackingSearch) DO
IF ErrorOccurred() THEN
Trace("Failed to call the Webservice: " + ErrorInfo(errFullDetails))
ELSE
Trace("Webservice successfully run")
END
END

For more details, see AFTER statement.

New in version 26

Asynchronous Webservice call

In some cases, the call to a Webservice may take too long. It may be necessary to make an asynchronous call to the Webservice, using the following syntax:

AFTER <Result> = <Webservice call procedure> DO
<Code executed only if the Webservice has been executed and has sent the response>
END
<Code executed directly after the call to the Webservice>

Using this syntax, you can prevent the call to the Webservice from blocking the application. The program continues to run even if the Webservice has not yet responded.

The previous example becomes:

trackingSearch is trackSearch
trackingSearchRes is resultTrackSearch
trackingSearch.accountNumber = 99999999
trackingSearch.consigneesCountry = "FR"
trackingSearch.consigneesZipCode = "37100"
trackingSearch.sendersRef = "111111"

AFTER trackingSearchRes = TrackingServiceWSService.trackSearch(trackingSearch) DO
IF ErrorOccurred() THEN
Trace("Failed to call the Webservice: " + ErrorInfo(errFullDetails))
ELSE
Trace("Webservice successfully run")
END
END

For more details, see AFTER statement.

Asynchronous Webservice call

In some cases, the call to a Webservice may take too long. It may be necessary to make an asynchronous call to the Webservice, using the following syntax:

AFTER <Result> = <Webservice call procedure> DO
<Code executed only if the Webservice has been executed and has sent the response>
END
<Code executed directly after the call to the Webservice>

Using this syntax, you can prevent the call to the Webservice from blocking the application. The program continues to run even if the Webservice has not yet responded.

The previous example becomes:

trackingSearch is trackSearch
trackingSearchRes is resultTrackSearch
trackingSearch.accountNumber = 99999999
trackingSearch.consigneesCountry = "FR"
trackingSearch.consigneesZipCode = "37100"
trackingSearch.sendersRef = "111111"

AFTER trackingSearchRes = TrackingServiceWSService.trackSearch(trackingSearch) DO
IF ErrorOccurred() THEN
Trace("Failed to call the Webservice: " + ErrorInfo(errFullDetails))
ELSE
Trace("Webservice successfully run")
END
END

For more details, see AFTER statement.

Properties associated with the Webservice

To handle a Webservice through programming, simply use the name of the Webservice (found in the "Project explorer" pane).

Remark: You can drag and drop directly from the "Project explorer" pane to the code editor to insert the name of the Webservice.

The following properties can be modified through programming:

Name	Type used	Effect

Address	Character string	Used to replace the call address of Webservice described in the WSDL by another URL. This property is useful if the Webservice is hosted on different servers. This property has the following format: "http://server:port/webservice_path". For a Webservice generated with WINDEV and deployed on a WEBDEV Application Server, it is the URL of the file whose extension is "awws". Remarks: The modification of this property replaces all the URLs described in the WSDL. If this property corresponds to an empty string (""), the URLs described in the WSDL will be re-used.
	Integer constant	Used to force the HTTP authentication method: auAutomatic (default value): automatic authentication method. auBasic: Basic authentication method. auNegotiate: Negotiate authentication method.
IgnoreError	Combination of constants	Used to ignore the certificate errors. the following constants can be used: httpIgnoreInvalidCertificate: Used to ignore an invalid certificate or a certificate coming from an unknown company. httpIgnoreInvalidCertificateName: Used to ignore the name of the site found in the certificate. httpIgnoreExpiredCertificate: Used to ignore the date of the certificate. httpIgnoreRedirectToHTTP: Used to redirect to a non-secure server. httpIgnoreRedirectToHTTPS: Used to redirect to a secure server. httpIgnoreRevocation: Used to ignore the check in the list of revoked certificates. Remarks: The errors regarding the security of transactions are ignored. IgnoreError is not available. Before version 200057, the errors regarding the security of transactions were ignored. IgnoreError was not available. From version 200057, the following errors are supported: httpIgnoreExpiredCertificate, httpIgnoreInvalidCertificate, httpIgnoreInvalidCertificateName, httpIgnoreRevocation. The other errors are ignored. For backward compatibility, all the errors are ignored by default.
Versions 18 and later MethodHTTP New in version 18 MethodHTTP MethodHTTP	Integer constant	HTTP method used to call the Webservice: httpPost (default value): POST method httpPut: PUT method Not available.
Password	Character string	Password used to perform the authentication during the HTTP requests to the Webservice. This name is used only if an authentication is required to access the server on which the Webservice is hosted.
Port	Character string	Name of the port defined in the WSDL. It is the port used to communicate with the server that is hosting the Webservice. See your network manager or the owner of the Webservice.
User	Character string	Username that will be used to perform the authentication during the HTTP requests to the Webservice. This name is used only if an authentication is required to access the server on which the Webservice is hosted. With the Negotiate authentication method, the domain must be added to the user depending on the configuration: myWebservice..User = "DOMAIN\User" or myWebservice..User = "User@DOMAIN"
Versions 26 and later VersionHTTP New in version 26 VersionHTTP VersionHTTP	Integer constant	HTTP version used by the server: httpVersion2: HTTP version 2.0. If the server does not support this version, an older version is used. httpVersion2Only: Forces HTTP version 2.0: if the server does not support this version, a fatal error is displayed. httpVersion1_1: HTTP version 1.1. httpVersion1_0: HTTP version 1.0. httpVersionDefault: HTTP version 1.0.

Remark:

If a username and a password are specified, the authentication of the HTTP requests will be done by using the "Basic" authentication schema, in which the parameters are in clear in the HTTP request. We recommend that you use HTTPS requests if the authentication is required.
If the server that hosts the Webservice requires a Windows authentication in HTTP, HTTPParameter must be called before consuming the Webservice (in order to use Internet Explorer for the HTTP requests).
The maximum timeout can be specified with HTTPTimeOut.

Caution: The properties modifiable in the editor and the properties modifiable through programming have no link.

Properties available on the types of variables

The types of variables automatically declared when importing the WSDL propose several properties:

Name	Type used	Effect

Exist	Boolean	True if the type of variable exists in the Webservice response, False otherwise.
Count	Integer	Number of elements of this type in the response of the Webservice. A Webservice can return arrays of variables. The Count property allows you to get the size of the returned array and the [ ] operator allows you to access the elements of the array.
Type	Character string	Name of the variable type. This property is used when a Webservice is likely to return responses of different types.
Value	Variant	Value of variable. Remark: This property is accessed by default when only the variable name is used. For example: myWebservice.RequestVariable = EDT_Value is equivalent to: myWebservice.RequestVariable..Value = EDT_Value

You cannot use a method that manages a shared context.

Advanced operations of the XML stream of the Webservice

In some cases, you may have to handle the XML data stream exchanged with the Webservice. Some Webservices ask for example to add headers into their XML stream to allow the authentication or return meta information in the response headers.

The following functions can be used to respond to these particular requests:


SOAPPrepare	Builds the request to the Webservice for a given function and parameters but it does not send it.
SOAPAddHeader	Adds custom headers into a call to a Webservice.
SOAPGetHeader	Re-reads the information found in the header of the Webservice response.
SOAPAddAttribute	Declares the additional attributes (not found in the WSDL) on a Webservice variable automatically generated. It is used in advanced programming when the WSDL returned by the Webservice does not exactly correspond to the expected type.

Special case: the Webservice returns a result whose type is not recognized by WINDEV, WEBDEV and WINDEV Mobile

The types of variables available in WINDEV and the ones available in a SOAP Webservice can differ.

The simple types (boolean, integer, etc.) and the complex types (datetime, duration, structures, arrays of simple types and array of structures, nested structures, etc.) used in the Webservice are automatically converted into the WLanguage format (and conversely) when the service is imported into a project. The Array types are also supported.

The most evolved types (classes, advanced types of WLanguage, etc.) are processed as character strings in the WLanguage code. These character strings contain the XML code corresponding to the type of variable returned by the Webservice and to its content.

Therefore, if a Webservice returns a result as a class instance, this result will be processed in the procedure as a character string in XML format. Then, you will have to process this character string (in WLanguage) in order to extract the desired information. For more details, see XML functions.

Remarks:

If the Webservice returns a structure, the name of the members found in the return structure is case sensitive.
If you are using a structure as parameter of a Webservice function and if a DATE member is not assigned, the following error will be displayed: "The 0000-00-00 value does not respect the XSD schema".

Distributing a WINDEV application that uses a Webservice

To distribute an application that uses a Webservice, simply include the file that describes the Webservice (.wsdl file) in the library of the application.

In order for the application to be able to run the Webservice, the end-user computers must have an access to Internet.

Remark: Before distributing an application that uses a Webservice, it is recommended to check the license and the distribution rights of this service (in case there is a free for the service).

Related Examples:

Training (WINDEV): WD Webservice Client

[ + ] This example illustrates the use of WebServices.
It explains how to retrieve, from a WebService, images according to keywords.
This project is the client that connects to the "WD Webservice Server" WebService.

Training (WINDEV): WD Webservice Server

[ + ] This example illustrates the use of the WebServices.
It explains how to create a WebService by providing some images according to keywords.
This project is the WebService that is used th the WD Webservice Client project.