External Definitions 

Use

There is a series of standard schema for describing the message structure at runtime. WSDL (Web Service Description Language), XSD (XML Schema Definition Language), or DTDs (Document Type Definitions) are often used to describe message schema. If a description of the message structure already exists in one of the above formats, you can use it in the ES Repository by importing it as an external definition rather than re-entering it manually using the data type editor.

See also: Messages.

Integration

An external definition enables you to import a local WSDL, XSD, or DTD file to the ES Repository and specify which parts of the schema to extract as the description for a message. You can use these extracted message schema as:

●      Request, response, or fault messages in operations of service interfaces

●      Source or target structures for message mappings

In the ES Builder, assigned message schema are labeled as  External Message. As when structuring service interfaces, message schema have the same meaning as message types.

For technical reasons, proxy generation and the respective editors in the ES Builder do not support the entire language range of XML schema and WSDL. An overview of which language elements are supported is available in SAP Developer Network (SDN) at https://www.sdn.sap.com/irj/sdn  → SOA Middleware  → Repository-Based Modeling and Design. In the Knowledge Center on the Repository-Based Modeling and Design page, choose Enterprise Services Repository & Registry and on the subsequent page select the Supported XML Schema and WSDL document.

Prerequisites

The document to be imported must conform to the WSDL, XSD, or DTD standard.

Features

Extracting Message Schema

If the file is not already in WSDL format, the ES Builder converts imported external definitions to a WSDL definition more suitable for further use. During this procedure, the ES Builder identifies the definitions that describe the message structure. Depending on the imported format, you can define the mode for this procedure before import:

Modes for Importing External Definitions

External Format	Selection Options in Messages List Box	Meaning
WSDL	Do Not Extract Messages	Definition imported without conversion, to enable central access to the external definition.
	All Message Definitions Contained	All message definitions extracted in WSDL. If the message definition contains more than one part, all parts are grouped together using a superordinate part.
	Using RPC Style	See: Import for WSDL Documents in RPC Style.
XSD	Do Not Extract Messages	See above.
	All Elements Contained	All element definitions interpreted as message schema.
	All Unreferenced Elements	Only those element definitions that are not referenced by another element are interpreted as message schema.
DTD	Do Not Extract Messages	See above.
	Message from DOCTYPE	DOCTYPE tag interpreted as message schema.
	Message from First ELEMENT	First ELEMENT tag interpreted as message schema.

Sources and References to External Documents

WSDL, XSD, and DTD documents can all reference each other. These references are supported as follows in external definitions:

●      ES Builder checks for references when it imports a document. Any references it finds are displayed on the External References tab page for the external definition created for the document.

●      The reference can only be evaluated within the ES Repository if there is another external definition in the same namespace as the external definition to be referenced that has the same string entered as its source as that which is displayed on the External References tab page. In other words, the source corresponds to the reference that is contained in the referencing document. You specify the source in the Source attribute in the editor for the referenced external definition.

A referencing XSD document contains the following <xsd:import schemaLocation="../common.xsd" />. After this document has been imported, the External References tab page specifies that a second external definition with the source ../common.xsd must be referenced to be able to follow the reference. The reference can be followed if you create a second external definition in the same namespace for the file common.xsd, then import the file using this external definition, and finally enter the string ../common.xsd as the source of this external definition. The editor displays the referenced external definition on the External References tab page for the referencing external definition. 

Since references between files usually require a directory structure on the file system, reference conflicts can occur in the ES Repository during the import. More information and examples: Mass Import for External Definitions.

Activities

...

       1.      To import multiple external definitions together, in the ES Builder main menu, choose Tools → Import External Definitions.

More information: Mass Import for External Definitions.

The following describes the procedure for importing single external definitions.

Create an external definition (see: Creating a New Object).

       2.      In the Category list field, choose whether you want to import a WSDL, XSD, or DTD document. This setting determines which selection options are available to you in the Mode list field.

       3.      In the Mode list field, choose which parts of the document you want to interpret as a message schema (see above).

       4.      Use the file dialog to choose a file to upload to the ES Repository. Due to technical reasons, the ES Builder can only note the file name and not the file directory path.

       5.      Once you have selected the file, use the tab pages to call up the following information:

○       Imported Document: Your file in text format.

○       Messages: The message schema that have been extracted using the selected mode.

○       WSDL: The result of the conversion to WSDL.

○       External References: Overview of the references used in the imported document. This will show any other imported documents that have been recognized.

       6.      If you want to make it possible for other external definitions to reference your imported document, enter the corresponding unique document ID in the Source field. This ID must correspond to the string that is used in other documents to reference this document. In this way the ES Builder can assign documents that reference each other to each other (see above).

Example

You want to import an XSD document myMessage to the ES Repository; this document references three other XSD documents myStr1, myStr2, and myStr3 by using the <include> statement. To import the documents individually, procedure as follows: First, import myMessage. The External References tab page then displays that three documents are referenced and that these documents are not yet in the ES Repository. Next, create further external definitions for myStr1, myStr2, and myStr3 in the same namespace and specify the source for each of these documents. If the source is not contained in the document itself, you will find it in the referencing document. If you refresh the display of the external definition for myMessage, the External References tab page shows that the documents have been found in the ES Repository. You can then navigate to the other referenced external definitions in the ES Repository by double clicking.