Generating Complex Parameters for Web Services

When importing a WSDL, a parameter containing complex data is defined as a string data type. As the developer, you need to provide the complex data as a well-formed XML string. To help in this task, you can use the /gen switch to generate example XML and/or entities.

The XML example created by /gen describes what is required for the parameter, so you do not need to be an expert in deciphering WSDL files. However, some knowledge of XML schemas is required. For example, the allowed value content of a schema data type is not described in the XML example. Contents of types derived from those schema types are described in terms of the schema facets. For more information, see XML Parameter Template.

To create the XML strings for web service IN parameters you can take any of the following approaches:

  • Use the XML template purely as documentation for what must be provided.
  • Modify the XML template and use it as a hard-coded string.
  • Use the XML template in combination with Uniface Structs to generate the required parameter.

What needs to be generated depends on how the parameter will be inserted into the envelope. For more information, see Complex Nested Parameters.

Using Structs to Generate a Parameter

To generate the XML for the parameter, you can create a Struct that contains the correct data and then use the StructToXml ProcScript command to generate the XML string for the parameter. For more information on Structs and their use, see the following topics:

To create and fill the Struct, you can use a number of different techniques:

  • Use ProcScript Struct functions to create and populate a Struct, based on the XML example.
  • Use the xmlToStruct ProcScript command to convert the XML example (possibly after editing it) to a Struct, and then use ProcScript Struct functions to interactively fill certain members. You could place the XML in a string and use string substitution to fill it with fields from a form.
  • Create components with entities painted in the relationships as described by the XML schema in the WSDL. Retrieve data interactively and then generate the appropriate Struct using the componentToStruct ProcScript instruction. This technique produces a Struct with a lot of extra information, so you can then use the structToXML/schema ProcScript instruction to provide the required XML. In this case, you need to extract the schemas from the WSDL and supply them as separate schemas to structToXML/schema.

The best technique to use largely depends on the data and the XML that needs to be created. For example:

  • Some WSDLs define a parameter that contains hundreds of optional elements, but for any one operation only a few are needed. The XML example will contain all of these optional elements but it is probably easier to create the Struct directly with the few that are required per operation.
  • If the data is complicated but does not need to change, it may be easier to edit the XML example string.
  • For complicated data that is stored in several tables in a database, creating components from generated entities may be the most flexible approach.

Explore the WSDL

To determine how the /gen switch can help, import the WSDL using the qualifiers /nosig/verbose/gen="xml", then examine the log file produced. The log file describes the contents of the WSDL and is mostly self-explanatory (although the format of messages in the log file may be changed without warning in the future).

  • Lines beginning with 
    "Found WSDL
			 …"
    describe items such as operation parameters or entities that were found in the WSDL.
  • Lines beginning with 
    "Not
			 generating …"
    are produced for any schema construct that can be influenced with a /gen option.

An example piece of XML is generated for each parameter. This XML is not complete—it does not contain the correct data, nor does it have the correct number of occurrences of data. However, it does document what is required.

Deciding on What to Generate

The XML example produced by importing the WSDL using the /nosig/verbose/gen="xml", documents what is required in the parameter and should help you decide what to generate. The following guidelines may be helpful:

  • If you plan to use the XML example directly, there is no need to generate the extra entities using /gen. Ordinary entity and occurrence parameters should still be generated, as the connector handles these parameters automatically.
  • Generating entities and then creating components requires extra work, and it requires a good knowledge of the componentToStruct conversion. It may require the schema elements to be extracted from the WSDL so that they can be supplied to the structToXml instruction. You can do this dynamically by reading the WSDL into a Struct.
  • Be careful when Choice model groups are present, as all of the members are generated but only one member should actually be used.
  • Generating entity relationships is a useful means of recording the structure and embedding of complex types.
  • If many of the complex types contain only complex types, few entities will be generated because an entity will only be generated if it contains a simple type field. This also means that the relationships will not be recorded. Generating a primary key field could be useful to force the creation of entities and relationships.
  • Generating entities for ‘any’ wildcard elements or fields for ‘anyAttribute’ wildcard attributes is meant as a type of place holder, because they will inevitably be actually called something else.
  • Be careful if ‘Model Groups’ or ‘any’ elements are present and entities are generated—the naming contains a sequential number which starts counting per import. The import never overwrites existing entities so it is possible that a different entity with that name already exists. Examine the log file from the import carefully to determine exactly what has happened.

Related Topics