Creating a Flow Service from an XML Schema Definition

webMethods 10.2 | Service Development Help | Building Flow Services | Creating a New Flow Service | Creating a Flow Service from an XML Schema Definition

When you create a flow service from an XML Schema definition, Integration Server also creates one or more IS document types and IS schemas.

Keep the following points in mind when creating flow service from an XML Schema definition:

You can specify whether Integration Server enforces strict, lax, or no content model compliance when generating the document type that is referenced in the flow service. Content models provide a formal description of the structure and allowed content for a complex type. The type of compliance that you specify can affect whether Integration Server generates an IS document type or flow service from a particular XML Schema definition successfully. Currently, Integration Server does not support repeating model groups, nested model groups, or the any attribute. If you select strict compliance, Integration Server does not generate an IS document type or flow service from any XML schema definition that contains those items.

Integration Server can create separate IS document types for named complex types or expand documents inline within one document type. For more information, see Determining How to Represent Complex Types in Document Types.

Integration Server can create one field for a substitution group or create fields for every member element in a substitution group. For more information, see Generating Fields for Substitution Groups.

To create a flow service from an XML Schema definition in CentraSite, Designer must be configured to connect to CentraSite.

When creating a flow service from an XML Schema definition that contains a large number of complex type definitions, and you want Integration Server to create a separate IS document for each complex type definition, you may need to increase the number of elements that Designer maintains in cache. If the cache is not large enough to include all of the generated IS document types, then Designer will have to repeatedly retrieve the document types from Integration Server while creating the flow service. This increases network traffic and can prolong the time needed to create the flow service. If the cache is large enough to contain all of the IS document types and other elements generated by Designer while creating a flow service, Designer might create the flow service more quickly. To increase the number of elements cached by Designer, see Caching Elements.

To create a flow service from an XML Schema definition

1. In Designer: File > New > Flow Service

2. In the New Flow service dialog box, select the folder in which you want to save the flow service.

3. In the Element name field, type a name for the flow service using any combination of letters, numbers, and/or the underscore character. For information about restricted characters, see About Element Names.

4. If you have a template you want to use to initialize a default set of properties for the service, select if from the Choose template list.

5. Click Next.

6. On the Select a Source Type panel, select XML Schema. Click Next.

7. On the Select a Source Location panel, under Source location, do one of the following to specify the source file for the flow service:

To use an XML schema definition in CentraSite as the source, select CentraSite.

To use an XML schema definition that resides on the Internet as the source, select File/URL. Then, type the URL of the resource. (The URL you specify must begin with http: or https:.)

To use an XML Schema definition that resides on your local file system as the source, select File/URL. Then, type in the path and file name, or click the Browse button to navigate to and select the file.

8. Click Next.

9. If you selected CentraSite as the source, under Select XML Schema from CentraSite, select the XML Schema definition in CentraSite that you want to use to create the flow service. Click Next.

If Designer is not configured to connect to CentraSite, Designer displays the CentraSite > Connections preference page and prompts you to configure a connection to CentraSite.

10. On the Select Processing Options panel, under Schema domain, specify the schema domain to which any generated IS schemas will belong. Do one of the following:

To add the IS schema to the default schema domain, select Use default schema domain.

To add the IS schemas to a specified schema domain, select Use specified schema domain and provide the name of the schema domain in the text box. A valid schema domain name is any combination of letters, numbers, and/or the underscore character. For information about restricted characters, see About Element Names.

11. Under Content model compliance, select one of the following to indicate how strictly Integration Server represents content models from the XML Schema definition in the resulting IS document type.

Select...	To...
Strict	Generate the IS document type only if Integration Server can represent the content models defined in the XML Schema definition correctly. Document type generation fails if Integration Server cannot accurately represent the content models in the source XML Schema definition. Currently, Integration Server does not support repeating model groups, nested model groups, or the any attribute. If you select strict compliance, Integration Server does not generate an IS document type from any XML schema definition that contains those items.
Lax	When possible, generate an IS document type that correctly represents the content models for the complex types defined in the XML schema definition. If Integration Server cannot correctly represent the content model in the XML Schema definition in the resulting IS document type, Integration Server generates the IS document type using a compliance mode of None. When you select lax compliance, Integration Server will generate the IS document type even if the content models in the XML schema definition cannot be represented correctly.
None	Generate an IS document type that does not necessarily represent or maintain the content models in the source XML Schema definition. When compliance is set to none, Integration Server generates IS document types the same way they were generated in Integration Server releases prior to version 8.2.

12. If you selected strict or lax compliance, next to Preserve text position, do one of the following to specify whether document types generated from complex types that allow mixed content will contain multiple *body fields to preserve the location of text in instance documents.

Select the Preserve text position check box to indicate that the document type generated for a complex type that allows mixed content preserves the locations for text in instance documents. The resulting document type contains a *body field after each field and includes a leading *body field. In instance documents for this document type, Integration Server places text that appears after a field in the *body.

Clear the Preserve text position check box to indicate that the document type generated for a complex type that allows mixed content does not preserve the locations for text in instance documents. The resulting document type contains a single *body field at the top of the document type. In instance documents for this document type, text data around fields is all placed in the same *body field.

13. If this document type will be used as the input or output signature of a service exposed as a web service and you want to enable streaming of MTOM attachment for elements of type base64Binary, select the Enable MTOM streaming for elements of type base64Binary check box.

For more information about streaming of MTOM attachments, see Working with Web Services.

14. If you want Integration Server to use the Xerces Java parser to validate the XML Schema definition, select the Validate schema using Xerces check box.

Note: Integration Server automatically uses an internal schema parser to validate the XML Schema definition. However, the Xerces Java parser provides stricter validation than the Integration Server internal schema parser. As a result, some schemas that the internal schema parser considers to be valid might be considered invalid by the Xerces Java parser.

15. Click Next.

16. On the Select Root Node panel, under Select the root node, select the elements that you want to use as the root elements for the IS document type. The resulting IS document type will contain all of the selected root elements as top-level fields in the generated IS document type

To select multiple elements, press the CTRL key while selecting elements.

If Integration Server determines that the XML Schema definition is invalid, the Select Root Node panel displays an error message to that effect. Click Cancel to abandon the attempt to create a document type.

17. Under Element reference handling, select one of the following to determine how Integration Server handles references to global elements of complex type:

Select...	To...
Only generate document types for elements with multiple references	Instruct Integration Server to create a separate document type for a referenced element only when the XML Schema definition contains multiple references to that element. If an element is referenced multiple times, Integration Server creates a separate document type for the element. Integration Server replaces each element reference with a document reference field. If an element is referenced only once, Integration Server defines the element in line by replacing the element reference with a document field.
Always generate document types for referenced elements	Instruct Integration Server to always create a separate document type for a referenced element even if it is referenced only once. In the document type, Integration Server replaces each element reference with a document reference field

Note: Integration Server always replaces an element reference to an element declaration of simple type with an inline field of type String.

18. Under Complex type handling, select one of the following to indicate how Integration Server handles references to named complex type definitions:

Select...	To...
Expand complex types inline	Use a document field defined in line to represent the content of a referenced complex type definition.
Generate document types for complex types	Create a separate IS document type to represent the content for a referenced complex type definition. The resulting IS document type for the root element represents the element of complex type using a document reference field. In turn, this document reference field refers to the IS document type created for the complex type definition. Integration Server generates a separate IS document type for any types derived from the referenced complex types. For more information about derived types, see Derived Types and IS Document Types.

Note: Integration Server always represents an anonymous complex type using a document field defined inline.

19. If you selected Generate document types for complex types and you want to register each document type with the complex type definition from which it was created, select the Register document type with schema type check box.

Note: If you want derived type support for document creation and validation, select the Register document types with schema type check box. For more information, see Registering Document Types with Their Schema Types.

20. If you want Integration Server to generate IS document types for all complex types in the XML Schema definition regardless of whether the types are referenced by elements or other type definitions, select the Generate document types for all complex types in XML Schema check box.

If you leave this check box cleared, Integration Server generates a separate IS document type for a complex type only if the complex type is referenced or is derived from a referenced complex type.

21. If any of the root elements you selected for the IS document type contain a namespace URI and you want to create a new namespace prefix for it, click Next. Otherwise, continue with step 22.

22. On the Assign Prefixes panel, if you want the IS document type to use different prefixes than those specified in the XML schema definition, select the prefix you want to change and enter a new prefix. Repeat this step for each namespace prefix that you want to change.

Note: The prefix you assign must be unique and must be a valid XML NCName as defined by the specification http://www.w3.org/TR/REC-xml-names/#NT-NCName.

23. Click Finish.

Integration Server generates the flow service, IS document type(s), and IS schema and saves it on the server. Designer displays them in the Package Navigator view.

Notes:

Integration Server uses the internal schema parser to validate an XML schema definition. If you selected the Validate schema using Xerces check box, Integration Server also uses the Xerces Java parser to validate the XML Schema definition. With either parser, if the XML Schema does not conform syntactically to the schema for XML Schemas defined in XML Schema Part 1: Structures (which is located at http://www.w3.org/TR/xmlschema-1), Integration Server does not create an IS schema. Instead, Designer displays an error message that lists the number, title, location, and description of the validation errors within the XML Schema definition. If only warnings occur, Designer generates the IS schema.

Note: Integration Server uses Xerces Java parser version J-2.11.0. Limitations for this version are listed at http://xerces.apache.org/xerces2-j/xml-schema.html.

When validating XML schema definitions, Integration Server uses the Perl5 regular expression compiler instead of the XML regular expression syntax defined by the World Wide Web Consortium for the XML Schema standard. As a result, in XML schema definitions consumed by Integration Server, the pattern constraining facet must use valid Perl regular expression syntax. If the supplied pattern does not use proper Perl regular expression syntax, Integration Server considers the pattern to be invalid.

Note: If the watt.core.datatype.usejavaregex configuration parameter is set to true, Integration Server uses the Java regular expression compiler instead of the Perl5 regular expression compiler. When the parameter is true, the pattern constraining facet in XML schema definitions must use valid syntax as defined by the Java regular expression.

If you selected strict compliance and Integration Server cannot represent the content model in the complex type accurately, Integration Server does not generate any IS document types for the flow service.

If you selected lax compliance and indicated that Integration Server should preserve text locations for content types that allow mixed content (you selected the Preserve text position check box), Integration Server adds *body fields in the document type only if the complex type allows mixed content and Integration Server can correctly represent the content model declared in the complex type definition. If Integration Server cannot represent the content model in an IS document type, Integration Server adds a single *body field to the document type.

The contents of an IS document type with a Model type property value other than “Unordered” cannot be modified.

If the XML schema definition contains an element reference to an element declaration whose type is a named complex type definition (as opposed to an anonymous complex type definition), Integration Server creates an IS document type for the named complex type definition. In the IS document type for the root element, Integration Server uses document reference field to represent the element reference. An exception to this behavior is the situation in which the element reference is the only reference to the complex type definition and the Only generate document types for elements with multiple references option is selected. In this situation, Integration Server uses document field defined in line to represent the content of the referenced complex type.

Integration Server uses the prefixes declared in the XML Schema or the ones you specified as part of the field names. Field names have the format prefix:elementName or prefix:@attributeName.

If the XML Schema does not use prefixes, the Integration Server creates prefixes for each unique namespace and uses those prefixes in the field names. Integration Server uses “ns” as the prefix. The first namespace is “ns1” and the second namespace is “ns2”.

When creating a flow service from an XML Schema definition that imports multiple schemas from the same target namespace, Integration Server throws Xerces validation errors indicating that the element declaration, attribute declaration, or type definition cannot be found. The Xerces Java parser honors the first <import> and ignores the others. To work around this issue, you can do one of the following:

Combine the schemas from the same target namespace into a single XML Schema definition. Then change the XML schema definition to import the merged schema only.

When creating the flow service, clear the Validate schema using Xerces check box to disable schema validation by the Xerces Java parser. When generating the flow service. Integration Server will not use the Xerces Java parser to validate the schemas associated with the XML Schema definition.

Before running a flow service that expects an XML document as input, you must first create a launch configuration that specifies the XML file, and then debug the service in Designer. For information about creating a launch configuration, see Creating a Launch Configuration for Running a Service.