Skip to main content

Using the SOAP Wizard

Using the SOAP Wizard

If you have access to the WSDL that describes a given web service, you can use the SOAP Wizard in Studio to generate a web client for the service.

Note:

If you have enabled a proxy server, Studio uses it when communicating from templates such as the SOAP Wizard. For information about specifying a proxy server and port, see Using a Proxy Server.

To use the SOAP wizard:

  1. In Studio, click Tools > Add-ins > SOAP Wizard.

  2. On the first screen of the SOAP Wizard, specify the location of the WSDL and the SSL configuration required to access it:

    1. Click URL or FILE to indicate the format of the WSDL.

    2. Type the WSDL URL, or browse to the WSDL file.

    3. If you specify a URL that requires SSL authentication (that is, if the URL begins with https), do the following:

      1. Select an SSL configuration from the SSL Configuration drop-down list.

        For information about creating and managing SSL/TLS configurations, see InterSystems TLS Guide.

        Important:

        The SSL Configuration field specifies only the SSL configuration that the wizard uses to access the WSDL.

      2. Optionally, clear the When making an SSL connection check that the server identity in the server certificate matches the name of the system being connected to check box.

        When the check box is selected, the wizard determines whether the certificate server name matches the DNS name used to connect to the server. If the names do not match, the connection is not permitted. This default behavior prevents man in the middle attacks and is described in RFC 2818Opens in a new tab, section 3.1. You can also see RFC 2595Opens in a new tab, section 2.4 for more information.

    4. Click Next.

      The wizard attempts to access and display the WSDL.

      If the wizard is unsuccessful, an error appears. For possible causes, see Problems Consuming WSDLs.

      Tip:

      If the wizard cannot access the WSDL URL after several attempts, you can save the WSDL as a file and browse to it instead.

      If the wizard is successful, the Step 2 screen appears.

    5. If the WSDL URL requires password authentication, specify your credentials:

      1. Select the type of credentials to use:

        • For InterSystems IRIS credentials, select InterSystems IRIS user name and password.

        • For HTTP Basic authentication credentials, select HTTP authentication user name and password.

      2. Fill in the Username and Password fields.

      3. Click Try Again.

        The wizard does not save your entries.

        If the username and password are valid, the Step 2 screen appears.

      For more information, see Using a Password-Protected WSDL URL.

  3. On the Step 2 screen of the SOAP Wizard, specify how the wizard generates classes from the WSDL:

    1. Configure the settings in the Options to control class generation and compilation area.

      For descriptions of the settings, see SOAP Wizard Options to Control Class Generation and Compilation.

    2. Click Next.

      The Step 3 screen appears.

  4. On the Step 3 screen of the SOAP Wizard, specify how the wizard packages the classes it generates from the WSDL:

    1. Configure the settings at the top of the screen to determine how the wizard generates class packages from the XML namespaces in the WSDL.

      For descriptions of the settings, see SOAP Wizard Options for XML Namespaces.

    2. Optionally edit the class package names.

      For information about the Package Name fields, see SOAP Wizard Rules for Class Package Names.

    3. Click Next.

      The wizard generates, compiles, and lists the classes. Then, the Step 4 screen appears.

      Note:

      If the name of an element in the schema begins with an underscore (_), then properties of the class generated for the element begin with a percent sign (%).

  5. Click Finish.

SOAP Wizard Options to Control Class Generation and Compilation

The Step 2 screen of the SOAP wizard includes the following options, which enable you to specify the types of classes that the wizard generates from the WSDL.

Create Client for Web Service

Indicates whether the wizard generates proxy classes that function as a client for the web service defined by the WSDL.

Create Web Service

Indicates whether the wizard generates classes that function as an InterSystems IRIS web service based on the WSDL.

Compile generated classes

Indicates whether the wizard compiles classes after generating them.

If you select Compile generated classes, you can control the behavior of the compiler by specifying flags in the Compile flags field. For more information, execute the following command:

 Do $System.OBJ.ShowFlags()
Class Type

Specifies the type of classes that the wizard generates from the WSDL. You can select one of the following options:

  • Persistent — Specifies that the classes inherit from %PersistentOpens in a new tab, and collections are defined as lists.

  • Persistent using one-many relationships — Specifies that the classes inherit from %PersistentOpens in a new tab, and collection properties are defined as one-to-many relationships.

  • Persistent using indexed one-many relationships — Specifies that the classes inherit from %PersistentOpens in a new tab, collection properties are defined as one-to-many relationships, and InterSystems IRIS defines an index for each relationship.

  • Persistent using parent-child for relationships — Specifies that classes inherit from %PersistentOpens in a new tab, and any collection properties are defined as parent-child relationships.

  • Serial — Specifies that classes inherit from %SerialObjectOpens in a new tab.

  • Registered — Specifies that classes inherit from %RegisteredObjectOpens in a new tab.

Add %OnDelete method to classes in order to cascade deletes

For persistent class types, indicates whether to implement the %OnDelete() callback method for each generated class definition. Do not use this option if you select Persistent using parent-child for relationships.

The generated %OnDelete() method deletes all persistent objects that are referenced by the class.

If you modify the generated classes, be sure to modify the corresponding %OnDelete() callback methods as needed.

Proxy Class Package

Package name for the web client and any generated classes.

The default package name is the service name.

If you specify an existing package name, the tool overwrites any existing class that has the same name as a newly generated class by default.

Create Business Operation

Indicates whether to generate a business operation and related request and response message classes, which you can use in a production.

For information about productions, see Introducing Interoperability Productions and Creating Web Services and Web Clients in Productions.

If you select Create Business Operation, you must specify the following values:

  • Business Operation Package — Package name for the business operation class.

  • Request Package — Package name for the request message class.

  • Response Package — Package name for the response message class.

SOAP Wizard Options for XML Namespaces

The Step 3 screen of the SOAP wizard includes the following options, which enable you to configure the class packages generated from the WSDL:

Add NAMESPACE class parameter

Indicates whether the generated type class will include the NAMESPACE class parameter set equal to the namespace of the web service.

  • If the WSDL explicitly indicates the namespace to which a given type belongs, Add NAMESPACE Class Parameter is selected and grayed out. In this case, the generated type class includes the NAMESPACE class parameter set equal to that namespace.

  • If the WSDL does not indicate the namespace for a given type, you can select or clear Add NAMESPACE Class Parameter.

Use unwrapped message format for document style web methods

Indicates whether to use an unwrapped message format for the methods in the generated web client. This option affects only methods that have SoapBindingStyle equal to "document".

If either of the following statements are true of the WSDL, select this check box:

  • The <message> elements contain multiple parts.

  • The types used by the response messages belong to multiple namespaces.

Alternatively, the wizard fails and displays an error message such as the following:

ERROR #6425: Element 'wsdl:binding:operation:msg:input' - message 'AddSoapOut' 
Message Style must be used for document style message with 2 or more parts.

For more information, see Details of the Generated Classes and Using InterSystems IRIS Web Client Classes.

Do not create array properties

Indicates whether the wizard generates array properties.

If you select this option, the wizard does not generate array properties but instead generates another form. For more information, see Creation of Array Properties.

Generate XMLNIL property parameter for nillable elements

Indicates whether the wizard specifies the XMLNIL property parameter for applicable properties in the generated classes.

This option applies to each property that corresponds to an XML element that is specified with nillable="true". If you select this option, the wizard adds XMLNIL=1 to the property definition. Otherwise, it does not add this parameter.

For details on this property parameter, see Handling Empty Strings and Null Values.

Generate XMLNILNOOBJECT property parameter for nillable elements

Indicates whether the wizard specifies the XMLNILNOOBJECT property parameter for applicable properties in the generated classes.

This option applies to each property that corresponds to an XML element that is specified with nillable="true". If you select this option, the wizard adds XMLNILNOOBJECT=1 to the property definition. Otherwise, it does not add this parameter. For details on this parameter, see Handling Empty Strings and Null Values.

Set XMLSEQUENCE parameter to 0

Indicates whether the wizard sets the XMLSEQUENCE class parameter in the generated classes to 0.

By default, the wizard sets this parameter to 1 in the generated classes, which ensures that the classes respect the order of elements as given in the schema in the WSDL. This value is useful when the schema has multiple elements of the same name within a given parent. For details, see Handling a Document with Multiple Tags with the Same Name.

Generate XMLIGNORENULL parameter set to 1

Indicates whether the wizard specifies the XMLIGNORENULL class parameter in the generated classes.

If you select this option, the wizard adds XMLIGNORENULL=1 to the class definitions, including the generated web client (or web service). Otherwise, it does not add this parameter.

For details on this class parameter, see Handling Empty Strings and Null Values.

Use Streams for Binary

Indicates whether the wizard generates a property of type %Stream.GlobalBinaryOpens in a new tab for each element of type xsd:base64Binary.

If you select this option, the generated properties are of type %Stream.GlobalBinaryOpens in a new tab. Alternatively, the properties are of type %xsd.base64BinaryOpens in a new tab.

The wizard ignores any attributes of type xsd:base64Binary.

Specify SECURITYIN class parameter

Specifies the value of the SECURITYIN class parameter in the generated client class.

If you are using Web-Services security, use REQUIRE or ALLOW, depending on whether you want the client to require the elements or simply validate them. Otherwise, IGNORE or IGNOREALL is generally suitable. For details, see Validating WS-Security Headers.

The SECURITYIN parameter is ignored if there is a security policy in an associated (and compiled) configuration class. See Securing Web Services.

SOAP Wizard Rules for Class Package Names

The SOAP Wizard applies the following rules for class package names:

  • The packages specified in the Web Client Package and Web Service Package fields contain the main generated web client or web service class. These values are initialized by your entry in the previous page of the wizard.

  • If the wizard generates a policy class as well (because the WSDL contains WS-Policy information), that class is in the same package by default. To specify a different package, specify a value for Configuration Sub-Package.

    By default, the class name is the web client or service name, with Config appended to it. If you specify a value for Configuration Sub-Package, then this generated class has the same name as the web client or service (but is in the given subpackage instead).

    For information on WS-Policy, see Securing Web Services.

  • For any supporting classes that are generated, the wizard detects all the namespaces used in the WSDL. By default, it organizes the generated classes into packages, with one package for each namespace.

    Optionally edit these package names.

    Not all namespaces necessarily correspond to generated classes. For example, the WSDL used in this example uses the namespaces https://schemas.xmlsoap.org/wsdl, https://schemas.xmlsoap.org/wsdl/mime, and https://schemas.xmlsoap.org/wsdl/soap. No generated classes are in these namespaces in this case, and the corresponding packages are not generated.

FeedbackOpens in a new tab