Importing WSDL Definitions for Web Services

Switches

• /bare
• /dataonly
• /gen (U2.0 Soap connector only)
• /nosig
• /verbose
• /mod

Parameters

• Options—string containing one or more entity generation options. For more information, see /gen .
• ModelName—name of the application model to which Uniface entity definitions in the XML schema are written. It overrides the default model name, which is derived from the first element of the namespace of the entity.
• WSDL—URL of a WSDL, or the fully-qualified file name of locally-stored WSDL. The value is stored as a SOAP implementation property (URL of the WSDL) of the SOAP signature.

Description

The import facility loads a WSDL file ImportFile into Uniface and converts it to a Uniface signature with the name provided in the <wsdl:service name> tag. You can view or edit the signature using the Signature Editor, and the model entities using the Model Editor.

Binding Styles and SOAP Connectors

Before importing a WSDL file, you need to set the SOAP connector in your .asn file.

If the binding style of the WSDL file is RPC/Encoded, you must use the SOAP connector U1.0. In this case, you also need to install the Microsoft SOAP Toolkit. For more information, see Call-Out from Uniface to a Web Service.

For other binding styles, you must use the SOAP connector U2.0. Using the SOAP connector U2.0, Uniface imports a WSDL file according to its binding style. However, you can force a Document/Literal Wrapped WSDL file to be imported as Document/Literal Bare using the /bare subswitch.

WSDL File Location

WSDL files are normally located on the web, so the ImportFile is typically a URL. For example:

/sti /mwr=ws http://www.MySite.com/MyWebService/MyWebService.wsdl

However, for performance reasons, you may want to create a local copy of the WSDL file and use it instead. This is because Uniface checks the WSDL file location when a session starts and local locations are more quickly verified than remote locations.

If you use a local copy of the WSDL file, you can import the WSDL from its local location. For example:

/sti /mwr=ws c:\mywebservice.wsdl

The path to the WSDL file, or a local copy of it, can be modified after the import by changing the location with the Signature Editor. For the u2.0 SOAP connector it is also possible to specify the WSDL file location in the assignment file.

If authentication is required in the server that provides the WSDL file, you must also supply the user name and password in the WSDL file path. For example:

/sti /mwr=ws http://username:password@UsefulWebServicesSide/TheWebService/TheWebService?wsdl

Web Service Parameters

An XML schema inside the WSDL file describes the XML structure operation parameters. During the WSDL import using the U2.0 Soap connector, Uniface uses the schema to examine the parameters of operations for their complexity and map the parameter data types.

When the binding type is Document/Literal Bare, parameters are treated as XML documents, with one XML document for IN parameters and another for OUT parameters. As the developer, you need to provide the document, element, and contents for the parameters.

For other binding styles, Uniface applies certain rules for how complex data should be provided in parameters:

• Simple XML schema types are mapped to Uniface (scalar) data types. For more information, see Data Type Mapping for Web Service Call-Out.
• Complex XML schema types that contain only simple XML schema types are mapped to entity or occurrence parameters. The corresponding model entities are also created.

  Important: A WSDL import does not overwrite any existing definitions in the application model. It is therefore very important to examine the log file produced to ensure that the entities and their relationships are those from the newly imported WSDL file.

• Unsupported XML schema types are mapped to a string parameter. These include:
  • Nested complex types
  • Repeating fields or groups of fields
  • Derived types from abstract types that are identified by a xsi:type attribute in the instance document.
  • Substitute elements from the defined substitution group instead of the head element.

  No direct mapping is possible, so special handling is required when activating the operation. As the developer, you need to ensure that data in the parameter is a well-formed XML string that matches the schema definition for the parameter. For more information, see Complex Nested Parameters.

  To help in this task, you can use the /gen switch, which generates extra items that may provide assistance.

/gen for Complex Parameters

The /gen switch can generate sample XML that documents what is required for each complex parameter, or generate entities for complex data. You can then use the example XML in combination with Uniface Structs to generate the required parameter. For more information, see /gen and Generating Complex Parameters for Web Services .

For example, the following import statement imports a WSDL file, generates sample XML for each complex parameter, and generates entities for repeating fields and groups (including choice groups).

/sti /mwr=ws /gen="xml,rfe,rge" http://www.WebSite.com/aWebService/aWebService.wsdl

Note:  If the /bare switch is used, no entities or XML are generated. If the /gen switch is specified in conjunction with /bare, a warning is issued.

Return Type

The following defaults apply:

• If a return is of data type numeric (XSD data types int, short, or long), it is mapped to $status.

  This can result in $status containing either a Uniface status or a return value from the web service, which could be confusing. If you do not like this behavior, you can modify the signature, as follows:

  1. Add an additional parameter as the first parameter of the operation.
  2. In the operation definition, set the Return Value to In First Parameter.
• If a return is of any other data type, it is mapped to the first parameter and Uniface returns a value to $status indicating success or failure.