Subscribing to a Web Service in 4D

4D allows you to subscribe to Web Services; in other words, to call external Web Services from within your databases. 

Using Web Services available on the Internet, you can easily add numerous additional functions to your databases, such as access to stock market information, package delivery follow-up, execution of complex calculations, etc. The multitude of Web Services available on the Internet can fulfill almost every need. 

You can also subscribe to Web Services that you have published yourself in other databases and in this way let various 4D databases communicate among themselves.

Any 4D database can subscribe to a Web Service; it simply needs to be connected to the Internet.

Generally, to be able to call a Web Service, you must follow the steps described below:

1. Retrieve the URL of the Web Service to which you want to subscribe.
   To do this, you can use Web sites that inventory Web Services published on the Internet (for example www.xmethods.net) or directories such as the UDDI. In most cases, you must obtain the URL of the WSDL file for the Web Service.
   Note: 4D can use Web Services published in RPC or DOC mode (see Compatibility of RPC, DOC and complex types).
2. Using the Web Services Wizard, parse the contents of the WSDL of the Web Service to be used and generate the corresponding proxy method.
   The proxy method is the local project method in charge of interrogating the Web Service and retrieving the returned values. This step is described in the section below.
   Notes:
   
   • It is possible to create proxy methods in the Web Services Wizard without using a WSDL file (simply enter the parameters to be used manually).
   • It is also possible to create proxy methods in the Method editor, without using the Web Services Wizard (advanced users).
3. In the code of your database, call the proxy method each time that you need it by passing the appropriate parameters to it.
   This step is described in Calling a proxy method.

The proxy method handles the connection to the Web Service:

The subscription to a Web Service from a 4D application is handled entirely by the Web Services Wizard. This wizard automatically carries out:

• Parsing of WSDL files for the Web Services to be used,
• Definition of the parameters for the proxy methods to be created,
• Creation of proxy methods.

To open the Web Services Wizard window, choose the Web Services Wizard... command in the Design menu of 4D. The Wizard window appears:

Note: It is also possible to display the Web Services Wizard from the options menu of the Methods page in the Explorer (see ).

This window includes three areas:

• The “URL:” area allows you to enter or select the URL of the WSDL file for the chosen Web Service. This area is a combo box that stores the previously-entered values in the form of a drop-down list.
• The central area displays the results of parsing the WSDL file contents: names of services and published methods.
• The lower area (“Advanced” parameters, hidden by default) displays the parameters of the method selected in the central area.

The Discover button triggers the parsing of the designated WSDL file and the filling in of the information areas.
The Browse... button displays a standard file opening dialog box, allowing the selection of a WSDL stored locally. Its pathname, beginning with “file://”, is then displayed in the “URL:” area (it is possible to enter the pathname manually in this area).
The Create button is used to generate the proxy method corresponding to the selected Web Service.
The Close button closes the Web Services Wizard dialog box. 

Typical use of the Web Services Wizard consists in parsing a WSDL file then generating the corresponding proxy method(s). This standard operation is entirely automatic and does not require any programming or any particular know-how on the part of the user. 

To parse a WSDL file and generate the proxy method:

1. In the “URL:” area, enter or paste the URL of the WSDL file for the Web Service that you want to use:
   
   This URL may come, for instance, from a “directory” of Web Services or may have been communicated directly by the server of the Web Service.
   You can also specify a local URL, i.e., the address of a WSDL file stored on your hard disk. To do this, click on the Browse... button and choose the local WSDL file, or enter its pathname directly in the “URL:” area. The pathname of the local file begins with “file://” then uses the standard system folder separator. You must pass an absolute pathname. 
2. Click on the Discover button in order for 4D to parse the contents of the WSDL file.
   After a few moments, the central area displays the results of file parsing: the name of the Web Service(s) as well as the published method(s) appear in the form of a hierarchical list.
   
   Note: You can display the XML source code of the WSDL file directly in your default Web browser by holding down the Shift key when you click on the Discover button.
   Clicking on a Web Service displays its documentation (if any) on the right-hand side of the window. Otherwise, the indication “No documentation” appears.
   Similarly, the documentation (if any) for each method appears when you select its name:
   
   Note: If the parsing of the WSDL file reveals the presence of complex type parameters, the Wizard displays a yellow flag next to the method concerned .
3. Select the Web Service method that you want to use then click on the Create button.
   4D instantly generates the corresponding proxy method and displays it in a window of the Method editor:
   
   The name of the proxy method is defined by the concatenation of the default prefix “proxy_” and the name of the Web Service method. The default prefix can be modified on the Web/Web Services page in the Database Settings. The name of the proxy method can also be modified after its creation; this does not influence the operation of the method.

Proxy methods generated by the Web Services Wizard from the parsing of a WSDL file are immediately operational and can be used "as is" (standard mode).

However, you might want to modify the parameters resulting from WSDL parsing. For example, it is possible to rename the proxy method. 

You can also use the Web Services Wizard to create a proxy method for which you have manually entered the parameters. In this case, do not use the WSDL parser.
It is not mandatory to enter all the parameters to be able to create a method.
It is even possible to not enter any parameters in order to create a proxy method “template” that you can then fill in using 4D programming.

In these non-standard modes, you must use the advanced parameters of the Web Services Wizard. To display these parameters, click on the expanding button located at the bottom left of the Wizard window. The advanced parameter fields then appear. If a method is selected, the fields display its current parameters:

All the parameters are modifiable. Note, however, that modifying parameters stemming from WSDL parsing (except for the method name) must be done with precaution because the operation of the Web Service may be altered as a consequence.

Here is a description of the advanced parameters:

• Method Name: Name that the Wizard will give to the proxy method to be created. By default, this name is made up of the prefix “proxy_” (modifiable in the Preferences) followed by the name of the selected method. This name can be modified freely (for instance, if it already exists in the database) without this having any influence on the operation of the Web Service.
• Endpoint URL: URL to which the proxy method sends the SOAP requests.
• SOAP Action: Contents of the SOAPAction field. This field generally contains the value “ServiceName#MethodName”.
• Namespace: Namespace of the Web Service (for more information, refer to Customizing a namespace).
• Parameter table: This table lists the parameters of the published method.
  
  Each row of the table describes a parameter:
  
  • The first column indicates whether the parameter is of the input (“in”) or output (“out”) type. This characteristic is evaluated from the point of view of the proxy method, and not that of the published method.
  • The second column indicates the name of the parameter.
  • The third column indicates the SOAP type of the parameter. Different SOAP types accepted by 4D can be displayed in the Type menu located in the Properties area. The Web Services Wizard will be responsible for associating SOAP types with the corresponding 4D types in the proxy method.
    The following table lists the types of SOAP values accepted and the corresponding 4D types:
    

    SOAP Type	Corresponding 4D Type
    boolean	Boolean
    int	Long Integer
    time	Time
    float	Real
    double	Real
    date	Date
    string	Text
    base64Binary	BLOB
    ArrayOfBoolean	Boolean array
    ArrayOfInt	LongInt array
    ArrayOfTime	LongInt array
    ArrayOfFloat	Real array
    ArrayOfDate	Date array
    ArrayOfString	Text array
    AsXML	BLOB

           
    Note: The AsXML type is not, strictly speaking, a SOAP type, but it is used for supporting complex XML types (see Processing complex types).
    The Properties area displays the characteristics of the parameter selected in the table. The Web Services Wizard allows you to modify the existing parameters or add parameters, for instance if the specified WSDL file is not up to date.
    
    • To modify a parameter, select it and then make your modifications in the Properties area.
    • To add a parameter, click on the Add button then set its characteristics in the Properties area.
    • To delete a parameter, select it in the list then click on the Delete button.
    Note: Modifications made in the advanced parameters will only be taken into account if a proxy method is actually created using the Create button.

To call a proxy method in your code, simply write its name and pass the required parameters to it. These parameters are declared in the header area of the proxy method by the Web Services Wizard. In conformity with the standard syntax for passing parameters between methods in 4D, they are named $0, $1, $2, and so on. They can be displayed in the advanced parameters of the description of the published method (see Using advanced parameters) and are sometimes described in its documentation. 

For instance, in the case of a method named WS_EuroConverter, the proxy method could be called in the following manner: 

After execution of the method, the following warning is displayed:

4D enables you to use Web Services published in either RPC or DOC mode and including complex types (see Compatibility of RPC, DOC and complex types).

Note: Despite the fact that they are complex XML types, data arrays are handled by 4D as simple types. 

The proxy methods generated by the Web Services Wizard that include complex types (i.e., published in RPC mode with complex types or in DOC mode) are similar to standard proxy methods. However, you will notice that in certain cases with these Web Services, the WEB SERVICE CALL command includes, as a parameter, a constant containing the word manual. 

In fact, the use of such Web Services requires additional processing. The main reason for this is that complex types are exchanged in the form of documents or XML elements. This means that in order to extract or include information in these SOAP parameters, prior XML parsing is necessary — whereas in the case of simple types, the parameter values are directly readable.

• Use of simple types (RPC)
  

• Use of complex types (DOC)
  

Only arrays and complex type data on one level (a single hierarchical level in the SOAP request) are fully supported by the Web Services Wizard. If more complex elements are found in the request, the Wizard will indicate this by a flag displayed next to the method name. Support of this type of Web Service generally requires custom processing by the developer. 

In 4D, complex type parameters (except for arrays) are handled in the form of BLOBs. The XML commands of 4D can be used to process the contents of these BLOBs. For more information, refer to the Web Services (Client) and XML DOM themes of the 4D Language Reference manual.