IMS General Web Services Base Profile Version 1.0 Final Specification

Copyright © 2005 IMS Global Learning Consortium, Inc. All Rights Reserved.
The IMS Logo is a registered trademark of IMS/GLC
Document Name: IMS General Web Services Base Profile
Revision: 19 December 2005

IPR and Distribution Notices

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

IMS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on IMS's procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Copyright © 2005 IMS Global Learning Consortium. All Rights Reserved.

If you wish to copy or distribute this document, you must complete a valid Registered User license registration with IMS and receive an email from IMS granting the license to distribute the specification. To register, follow the instructions on the IMS website: http://www.imsglobal.org/specificationdownload.cfm.

This document may be copied and furnished to others by Registered Users who have registered on the IMS website provided that the above copyright notice and this paragraph are included on all such copies. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to IMS, except as needed for the purpose of developing IMS specifications, under the auspices of a chartered IMS project group.

Use of this specification to develop products or services is governed by the license with IMS found on the IMS website: http://www.imsglobal.org/license.html.

The limited permissions granted above are perpetual and will not be revoked by IMS or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.

Executive Summary

The General Web Service Base Profile provides a basic structure for the definition of Web Services. It consists of a set of non-proprietary Web services specifications, along with clarifications and amendments to those specifications that promote interoperability. The General Web Services Base Profile addresses the most common problems experienced when implementing web service specifications. The General Web Services Base Profile defines the selection of mechanisms within referenced specifications that are well understood, widely implemented and useful.

The General Web Services Base Profile promotes interoperability for web service based specification implementations on different software and vendor platforms. The Base Profile focuses on a core set of web service specifications and the most common problems experienced implementing the identified web service specifications. It is not a goal of the General Web Services Base Profile to create a plug-and-play architecture for web services or to guarantee complete interoperability. The General Web Services Base Profile addresses interoperability in the application layer, in particular, the description of behaviors exposed via Web Services.

The General Web Service Base Profile is derived from the Web Services Interoperability Basic Profile v1.1 and the Web Services Interoperability Simple SOAP Binding Profile v1.0. The IMS Global Learning Consortium (IMS/GLC) recommendations for the General Web Service Base Profile are to adopt:

• XML Schema V1.0 - all data models in IMS specifications will be defined in terms of XML Schema (XSD);
• HTTP V1.1 - the Hypertext Transfer Protocol (HTTP) is the mandated protocol binding for the SOAP messages;
• SOAP V1.1 - SOAP is the mandated messaging protocol;
• WSDL V1.1 - an instance of the service is defined using Web Services Description Language (WSDL) v1.1.

The General Web Service Base Profile can be extended by the adoption of one or more support General Web Service profiles. Other IMS General Web Service documents describe profiles for Addressing (transport-neutral web service addressing), Attachments (sending non-XML documents with the SOAP messages) and Security (secure data exchange).

In principle, the SOAP-based binding for the web services supports many communications messaging models (the Information Model for an IMS/GLC specification is defined independently of the messaging nature, i.e., this is determined by the form of the Web Services Description Language binding). At the current time only one messaging model is supported:

• Synchronous - this is a request/response message exchange in which the service initiator is blocked until the response message is received

Further messaging models will be added as and when required, i.e., asynchronous, polled, and publish and subscribe. There are three methods by which the functional capability of the base profile can be extended:

• Addition of new SOAP messages - the addition of new business transactions and the usage of new messaging models requires the creation of new SOAP messages;
• Extensions to the SOAP header - the current IMS General Web Service Base Profile makes use of the SOAP header to contain the application-to-application transaction status information. It is recommended that proprietary extensions to the SOAP header maintain the current usage patterns;
• Extensions in the data contained within the SOAP body - the SOAP body contains the XML instance that is used to represent the parameters defined for the transaction operations in the specification. There may be a need to add new parameters or to extend the XML structures of the current parameters.

The IMS General Web Service documentation is augmented with a substantial set of support tools that enables organizations to create their own Web Services Description Language bindings based upon the IMS General Web Service. Other materials enable .NET and J2EE implementations to be built based upon reference implementations of the IMS General Web Service.

Table of Contents

1. Introduction

1.1 Scope and Context

The objective of the General Web Services activity is to provide a framework for guiding project teams looking to use web services as part of IMS Global Learning Consortium (IMS/GLC) specification development. A General Web Services service binding will provide a methodology and an application profile that meets the following criteria:

• Interoperability - Artefacts produced under the General Web Services activity will seek to identify mechanisms and standards that promote interoperability between web service specification implementations across different software and operating system platform;
• Efficiency - Artefacts produced under the General Web Services activity will be designed to help other IMS project teams efficiently and effectively evaluate web services protocols as they pertain to the functional requirements of the project team;
• Consistency - Artefacts produced under the General Web Services activity will be designed to facilitate the implementation of consistent approach to the implementation of web service protocols across IMS project teams and specifications;
• Flexibility - Artefacts produced under the General Web Services activity will be flexible enough to adapt to evolving web service protocols such as 'SOAP'/'SOAP with message attachments' and to work with a variety of binding methods for web services such as Web Services Description Language (WSDL);
• Practicality - Artefacts produced under the General Web Services activity will seek to facilitate vendor's ability to implement IMS/GLC based Web Service solutions and interoperability across platforms and vendor implementations of web service protocols.

The General Web Services Base Profile (GWSBP) provides a basic structure for the definition of Web Services. It consists of a set of non-proprietary Web Services specifications, along with clarifications and amendments to those specifications that promote interoperability. The General Web Services Base Profile addresses the most common problems experienced implementing web service specifications. The General Web Services Base Profile defines the selection of mechanisms within referenced specifications that are well understood, widely implemented and useful. The General Web Services Base Profiles will contain syntax conventions consistent with IMS Specification Development Methodology [SpecDev, 03] and Abstract Framework [AbsASCs, 03], [AbsGloss, 03], [AbsWhite, 03].

The General Web Services Base Profile promotes interoperability across web service based specification implementations on different software and vendor platforms. The Base Profile is focused on a core set of web service specifications and the most common problems experienced implementing the identified Web Service specifications. It is not a goal of the General Web Services Base Profile to create a plug-and-play architecture for web services or to guarantee complete interoperability. The General Web Services Base Profile addresses interoperability in the application layer, in particular, the description of behaviors exposed via Web Services. The General Web Services Base Profile assumes the interoperability of the lower layer protocols is sufficient.

Included in this document is a set of recommendations and best practices including how to extend the General Web Services Base Profile. The extensions will have guidance for creating Web Services binding for the Abstract Framework's common services layer such as error handling, security, manifest, context and routing. IMS/GLC has defined a complementary set of profiles that build upon the Base Profile to incorporate more of the Web Services standards and specification developed by the World Wide Web Consortium (W3C). Therefore, this document should be read in conjunction with the set of IMS General Web Services extension profiles [GWS, 05a], [GWS, 05b], [GWS, 05c] and the IMS General Web Services WSDL Binding Guidelines [GWS, 05d]. The terms of reference for the creation of both documents are defined in the original project charter [GWS, 03a].

1.2 Structure of this Document

The structure of this document is:

1.3 Nomenclature

1.4 References

2. Context for the GWS Profiles

2.1 Syntax Conventions

2.1.1 Recommendations from the IMS Abstract Framework

All IMS service-oriented specifications will be defined in the context of the IMS Abstract Framework [AbsWhite, 03], [AbsASC, 03], [AbsGloss, 03]. Web services are one possible binding of an IMS service-oriented specification. Section 4 of this document describes how an IMS specification as defined by an Information Model is related to web services through the appropriate 'Infrastructure Binding'.

2.1.2 Recommendations from the International Conformance Program

The IMS International Conformance Program is responsible for defining how a particular information model and binding is constrained to support a particular domain in the form of an Application Profile Guidelines [APG, 05a], [APG, 05b]. Support for Conformance Testing will be added where appropriate, e.g., the WS-I enables conformance statements to be added to a WSDL file.

2.1.3 Recommendations from the IMS Binding Auto-generation Toolkit

The IMS Binding Auto-generation Toolkit document describes how the Unified Modelling Language (UML) is to be used to document an IMS information model [GWS, 05e]. The UML description is designed to facilitate the corresponding bindings, i.e., the UML description is not designed from the perspective of implementation as an Application Programming Interface (API). The UML description is also made available as an XML Metadata Interface (XMI) file; this enables tools to import the UML description and generate the corresponding code stubs. IMS has developed XML Stylesheet Language Transformations (XSLT) files to support automated UML conversion to WSDL, etc. The usage of these XSLTs and the corresponding tool is explained in the IMS Binding Auto-generation Toolkit Manual [GWS, 05e].

2.1.4 Recommendations from W3C Web Service Architecture

The Web Service Architecture (WSA) is a normative document that seeks to provide a context and model for understanding Web services and to facilitate placing Web services specifications and technologies within a larger Web Services framework and with other technologies outside of WSA. The WSA's goal is to promote interoperability through the common definition of a web service and its core concepts and relationships. The purpose of WSA is not to specify how Web services are implemented or to impose restrictions on combination or coordination of Web services. WSA provides discussion of the WSA's core concepts and relationships from various perspectives. Where appropriate, IMS will use the WSA in the IAF.

For more information on the Web Services Architecture, go to W3C Web Services Architecture (http://www.w3.org/TR/ws-arch/).

2.1.5 Recommendations from Web Services Interoperability Basic Profile

The IMS GWS Base Profile is based upon the WS-I Basic Profile v1.1 [WSI, 04a] and the WS-I Simple SOAP Binding Profile v1.0 [WSI, 04d]. The WS-I Basic Profile is shown in Table 2.1.

It is recognized that SOAP v1.2 and WSDL v2.0 are available as later versions of the SOAP and WSDL specifications respectively. SOAP v1.2 and WSDL v2.0 will be considered for future revisions.. It should be noted, that from the perspective of adopted specifications, the combination of the WS-I Basic Profile v1.1 and Simple SOAP Binding Profile v1.0 is identical to the WS-I Basic Profile v1.0a [WSI, 03].

2.2 Core Technologies

2.2.1 XML

XML 1.0 (Third Edition) is the core data representation technology adopted for the binding of IMS specifications [XML, 04]. An IMS data-model oriented information model can be defined as a hierarchy. Hierarchical models are convenient for representing data consisting of many elements and sub-elements. XML is perfectly suited for representing hierarchical models.

2.2.2 XML Schemas

XML Schema Definition (XSD) is the primary XML binding control document format of IMS (at present these bindings are working to the May 2001 version of XML Schema) [XSD, 01]. The XSD defines elements, their content models, and attributes. It also defines the standard IMS vocabularies. The XSD defines the element types and attribute groups separately from the elements. The key recommendations for XML Schema with respect to the Base Profile are:

1. When used in the context of SOAP messages all data constructs should be defined as elements. Attributes should not be used. This follows the recommendation of the WS-I;
2. All data types should be defined as 'Global'. The usage of 'Local' data types causes problems for some of the WSDL import tools, e.g., Axis;
3. All data types should have the character string ".Type" at the end of their name. This avoids naming conflicts between instances and their types.

2.2.3 SOAP

SOAP is a messaging protocol for XML documents which can be used for exchanging structured and typed information between peers in a decentralized, distributed environment [SOAP, 03a], [SOAP, 03b]. It is a stateless, one-way message exchange mechanism, but applications can create more complex interaction patterns (e.g., request/response, request/multiple responses, etc.) by combining such one-way exchanges with features provided by an underlying transport protocol and/or application-specific information. SOAP provides the framework by which application-specific information may be conveyed in an extensible manner. Also, SOAP provides a full description of the expected actions taken by a SOAP processor on receiving a SOAP message.

A SOAP message contains two SOAP-specific sub-elements within the overall Envelope: the 'Header' and 'Body'. The contents of these elements are application defined and not a part of the SOAP specifications, although the latter does have something to say about how such elements must be handled. The 'Header' is optional. Headers have been designed in anticipation of various uses for SOAP, many of which will involve the participation of other SOAP processing nodes along a message's path from a sender to an ultimate receiver, to allow SOAP processors to exchange information to provide value-added services. These form the mechanism by which SOAP messages may be extended in an application-specific manner. The 'Body' is the mandatory element within an Envelope and this is where the main information conveyed in a SOAP message must be carried. The immediate child elements of a 'Header' are called header blocks, and represent some logical grouping of data that can be targeted at SOAP nodes encountered in the path of a message from a sender to a receiver.

The SOAP envelope is the container for the messages to be exchanged between the systems. These messages need to be physically transmitted across the communications system using an appropriate transport mechanism. In many cases the Hypertext Transport Protocol (HTTP) is used as this transport mechanism. The key recommendations for XML Schema with respect to the Base Profiles are:

1. Only bindings based upon SOAPv1.1 across HTTPv1.1 are supported;
2. The SOAP message body contains all of the parameters defined in the corresponding operation;
3. The status information is to be placed in the SOAP message header.

2.2.4 WS-Addressing

Web Services Addressing (WS-Addressing) defines two interoperable constructs that convey information that is typically provided by transport protocols and messaging systems. These constructs normalize this underlying information into a uniform format that can be processed independently of transport or application. The two constructs are 'endpoint references' and 'message information' headers. Both of these constructs are designed to be extensible and re-usable so that other specifications can build on and leverage endpoint references and message information headers.

A Web service endpoint is a (referenceable) entity, processor, or resource where Web service messages can be targeted. Endpoint references convey the information needed to identify/reference a Web service endpoint, and may be used in several different ways: endpoint references are suitable for conveying the information needed to access a Web service endpoint, but are also used to provide addresses for individual messages sent to and from Web services. To deal with this last usage case this specification defines a family of message information headers that allows uniform addressing of messages independent of underlying transport. These message information headers convey end-to-end message characteristics including addressing for source and destination endpoints as well as message identity.

2.2.5 Attachments for SOAP Messages

Attachments for SOAP messages are available in several forms:

1. SOAP with Attachments (SOAPwA) - SOAP With Attachments (SOAPwA) extends SOAPv1.1 by providing a MIME binding to support multiple message payloads, while ignoring the convention by which Remote Procedure Call (RPC) arguments may be marshalled and unmarshalled in XML. SOAPwA is especially suited for use cases where the two communicating parties are NOT located within the same organization, and the exchange paradigm is therefore more one of asynchronous Document Exchange across the Internet, than synchronous Remote Procedure Call within a single business (or University) enterprise;
2. WS-Attachments - this specification defines an abstract model for SOAP attachments and based on this model defines a mechanism for encapsulating a SOAP message and zero or more attachments in a DIME message. SOAP attachments are described using the notion of a compound document structure consisting of a primary SOAP message and zero or more related documents known as attachments;
3. Message Transmission Optimization Mechanism (MTOM) - MTOM is one of the W3C message attachment approaches to enable SOAP messages to contain non-XML objects. MTOM is a development of SOAPwA and is proposed as a replacement for the original SOAPwA specification.

The equivalent attachments recommendations for IMS GWS are defined in the IMS GWS Attachments Profile document [GWS, 05b].

2.2.6 WSDL

A WSDL document defines services as collections of network endpoints, or ports. In WSDL, the abstract definition of endpoints and messages is separated from their concrete network deployment or data format bindings. This allows the reuse of abstract definitions: messages, which are abstract descriptions of the data being exchanged, and port types that are abstract collections of operations. The concrete protocol and data format specifications for a particular port type constitute a reusable binding. A port is defined by associating a network address with a reusable binding and a collection of ports defines a service. Hence, a WSDL document uses the following elements in the definition of network services:

• Types - a container for data type definitions using some type system (such as XSD);
• Message -an abstract, typed definition of the data being communicated;
• Operation - an abstract description of an action supported by the service;
• Port Type -an abstract set of operations supported by one or more endpoints;
• Binding - a concrete protocol and data format specification for a particular port type;
• Port - a single endpoint defined as a combination of a binding and a network address;
• Service - a collection of related endpoints.

The key recommendations for WSDL with respect to the Base Profile are:

1. A separate set of WSDL files are defined for each type of communication mode being supported by the binding and there will be one form of the WSDL binding will be contained within a single physical file;
2. Alternatively there will be a split file binding in which the XSD information is defined in a separate file from that which contains the rest of the WSDL definition. The WSDL file imports the XSD definitions using the <xsd:import> construct;
3. The second alternative is to have the WSDL definition split into the service specific and abstract files plus the XSD, i.e., to create three separate but linked files. The service-specific file imports the abstract definitions using the <wsdl:import> construct and the abstract definitions file imports the XSD definitions using the <xsd:import> construct;
4. The final alternative is to have the two separate WSDL files plus several XSD files. The data schema and the message structure schema will be defined in separate files. The message structure XSD will contain all of the messages required for the different communication modes to be supported.

2.2.7 WS-Security

WS-Security defines a standard way to incorporate security information into a SOAP message using existing security standards for confidentiality, integrity, non-repudiation, authentication and authorization. WS-Security provides a method for representing security information in a SOAP message. WS-Security defines a way to pass security tokens, such as a simple username, SAML, X.509 certificates and Kerberos tickets, a mechanism using XML Signature to digitally sign all or part of a SOAP message, a mechanism using XML Encryption to encrypt part of a SOAP message and a method for attaching signature and encryption headers to a SOAP message. The equivalent security profile for IMS GWS is defined in the IMS GWS Security Profile [GWS, 05c].

2.2.8 Choreography

IMS plans to adopt the appropriate message and service choreography specifications, as opposed to creating its own. The underlying message choreography support in the GWS bindings are detailed in Section 5 of this document. Reliable messaging is only supported as a feature of the underlying communications infrastructure, e.g., through the usage of the Transmission Control Protocol (TCP). When stable, the following specifications will be adopted:

1. Web Services Reliable Messaging Framework (WS-Reliability) [WSR, 03] - the purpose of WS-Reliability is to address reliable messaging requirements, which become critical, for example, when using Web Services in B2B applications. SOAP [SOAP1.1] over HTTP [RFC2616] is not sufficient when an application-level messaging protocol must also address reliability and security. While security is getting traction in the development of Web Services standards, reliability is not. This specification is intended as an initial proposal for defining reliability in the context of current Web Services standards. The specification borrows from previous work in messaging an transport protocols, e.g., SOAP, and the ebXML Message Service. It proposes appropriate modifications to apply this work to Web Services;
2. Web Services Choreography Description Language Version 1.0 (W3C Working Draft 27 April 2004) - Web Services Choreography Description Language (WS-CDL) is an XML-based language that describes peer-to-peer collaborations of Web Services participants by defining, from a global viewpoint, their common and complementary observable behavior; where ordered message exchanges result in accomplishing a common business goal. The Web Services specifications offer a communication bridge between the heterogeneous computational environments used to develop and host applications. The Web Services Choreography specification is targeted for composing interoperable peer-to-peer collaborations between any type of Web Service participant regardless of the supporting platform or programming model used by the implementation of the hosting environment;
3. Business Process Execution Language for Web Services (BPEL4WS - BPEL4WS (or BPEL for short) is an XML-based standard for defining Web services can be combined to implement business processes [BPEL, 03]. It builds WSDL and XSD. BPEL provides an XML notation and semantics for specifying business process behavior based on Web Services. A BPEL4WS process is defined in terms of its interactions with partners. A partner may provide services to the process, require services from the process, or participate in a two-way interaction with the process. Thus BPEL orchestrates Web Services by specifying the order in which it is meaningful to call a collection of services, and assigns responsibilities for each of the services to partners. It can be used to specify both the public interfaces for the partners and the description of the executable process.

3. Base Profile Rules

3.1 IMS Base Profile

The IMS GWS Base Profile is defined in Table 3.1. The only difference between this profile and that of the WS-I Basic Profile/Simple SOAP Binding Profile is that the UDDI specification is not included in the profile.

3.2 Base Profile Rules Derived from WS-I Basic Profile

Table 3.2 summarizes the set of rules used in the WS-I Basic Profile v1.1 and their equivalent adoption status for the IMS GWS Base Profile. Within Table 3.2 the following conventions are used:

• The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119;
• Normative statements in the Profile, i.e., those impacting conformance, as outlined in "Profile Conformance", are presented in the following manner: RnnnnStatement text here, where "nnnn" is replaced by the statement number. Each statement contains exactly one requirement level keyword, e.g., "MUST", and one conformance target keyword, e.g., "MESSAGE".

Table 3.3 summarizes the set of extension points available in the WS-I Basic Profile v1.1 and thus within the IMS GWS. Extensibility points in underlying specifications are presented as:

• EnnnnExtensibility Point Name - Description, where "nnnn" is replaced by a number that is unique among the extensibility points in the Profile. As with requirement statements, extensibility statements can be considered namespace-qualified.

3.3 Base Profile Rules Derived from WS-I Simple SOAP Binding Profile

Table 3.4 summarizes the set of rules used in the WS-I Simple SOAP Profile v1.0 and their equivalent adoption status for the IMS GWS Base Profile. Within Table 3.4 the following conventions are used:

• The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119;
• Normative statements in the Profile, i.e., those impacting conformance, as outlined in "Profile Conformance", are presented in the following manner: RnnnnStatement text here, where "nnnn" is replaced by the statement number. Each statement contains exactly one requirement level keyword, e.g., "MUST", and one conformance target keyword, e.g., "MESSAGE".

3.4 Summary of Differences between IMS and WS-I Profiles

The key points for the IMS Base profile are that:

1. SOAP fault messages will not be defined in the binding WSDL. All status information is carried in the StatusInfo/StatusInfoSet object. If SOAP fault codes are received then these must be mapped to the StatusInfo/StatusInfoSet objects as defined by IMS [GWS, 05];
2. The usage of WS-I Conformance Claims is not required. If these are used then they have implementation-specific relevance;
3. UDDI is not a part of the profile;
4. 'Document-literal" encoding is used, i.e., the is no "rpc-lteral" encoding.

4. Relationship to the Abstract Framework

4.1 IAF Overview

The IMS/GLC Abstract Framework (IAF) can be represented as a layered model [AbsWhite, 03], [AbsASC, 03], [AbsGloss, 03], as shown in Figure 4.1, consisting of four layers:

• Application layer - this is a tool, system, agent, etc. that presents the appropriate application services to the user, i.e., an application manages the user interface. The application may use one or more application services but whenever possible the system composition should be hidden from the user;
• Application Services layer - a set of services that provide the required eLearning functionality to the applications. An application service may make use of one or more common services. Distributed application services communicate using via the Infrastructure Layer;
• Common Services layer - a set of services that are available to the application services. Common services may use other common services. Therefore, a common service is available to any other service;
• Infrastructure layer - this provides the end-to-end transaction and communications services for the application and common services.

Access to a service is through the appropriate Service Access Point (SAP). Each service has a single SAP. A Component may support one or more SAPs (in an object oriented representation, a SAP could be supported by one or more operators where the class is itself the definition of the service).

In a distributed implementation of this layered framework, as typified in a webs services environment, the interaction between the services would as shown in Figure 4.2. In this interaction framework there are three categories of interface that must be supported by the Infrastructure layer namely:

• The Application Services interface (A1) - this interface is used to provide interoperability between common application services, e.g., Enterprise-to-Enterprise systems. One form of the interface is based upon XML-messaging;
• The Common Services interface (A2) - this interface is used to provide interoperability with the set of common services that are made available to the application specific services, e.g., authentication and authorization for an Enterprise system;
• The run-time interface (B) - this interface is used to interconnect the client's run-time application with the remote service provider.

Figure 4.2 shows that there are two types of interaction behavior that need to be specified to ensure interoperability, namely:

• Message passing - where information is exchanged between systems using some form or another of message exchange. The content and sequence of the messages define the expected behavior. The communicating systems are expected to process and generate the messages as a response to known and understood events. The systems must be capable of handling unknown error conditions;
• Run-time - where the end systems have to reliably operate on information using some predefined algorithm. The data will determine the outcomes of the algorithms but the behavior is well defined for all possible outcomes.

The IMS/GLC specifications are focused on data exchange interoperability. To this end they define a data model of the information to be exchanged and a behavioral model that encapsulates the data model and constrains the way in which the data can be manipulated. An IMS/GLC information model is the manifestation of this behavioral and data description and an information model will consist of one or more IMS/GLC Components (these will realize either all, or part of, an Application Service). These components can then be realized in a variety of ways; the defined IMS/GLC method is as an XML-based binding. As such, this binding describes the way in which the data is exchanged in the form of XML messages/documents, however the actual transfer of these structures requires, at the very least, an appropriate communications system.

The exchange of the data between the XML components within the abstract framework is defined through the Infrastructure Layer. A schematic representation of the system components in this infrastructure description is shown in Figure 4.3. This representation assumes that the system is loosely coupled, e.g., as per web services.

In Figure 4.3 the key parts of this infrastructure are:

• IMS/GLC XML Components - the application and common services components that are combined to create the e-learning system required. It is assumed that these components exchange information in the form of XML documents;
• XML-based Context - the XML documents are transformed to XML messages which are then mapped onto a common XML messaging infrastructure that is designed to support the required end-to-end services, e.g., reliable data transfer, datagram, publish and subscribe, etc. The preferred context mapping language is the Web Services Description Language (WSDL);
• XML-based Envelope - the common XML messaging system can be supported using several types of XML envelope encapsulation, e.g., SOAP/SOAP message attachments (used to support file attachments such as images, etc.), eb-XML, etc. WSDL supports SOAP, 'HTTP-Get' and 'HTTP-Post' transport mechanisms;
• Generic transport - the envelope is then transported across the network using an appropriate end-to-end file transfer protocol, e.g., Simple Mail Transfer Protocol (SMTP), File Transfer Protocol (FTP), Hypertext Transfer Protocol (HTTP), etc.;
• Communications network - this is the actual data network that is used to physically transport the data from one system to another. This will almost certainly be based upon the ubiquitous Internet Transmission Control Protocol/Internet Protocol (TCP/IP) combination providing seamless interworking between wire-line and wireless networks.

4.2 Application Services Layer

4.2.1 Conventions for Definitions of End Points

The end-points for the communicating services are defined as the 'Initiator' and 'Respondent'1. The 'Initiator' is the system that starts the interaction, resulting in the transmission of a message, and the 'respondent' is the system that must process the message and may or may not return some information, i.e., it responds to the initiating interaction. The applications services are represented by Service Access Point, i.e., the abstract API. Successful communication requires the 'Respondent' to be able to identify what is being requested and to collate a sequence of instructions over a prolonged period of time, i.e., an asynchronous stream of interactions. Therefore the binding must support the following end-point identification information:

• System identification - the unique system identifier. This identifier may be used in one of several parts of the physical addressing system;
• Service identification - the service entities that are supporting the business process, e.g., the 'Person Management Service';
• Transaction identification - the service transaction required to support the business process, e.g., 'createGroup' for creating a 'Group' object;
• Operation identification - the operation of abstract-API call that is used to trigger the transaction(s) message exchange, e.g., 'createPerson' for creating a 'Person' object. Several transactions may be supported by a single 'operation', e.g., 'deletePersons' make contain a set of 'deletePerson' transactions;
• Object identification - the object identifier that is being manipulated by the operation, e.g., the unique identifier for a 'Person'.

4.2.2 Conventions for Definitions of Behaviors

The abstract API for an application service defines its behaviors as operations in UML Class Diagrams. UML Interaction Diagrams show how the messages representing these operations interact with messages from other behaviors. These behaviors contain:

• Supplied parameters - these are values/objects that are supplied to the operation and in UML these are denoted 'in' parameters;
• Returned parameters- these are values/objects that are returned by the operation and in UML these are denoted 'out' parameters.

These values/objects are represented as XML and must have an associated XSD to act as the control validation source. Each and every operation will have a 'Status' Object that must be returned. The 'Status' object contains the status information that describes the end state of the 'Respondent' once it has attempted to process the received message. This status may contain error information if the processing has resulted in an error state/condition in the 'Respondent'. The causes for error are:

• Business rule violations - this is related to the semantic correctness of the data. Errors include such things as invalid object identifiers, attempted access to restricted information, etc.
• Invalid data content - the data supplied has syntactic errors, e.g., the XML may be invalid. There is also the case where too much information is supplied, i.e., optional data elements are supplied for a service that can only store the mandatory fields;
• Unavailable resources - these arise where the end-system does not have the resources to support the request. This may be due to conditions such as insufficient data storage, busy message buffers, etc.
• Related common service failures - these errors occur when more than one service is required to interact to provide the correct end-to-end operation. Typical examples include authorization, authentication, etc. where the supplied information carried in the SOAP header will be invalid for the required transaction;
• Infrastructure service failures - failures of the underlying communications infrastructure. All of these errors will result in a SOAP Fault being received, i.e., there may be no other form of error information in the SOAP message.

Therefore the binding SOAP messages must support the following behavioral information:

• Service identification - the service being supported by the SOAP messages;
• Operation identification - the operation being requested. This operation may consist of more than one business transaction;
• Object identification - the unique identifier for the object. This identifier must be passed as one of the 'Supplied Parameters';
• Supplied parameter XML - the information that is sent from the 'initiator' to the 'respondent'. It is contained in the body of the corresponding SOAP message;
• Returned parameter XML - the information that is sent from the 'respondent' to the 'initiator'. It is contained in the body of the corresponding SOAP message. This excludes the status object information;
• Status object XML - this object contains all of the status information carried in the response-type messages. This status object is used to contain any error reporting information. It is contained in the header of the corresponding SOAP message;
• Message choreography - each message must carry a unique identifier to enable the different parts of the end-to-end choreography to be matched. All response-type messages must identify the corresponding request-type messages. This choreography is determined by the type of messaging model (see Section 5).

4.3 Common Services Layer

At the current time there is no recommendation by IMS on how the interaction between application and common services should be choreographed. Once the appropriate specifications have matured, e.g., WS-CDL and BPEL4WS, then the corresponding recommendations will be made.

4.3.1 Error and Exception Handling

The application services exchange status information using the SOAP header status information object, defined as part of the binding by IMS/GLC. This status object is used to contain any error state information. Further error information on the SOAP communication is also supplied in the form of SOAP fault messages; this fault information is again supplied within the SOAP header. The IMS GWS Base Profile does not describe how the status information should be processed and what resulting remedial action should be taken. In the case of error status information this means that the exception handling in the end-systems is undefined. In some implementations an external common service may be invoked to support exception handling.

4.3.2 Security

System security is of increasing importance in the design of the overall system architecture. From the perspective of the IMS GWS Base Profile many aspects of security within the system's architecture are out of scope. This functionality can be supported using the appropriate common services. The IMS GWS Security Profile [GWS, 05d] defines how security architectures are supported by the SOAP messaging mechanism. The implications for common service requirements from the perspective of security are:

• Session - session management could be supplied using a common service thereby enabling functionality such as secure/private application multicasting, replicated repository management, etc.;
• Authentication & Authorization - a single sign-on authentication and authorization service is highly desirable to enable end-systems to minimize the required user-interaction across multiple applications within and between enterprises;
• Encryption & Digital Signing - a key management common service, e.g., X509, should be used to support data encryption and digital signatures.

4.3.3 Routing

SOAP is a point-to-point protocol. It is possible to implement SOAP on top of many different communications architectures, e.g., message broker, store-and-forward, etc. This may require SOAP message routing/switching and the spoofing of end-to-end connectivity. The ways in which these services interact with the underlying IMS GWS Base Profile messaging models (synchronous, asynchronous, etc.) is undefined but an implementation of an intermediate system must ensure that the behavior of the end-systems is consistent within the corresponding information model and binding specifications.

4.4 Infrastructure Layer

In Figure 4.3 the Infrastructure Layer begins with the XML-based Envelop sub-layer. For WSDL this takes the form of either SOAP or HTTP-POST or HTTP-Get. The generic transport sub-layer is assumed to be HTTP or HTTPS, on top of TCP/IP.

4.4.1 Quality of Service

The available Quality of service is that sustained by the TCP.

4.4.1.1 Best Effort

Most forms of TCP provide a 'best effort' service, i.e., there is no guaranteed minimum data rate or maximum end-to-end delay. Therefore, the quality of service perceived by the end-system is determined by: the other load on the network infrastructure (this will depend upon the time of day); the bandwidth of the network links and the error conditions on those links; the number and capabilities of the switches and the routers traversed; and to a lesser extent the physical propagation distance between the end-points.

4.4.1.2 Session Support

There is no session support within TCP

4.4.1.3 Duplicate Elimination

The byte streaming operation of TCP ensures that data duplication does not occur across the physical network infrastructure between the linked TCP end-points. However, if the high level protocols duplicate information then TCP will not detect this duplication. At present the IMS GWS Base Profile does not provide reliable SOAP messaging but does provide the mechanisms by which an implementation can create such a capability, e.g., unique message numbering - see Section 6.

4.4.1.4 Guaranteed Delivery

Once the TCP process accepts a data transfer request it guarantees data transfer or issues a data transfer failure status. Data errors do not occur because the streaming protocol retransmits data that is corrupted. However, if invalid or corrupted data is submitted to the TCP process then that information is guaranteed delivered reliably to the destination!

4.4.2 Message Packaging

4.4.2.1 Single XML Payload

The XML payload is carried in the SOAP body. The validity of this payload is determined by the associated XML control document (XSD).

4.4.2.2 Multiple Payloads

The IMS GWS Base Profile requires that only a single XML payload be supported in the SOAP body. Therefore, multiple XML payloads require the usage of an XML container XSD. The container is defined such that it supports one or more of the core data XML structures.

4.4.3 Generic Transport Layer

The SOAP messaging mechanism supports several transport protocols - in terms of the Internet Protocol Suite these transport protocols are formally named Application Protocols. All of these protocols operate using TCP/IP.

4.4.3.1 HTTP/HTTPS Conventions

These are the protocols recommended in the IMS GWS Base Profile for the exchange of the SOAP messages.

4.4.3.2 SMTP Conventions

This protocol is not supported as part of the IMS GWS Base Profile.

4.4.3.3 FTP Conventions

This protocol is not supported as part of the IMS GWS Base Profile.

5. Implementation Profiles

5.1 Messaging Models

5.1.1 Synchronous Request/Response Messaging Choreography

The message choreography for the synchronous message binding is shown in Figure 5.1. This diagram shows how the 'Service Requester' exchanges information with the 'Service Provider' using the corresponding communications handlers "Service Request Comms Hndlr' and 'Service Provider Comms Hndlr' respectively.

The message choreography for error-free operation is:

1. The 'Service Requester' triggers the request. This is a synchronous request and as such the 'Service Requester' is blocked until the 'Service Provider' has replied to the request;
2. The 'Service Requester Comms Hndlr' constructs and transmits the request message (for the Base Profile this takes the form of a SOAP message). The 'Service Requester Comms Hndlr' waits until the corresponding response message has been received (good system design requires that an appropriate fault recovery mechanism is implemented to avoid the system becoming dead-locked - this is outside the scope of the Base Profile);
3. When the 'Service Provider Comms Hndlr' receives the request it is processed and the encapsulated request is passed to the 'Service Provider';
4. The 'Service Provider' processes the request and constructs the appropriate response. Once this response has been accepted by the 'Service Provider Comms Hndlr' the 'Service Provider' is free to process other activities;
5. The Service Provider Comms Hndlr' constructs and transmits the appropriate response message (for the Base Profile this takes the form of a SOAP message);
6. Eventually, the 'Service Requester Comms Hndlr' will receive the response message. This results in the corresponding response information being returned to the 'Service Requester'. This unblocks the 'Service Requester', i.e., it is now free to issues further requests.

Error recovery is beyond the scope of this Base Profile definition. It is the responsibility of the implementation of this choreography to ensure the correct synchronous exchange of information. The actual WSDL/SOAP binding realization [GWS, 05d] makes available several features that can be used provide error recovery.

5.1.2 Asynchronous Messaging Choreography

At the current time IMS has not authorized the publication of the Asynchronous Communications messaging choreography for Final Release. This is because there are no validated implementations of this technique and there is work underway in W3C that could result in that IMS approach becoming proprietary. This work remains published as Public Draft material [GWS, 05f].

5.1.3 Polled Messaging Choreography

At the current time IMS has not authorized the publication of the Polled Communications messaging choreography for Final Release. This is because there are no validated implementations of this technique and there is work underway in W3C that could result in that IMS approach becoming proprietary. This work remains published as Public Draft material [GWS, 05f].

5.1.4 Publish and Subscribe

To be studied in a later version of this document.

5.2 Organizational Profiles

There are numerous issues to consider regarding of how web services are used and invoked based upon whether they requestor and provider cross either organizational bounds or "trust" bounds. The reader is encouraged to review both "intra" and "inter" organizational communication issues, since issues described in one may have some relevancy in the other.

5.2.1 Intra-organizational Communications

The issues for consideration are:

• Will the learner need a "Single Sign On" Experience?
• Can it be assumed that all systems "trust" each other within the Organization, e.g., can the organization truly be modelled as a single "Unit of Trust"?
• Is there a central system or "service" that can aggregate and serve as the central point for "Federated Identity":
  • User identity management and authentication
  • User Attributes
  • User Entitlements (authorizations).

5.2.2 Inter-organizational Communications

The issues for consideration are:

• Are all providers of services pre-established, or are providers established dynamically through some lookup or registry?
  • What considerations exist for any transaction needs across the systems and/or organizations as part of "two-phase" commit?
  • Is there a need for a third party "certificates" to validate the identities of the service provider and requestor?
• Does one organization become the "system of record" for identity management? If so, does it:
  • Handle authentication, and communicate current status of user's authentication?
  • Handle "log out", and communication of that activity to the other organizations?
  • Have all needed entitlements information on the user?
  • Have all needed user attributes and entitlement information?
  • What user attributes can be shared?
• What are the parameters for a Service Level Agreement (SLA)?
  • Availability?
  • Accessibility?
  • Performance?
  • Reliability?
  • Security?
  • Agreed upon Roles/Requestors that can invoke the service, with what entitlements?
• Are all communications between Organizations that are enrolled in a "Circle of Trust", a.k.a. "Trust Chain;
  • Is there a need for "non-repudiation" for services requested and performed?
  • Does some of the data in the XML package need to be "blacked out" or encrypted before the request (data is sensitive and not needed as part of the service)?
  • Does the request/response need to be encrypted (SSL, TLS) to ensure confidentiality?
• Do some of the SLA and encryption constraints affect what messaging model should be used?

6. Best Practice Recommendations

6.1 Supporting Status/Error Codes and Exception Handling

When a behavior-based IMS information model is developed that is to be mapped onto SOAP messages then each operation is required to return status information. This status information provides contextual information about the completed success or otherwise of the operation. There are two types of status information that are available to the end-systems:

• Business transaction - these are the status reports that reflect the business logic of the transactions being exchanged by the end-systems. This status information will be contained within the message header under a specially defined data structure. The status information contained herein is also used to contain any error codes, i.e., error reporting is handled as a subset of status information reporting;
• SOAP fault- this is the SOAP fault codes that are reported by the SOAP messaging infrastructure and which are carried in the SOAP message headers. A two-tier fault message code is available with the top-level being a non-extensible enumerated list.

The status information for the business transactions is carried in a single status information object that contains the following sub-structures:

• CodeMajor - The major code assigned to the status block. This is a fixed enumerated list. This is used in conjunction with the 'severity'. The list of codes is: Success, Processing, Failure and Unsupported.
• Severity - the severity of the status report. This is a fixed enumerated list. This is used in conjunction with the CodeMajor. The list of codes is: Status, Warning and Error.
• CodeMinor - this is a detailed report code structure that is used to identify specific causes of failure. A set of codes can be defined for each transaction - these will be defined as part of the corresponding Information Model.

The interpretation of the 'CodeMajor/Severity' matrix is shown in Table 6.1.

The IMS specifications do not describe how the status information is to be handled within an end-system, i.e., this will depend on how the abstract API is physically realized within an implementation. However, it is important that an implementation can:

• Combine the transaction status information and the SOAP fault error codes in a single integrated status reporting mechanism. Any other system failure information that is made available by an implementation should also use the same mechanism;
• Examine the status information reported after the completion of the appropriate phase of an operation and especially once the operation has been completed. This may require an explicit status information call or it may be reported as part of the API call;
• Differentiate the status information reports for each transaction within an operation. Remember that some specifications provide operations that can contain more than one transaction request and that a different status report may be given for each of those transactions.

Exception handling is the system's response to a known or unknown error condition. Exception handling is outside the scope of the IMS GWS Base Profile specification. However, an error condition should not cause the end-systems to fail in an uncontrolled manner. The requirement for every operation to return status information is to enable an implementation to terminate in a controlled fashion.

6.2 Supporting Different Communications Messaging Models

The IMS approach to supporting different modes of communication is to hide this within the binding, i.e., the information model is agnostic of the form of communication model used in the binding. Therefore binding is designed with the following features:

• Each message has a unique identifier. Message identifiers are not necessarily sequentially allocated, i.e., the identifier is not a message sequence number;
• All response and acknowledgement messages will supply the initiating message identifier. This will enable the implementation to correlate the cause and effect messages;
• A message identifier information will be carried in the header of the appropriate message construct, i.e., SOAP messages in this case.

The following functional capabilities are not supported in the binding and as such an implementation must supply these as and when required (some of these capabilities may be supported as and when the appropriate web service specifications have been developed and ratified):

• Error detection and correction - all messages are assumed to be correct, i.e., there are no bit errors;
• Message loss and duplication avoidance - it is assumed that no messages are lost or duplicated by the communications infrastructure.

SOAP is either a single message or two-message communication mechanism, i.e., it does not enable a complex choreography for more than two messages. Therefore, asynchronous and polled communication message models require sophisticated usage of WSDL and its SOAP messaging definitions. These require multiple sets of WSDL file definitions that an implementation has to combine to create the full message choreography. This approach is fully explained in the IMS GWS WSDL Binding Guidelines [GWS, 05d].

6.2.1 Synchronous Messaging Status Codes

A single status code is returned in the response message for each transaction.

6.2.2 Asynchronous Messaging Status Codes

At the current time IMS has not authorized the publication of the Asynchronous Communications messaging choreography for Final Release. This is because there are no validated implementations of this technique and there is work underway in W3C that could result in that IMS approach becoming proprietary. This work remains published as Public Draft material [GWS, 05f].

6.2.3 Polled Messaging Status Codes

At the current time IMS has not authorized the publication of the Polled Communications messaging choreography for Final Release. This is because there are no validated implementations of this technique and there is work underway in W3C that could result in that IMS approach becoming proprietary. This work remains published as Public Draft material [GWS, 05f].

6.3 Versioning

The following notes on Versioning are based on the W3C's notes on Versioning XML Languages as can be found from: http://www.w3.org/2001/tag/doc/versioning-20031003. In broad terms, the approaches to versioning are:

• None - no distinction is made between versions of the language. Applications are either expected not to care, or they are expected to cope with any version they encounter;
• Compatible - designers are expected to limit changes to those that are either backwards or forwards compatible, or both i.e.
  • Backwards compatibility: Applications are expected to behave properly if they receive an instance document of the "older" version of a language. Backwards compatible changes allow applications to behave properly if they receive an "older" version of the language
  • Forwards compatibility: Applications are expected to behave properly if they receive an instance document of the "newer" version of a language. Forwards compatible changes allow existing applications to behave properly if they receive a "newer" version of the language.
• Flavors - applications are expected to behave properly if they receive one of a set of flavors of the document type;
• Big bang - applications are expected to abort if they see an unexpected version.

There is no single approach that is always correct. Different application domains will choose different approaches. Just as there are a number of approaches, there are a number of strategies for implementing an approach. The Internet - including MIME, markup languages, and XML languages have successfully used various strategies, either singly or in combination such as XML Namespaces and Schema. For any given approach, some strategies may be more appropriate than others. Among the strategies we find:

• Must Understand - receivers must understand all of the elements and attributes received and are expected to abort processing if they do not. SOAP processors must understand headers that are explicitly identified to be mandatory;
• Must Ignore - receivers must ignore elements or attributes that they do not understand. Sometimes the must understand and must ignore approaches can be combined for more selective use. SOAP processors must ignore headers they do not recognize unless the header explicitly identifies itself as one that must be understood. There are 2 variations of the 'Must Ignore' strategy:
  • Must Ignore All: This variation on must ignore requires the receiver to ignore an element or attribute it does not understand and, in the case of elements, all of the descendents of that element. Most data applications, such as Web services that use SOAP header blocks or WSDL extensions, adopt this approach to dealing with unexpected markup
  • Must Ignore Container: This variation on 'Must Ignore' requires the receiver to ignore an element or attribute that it does not understand, but in the case of elements, to process the children of that element. The Must Ignore Container practice was described in HTML 2.0;
• Explicit Fallback - a language can provide mechanisms for explicit fallback if the extension is not supported. MIME provides multipart/alternative for equivalent, and hence fallback, representations of content. HTML 4.0 uses this approach in the NOFRAMES element. In XML, the XML Inclusions specification Xinclude provides a fallback element to handle the case where the putatively included resource cannot be retrieved.
• Explicit Testing - a language can provide a mechanism for explicit testing. The XSLT Specification provides a conditional logic element and a function to test for the existence of extension functions. This allows designers of style sheets to deal with different receiver capabilities in an explicit fashion.

Languages can choose a mixture of approaches. For example, XSLT provides both an explicit fallback mechanism for some conditions and explicit testing for others. The SOAP specification, another example, specifies 'Must Ignore' as the default strategy and the ability to dynamically mark components as being in the 'Must Understand' strategy.

6.3.1 IMS Versioning Solution

The IMS solution is to add a separate version structure that is contained in the SOAP header. This structure is optional and when it is absent the default version is GWS Base Profile v1.0.

6.4 Using the Messaging Questionnaire Template

The messaging questionnaire, supplied in Appendix B, looks at three messaging mechanisms:

• Request data update;
• Read request/response;
• Data monitoring.

The following sub-sections identify the set of questions that should be answered for each of the messaging mechanism listed above. The numbers shown in the square brackets ('[]') denote the equivalent question number in the Messaging Questionnaire. The set of questions identify two systems 'X' (the Source) and 'Y' (the Target) that are communicating using the corresponding messaging mechanism.

6.4.1 Use Case #1: Request Data Update / ACK (or NAK)

The key questions for systems that are based upon:

• 'X' sends Create / Update / Delete to 'Y';
• 'Y' sends back Response to 'X'.

1.   [3] Accept only or Reject possible?

Can the 'Y' system reject the 'X' change? What if the version number is wrong or (worse) if the Request message doesn't pass the "well formed" or "valid" checks? What if the change is illegal, e.g., no such object?

Should all errors (system level, XML level, business level) be reported in the same way?

2.   [4] Synchronous or Asynchronous Response?

Is the 'Y' response expected immediately? If not, how is the response correlated to the request?

Does the Response imply that the 'Y' database update has actually been made? If so, can 'X' always leave its Request pending until this occurs (even if 'Y' is in another organization)?

Alternatively, can the Change Request be acknowledged immediately, and the actual Response be returned later (asynchronously), after the 'Y' database update is actually done or if an error occurred while processing the Request Message, not done?

Is there a maximum time a given 'X' system is willing to wait for the Response and does the 'Y' system need to know this time? If so, and if not simply pre-wired, the infrastructure may have to support "session state".

Is there ever a need for the 'X' system to cancel the Request before it is executed?

3.   [5,6] What level of Quality of Service (QoS) is required?

If the Response message is lost, and 'X' times out and resends, does 'Y' need to detect delivery of a duplicate message, i.e., is it an error to issue this Update message twice? Should the infrastructure prevent duplicate message delivery?

Must the recipient (or the network) be active for the Request to successfully be made? Should the infrastructure support guaranteed message delivery (making life easier for the requesting 'X')?

4.   [9,10,11] How is Partner Location determined?

Is the location of 'Y' "pre-wired" in 'X'? If more than one 'Y' is connected to 'X', how does 'X' know which 'Y' to inform of the change?

Is there a "globally unique" Record ID? If so, is it global to 'Y' (and all its connected 'X' partners) or global across all possible -compliant 'Y'? If the former, then a single 'X' cannot be connected to multiple 'Y'.

5.   [12, 13] Is a Data Monitoring capability ever necessary?

Does 'X' ever need to synchronize with data maintained in 'Y'? In other words, are there ever any changes to 'Y' data not caused by 'X' that 'X' needs to be informed of? If so, than either 'X' must itself be a web service, and be known to 'Y', which will use the 'X' API to post such changes. Alternatively, 'X' must "subscribe" to posted changes from Y.

Is it required to allow a 3rd party (e.g., an "Event Logger") to track all such changes (from either 'X' or 'Y')? If so, an infrastructure supporting some variant of the publish/subscribe model offers definite advantages.

6.   [14,15,16,17] What level of Security is required?

Are there any security requirements for communication between 'X' and 'Y'? Which direction? What type? A. Encryption of data?
B. Authentication of 'X' as source of Change Request to 'Y'?
C. Authorization of 'X' to issue the Change Request for this data?

How much of such security requirements should be supplied by the infrastructure?

7.   [18, 19, 20] Is "One-shot" communication exchange enough or is Session support needed?

Do 'X' and 'Y' have longer running conversations? Is there a session established between them in which state is maintained? If so, what are some of the state variables for such a session? A. Security "Cookie"?
B. Version number of each participant?
C. Optional services supported/not supported.

How much of the above information that both 'X' and 'Y' need to agree on, is discovered dynamically? How much of this information is pre-configured by the System Administrator?

8.   [21, 22] How are Optional Elements resolved?

Are there any optional elements in the schema that define this exchange?

If so, how do the two parties ensure that there is no case in which one side does not support such an optional element, while the other side depends upon it?

9.   [23] Can there be a range of different Transports used?

What is the range of different transports such 'X' to 'Y' communication could logically be expected to occur across? A. HTTP;
B. HTTPS;
C. IIOP (Corba) or DCOM;
D. MOM (MQ/Series, MSMQ, JMQ, etc.);
E. SMTP (note - supports multiple binary payloads);
F. Other (FTP, etc.).

10.   [28, 29] Is support for Batch Updates necessary?

Can the 'X' Update reference data in more than one object? If so, does the Update message schema support aggregates?

11.   [30, 31, 32] Are there any Transaction considerations in this database update?

Can the 'X' Change Request ever be considered as part of a larger (perhaps multi-party) transaction? For example, can it propagate to a 'Z' system, which might have to complete its data updates before the 'Y' system could return an acceptance Response?

If so, how are the boundaries of the transaction identified in the documentation? Need any transaction identifier be conveyed on the wire?

12.   [33] What does the Version Number mean?

Does the version number of the messages involved in this exchange refer to: A. The particular version of the release supported by both sides?
B. The version of the data object being updated?
C. The version of the schema for the Change Request or Response message?

13.   [34, 35] What are the Message Packaging requirements?

Can either the Request or Response consist of multiple independent payloads? Can the format of any of these payloads be other than XML?

14.   [36, 37] Legality

Are there any requirements for non-refutability of either the Update Request or the subsequent Response? Are there any requirements for guaranteed non-alterability of message data?

15.   [38, 39, 40, 41, 42] Operation Specifics

Are partial modifications to the data record possible? If so, must the original values of the elements being changed be included in the Change Request as well? If not, how are the "positions" of these elements within the total Object Schema indicated?

When the Change Request from 'X' indicates "Create", is the GUID for that object included in the message? Note that this could cause problems if 'Y' owns GUID creation for its objects. If it is NOT so included, is the value of the GUID that 'Y' assigns, returned in the Response message to 'X'?

6.4.2 Use Case #2: Read Request / Response

The key questions for system that are based upon:

• 'X' sends Read Request to 'Y';
• 'Y' sends back Response to 'X'.

1.   [4] Synchronous or Asynchronous Response?

Is the 'Y' response expected immediately? If not, how is the response correlated to the request?

Is there a maximum time a given 'x' system is willing to wait for the Response and does the 'Y' system need to know this time? If so, and if not simply pre-wired, the infrastructure may have to support "session state".

2.   [5, 6] What level of Quality of Service (QoS) is required?

Must the recipient (or the network) be active for the Request to successfully be made? Should the infrastructure support guaranteed message delivery (making life easier for the requesting 'X')?

3.   [9, 10, 11] What is known about the Partner?

Is the location of 'Y' "pre-wired" in 'X'?

Is there a "globally unique" Record ID? If so, is it global to a single 'Y' or global across all possible -compliant 'Y'? If the former, then a single 'X' cannot be connected to multiple 'Y'.

If the requestor is a device (ex: for a Price Lookup, the client can be an in-store server, a POS terminal or a scanner) then the Response could be different (full information to single line display).

If the response does indeed depend upon knowing the type of requestor, than how does the responder get this information?

4.   [12, 13] Is a Data Monitoring capability ever necessary?

Does X ever need to synchronize with data maintained in Y? In other words, are there ever any changes to Y data that X needs to be informed of? If so, than either X must itself be a web service, and be known to Y, which will use the X API to post such changes. Alternatively, X must "subscribe" to posted changes from Y.

Is it required to allow a 3rd party (ex: an "Event Logger") to track all such Y changes? If so, an infrastructure supporting some variant of the publish/subscribe model offers definite advantages.

5.   [14, 15, 16, 17] What level of Security is required?

Are there any security requirements for communication between 'X' and 'Y'? Which direction? What type? A. Encryption of data?
B. Authentication of 'X' as source of Change Request to 'Y'?
C. Authorization of 'X' to issue the Change Request for this data?

How much of such security requirements should be supplied by the infrastructure

6.   [18, 19, 20] Is "One-shot" communication exchange enough or is Session support needed?

Do the X and Y systems have longer running conversations? Is there a session established between them in which state is maintained? What are some of the state variables for such a session? A. Security "Cookie"?
B. Version number of each participant?
C. Optional services supported/not supported.

How much of the above information that both 'X' and 'Y' need to agree on, is discovered dynamically? How much of this information is pre-configured by the System Administrator?

7.   [21, 22] How are Optional Elements resolved?

Are there any optional elements in the XML schema that define this exchange?

If so, how do the two parties ensure that there is no case in which one side does not support such an optional element, while the other side depends upon it?

8.   [23] Can there be a range of different Transports used?

What is the range of different transports such 'X' to 'Y' communication could logically be expected to occur across? A. HTTP;
B. HTTPS;
C. IIOP (CORBA) or DCOM;
D. MOM (MQ/Series, MSMQ, JMQ, etc.);
E. SMTP (note - supports multiple binary payloads);
F. Other (FTP, etc.).

9.   [24, 25] Is support for multi-object retrieval necessary?

Can the 'X' Request ask for information on more than one object? How flexible is the query (i.e., list of specific Record IDs, all the way up to full SQL capability on object collection)?

If multiple objects result, does the Response message schema support aggregation?

10.   [33] What does the Version Number mean?

Does the version number of the messages involved in this exchange refer to: A. The particular version of the release supported by both sides?
B. The version of the data object being requested?
C. The version of the schema for the Request or Response message?

11.   [34, 35] What are the Message Packaging requirements?

Can either the Request or Response consist of multiple independent payloads? Can the format of any of these payloads be other than XML?

12.   [36, 37] Legality

Are there any requirements for non-refutability of either the Request or the subsequent Response? Are there any requirements for guaranteed non-alterability of message data?

13.   [30, 31, 32] Are there any Transaction considerations in this data request?

Can the 'X' Read Request ever be considered as part of a larger (perhaps multi-party) transaction? For example, can it propagate to system 'Z', which might have to supply some of its data before the 'Y' system could return an acceptance Response?

If so, how are the boundaries of the transaction identified in the documentation? Need any transaction identifier be conveyed on the wire?

6.4.3 Use Case #3: Data Monitoring

The key questions for system that are based upon:

• 'X' publishes an Event (usually indicating an update to its object(s);
• 'Y' and 'Z' receive the Event via a 3rd party Message Broker (MOM).

1.   [1, 2] How did 'Y' and 'Z' get selected to receive the event message from 'X'?

Did 'Y' and 'Z' dynamically pre-subscribe to receive 'X's Event, or did they pre-subscribe to receive messages on a specific "topic" (typically changes to objects of a specific type) which 'X' was identified as "owning"?

If the latter, did 'X' have to pre-register to post events on this topic?

2.   [6, 7, 8] What level of Quality of Service (QoS) is required?

Must each recipient (and the network) be active for the Event to successfully be generated?

Should the infrastructure support guaranteed message delivery (implying that a newly reactivated application receives all the events previously queued for it).

Must events be delivered in the order in which they were posted?

Does the recipient have to be notified when all events are successfully delivered?

3.   [43, 44, 45, 46, 47] What level of Security is required?

Are there any security requirements for communication between the Message Broker and the 'X', 'Y' and 'Z' systems? Does the Message Broker need to enforce: A. Encryption of data?
B. Authentication of 'X' as source of Change Request to 'Y'?
C. Authorization of 'X' to issue the Change Request for this data?

Can the levels of security for event propagation be set by the issuing application 'X' or must all security levels be pre-configured by the administrator of the Message Broker?

4.   [21, 22] How are Optional Elements resolved?

Are there any optional elements in the XML schema that define this Event?

If so, how do all the parties ensure that there is no case in which one side does not support such an optional element, while the other side depends upon it?

5.   [26, 27] Is support for multi-object retrieval necessary?

Can the 'X' event report on changes to more than one object instance? If so, does the Event message schema support aggregates?

6.   [33] What does the Version Number mean?

Does the version number of the Event involved in this exchange refer to: A. The particular version of the release supported by both sides?
B. The version of the data object being reported?
C. The version of the Event message schema?

7.   [34, 35] What are the Message Packaging requirements?

Can the Event message consist of multiple independent payloads? Can the format of any of these payloads be other than XML?

8.   [36, 37] Legality

Are there any requirements for non-refutability of the Event? Are there any requirements for guaranteed non-alterability of message data?

9.   [38, 39, 40] Operation Specifics

Are partial modifications to the object referred to in the Update Event possible? If so, do the original values of the elements being changed need to be included in the Update Event as well? If not, how are the "positions" of these elements within the total Object Schema indicated?

10.   [30, 31] Are there any Transaction considerations in this notification of database update?

Can the Event ever be considered as part of a larger (perhaps multi-party) transaction? For example, can it generate other events that must be "tied" to the original?

If so, how are the boundaries of the transaction identified in the documentation? Need any transaction identifier be conveyed on the wire?

7. Extending the Base Profile

7.1 Proprietary Extensions

There are three methods by which the functional capability of the base profile can be extended:

1. Addition of new SOAP messages - the addition of new business transactions and the usage of new messaging models requires the creation of new SOAP messages. The addition of new business transactions should result in a change to the specification itself. Therefore, the application of the transformation rules will result in the automatic generation of the new SOAP messages. Support for a new messaging model, will require the creation and application of a new set of transformation rules;
2. Extensions to the SOAP header - the current IMS GWS Base Profile makes use of the SOAP header to contain the application-to-application transaction status information. Other specifications, e.g., WS-Security, also use the SOAP header to contain the appropriate information. It is recommended that proprietary extensions to the SOAP header maintain the current usage patterns;
3. Extensions in the data contained within the SOAP body - the SOAP body contains the XML instance that is used to represent the parameters defined for the transaction operations in the specification. There may be a need to add new parameters or to extend the XML structures of the current parameters. Extending the XML data structures must use the IMS extension mechanism otherwise the SOAP message receiver processor will not be able to marshal the messages, i.e., the receiver must know 'a priori' the XML structure of the received messages. New parameters may require a new XSD or at the very least will require a change to message structure XSD.

7.2 Further Work in V2.0

The areas for further work in the development of the IMS GWS Base Profile are:

1. Inclusion of conformance statements - the WS-I describes how conformance statements can be embedded in the WSDL description. These statements can be used to determine if the SOAP messages conform to the profile. WS-Policy is an alternative mechanism that is under development by W3C;
2. Adoption of SOAP 1.2 - the current profile is based upon SOAP 1.1 but SOAP 1.2 is now available. We will not consider changing the IMS GWS Base Profile until reliable tools are available to support using SOAP 1.2;
3. Adoption of WSDL 2.0 - W3C is developing WSDL 2.0 (this was originally referred to as version 1.2). Changing the intermediate representation should not alter the actual SOAP messages to be generated but will enable improved expression to allow more complex bindings to be described in the WSDL file. We will not consider changing the IMS GWS Base Profile until reliable tools are available to support using WSDL 2.0;
4. Adoption of UDDI 2.0 - UDDI 2.0 is not widely adopted. We will not consider adding the usage of UDDI to the IMS GWS Base Profile until there is sufficient practical experience of using UDDI;
5. Reliable messaging - reliable application-to-application communications requires the usage of the corresponding reliable SOAP messaging protocol. TCP does not operate at the right level in the communications stack to provide coverage of the SOAP messages;
6. Message choreography - the more complex messaging models, i.e., 'asynchronous', 'polled' and 'publish-and-subscribe' need to be supported (IMS proprietary implementations for asynchronous and polled are available in the Public Draft version of this document [GWS, 05a]). The usage of WSDL 2.0 may resolve this issue;
7. Service choreography - the interaction between the application and common services needs to be described using the appropriate service choreography. This will enable us to definitively specify how services may interact. The usage of BPEL4WS will be investigated for this choreography.

8. Conformance to the Base Profile

8.1 International Conformance Programme

The IMS International Conformance Programme has developed the Application Profile Guidelines [APG, 05a], [APG, 05b]. These guidelines describe how a specification can be tailored for a particular domain of usage by creating the appropriate Application Profile. A collection of Application Profiles is produced to create the corresponding Domain Profile (in many cases a domain of usage requires several related Application Profiles to be produced).

8.2 Base Profile Conformance

As per the Conformance Specification, the test specification is to be produced from two perspectives:

• 'Service Requester' - the driver and consumer of the service;
• 'Service Provider' - the provider of the service.

8.2.1 Service Requester Perspective

For behavior that is defined in the UML-interface diagram of the specification the following test set must be defined to create the corresponding SOAP/HTTP messages:

1. Unsupported service report - the service request is rejected because it is not supported by the service provider (this is also true for requests requiring service extensions);
2. Successful service provision with only mandatory elements - the service is correctly supported when the supplied data contains only the mandatory data elements;
3. Successful service provision with mandatory and optional elements - the service is correctly supported when the supplied data contains any combination of optional data with all of the mandatory data (this includes all of the optional data, any single piece of optional data and combinations of multiple optional data);
4. Successful service provision with mandatory and optional elements - the service is correctly supported when the supplied data contains any combination of optional data with all of the mandatory data (this includes all of the optional data, any single piece of optional data and combinations of multiple optional data);
5. Correct generation of error status codes - the requester must correctly handle the appropriate error codes when invalid data was supplied, when the system was in a state inconsistent with the request and when there was a failure of some component in the system, e.g., full database in the service;
6. Data overload handling - observation of how the requester handles situations in which it is given more data than it can support, e.g., it only supports the mandatory elements but it is also supplied with optional elements;
7. Support for extensions - to ensure that the requester correctly responds to the different status codes that are returned due to its original usage of extensions.

8.2.2 Service Provider Perspective

For behavior that is defined in the UML-interface diagram of the specification the following test set must be defined to create the corresponding SOAP/HTTP messages:

1. Unsupported service report - the service request is rejected because it is not supported by the service provider (this is also true for requests requiring service extensions);
2. Successful service provision with only mandatory elements - the service is correctly supported when the supplied data contains only the mandatory data elements;
3. Successful service provision with mandatory and optional elements - the service is correctly supported when the supplied data contains any combination of optional data with all of the mandatory data (this includes all of the optional data, any single piece of optional data and combinations of multiple optional data);
4. Successful sequential service provision - the service is correctly supported when the same behavior is invoked several times. This is to ensure that the same multiple behaviors result in the appropriate incremental record changes;
5. Correct generation of error status codes - the service must correctly report the appropriate the error codes when invalid data is supplied, when the system is in a state inconsistent with the request and when there is a failure of some component in the system, e.g., full database in the service;
6. Support for extensions:-
7. Confirmation that the service provider correctly rejects unknown service extensions
8. Confirmation that the service can either report that data extensions are not supported but the service operation is otherwise completed
9. Confirmation that the full extension facility is supported.

8.3 Conformance for Extension Profiles of the Base Profile

Conformance to profiles that have extended the base profile is defined in the associated profile description document.

Appendix A - Glossary of Terms

Throughout the General Web Services documents a variety of key terms, concepts and descriptions have been introduced. These terms, concepts and descriptions and defined below but where appropriate the normative definition from the IAF Glossary is referenced [AbsGloss, 03].

Appendix B - Messaging Questionnaire Template

The messaging questionnaire work aid is shown in Table B12. Whenever possible, this questionnaire should be completed for each use-case. This set of responses is then analyzed to determine the set of bindings available to support the set of required features.

About This Document

List of Contributors

The following individuals contributed to the development of this document:

Revision History

Index

A
a-API 1
Abstract Framework 1, 2, 3, 4, 5, 6
API 1, 2, 3, 4, 5, 6
Application Profile 1, 2, 3, 4
Application Services Layer 1
Asynchronous 1, 2, 3, 4, 5
Authentication 1, 2, 3, 4, 5, 6
Authorization 1, 2, 3, 4, 5

B
Base Profile 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19
Batch Updates 1
Best Practice 1, 2, 3, 4
Business Processing Execution Language 1, 2, 3, 4, 5, 6

C
Choreography 1, 2, 3, 4, 5
Common Services Layer 1
Conformance 1, 2, 3, 4, 5, 6, 7, 8
Context 1, 2, 3, 4
CRUD 1

D
DCOM 1, 2, 3
DIME 1, 2

E
ebXML 1, 2, 3, 4
Encryption 1, 2, 3, 4, 5, 6
Error & Exception Handling 1

G
General Web Services Base Profile 1, 2, 3

I
IMS Auto-generation Binding Tool 1
IMS General Web Services 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19
     Addressing Profile 1, 2
     Attachments Profile 1, 2, 3
     Base Profile 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
     Security Profile 1, 2, 3, 4, 5
Infrastructure Layer 1, 2, 3
International Conformance Programme 1
Internet Protocol 1, 2, 3
IP Security 1

M
Message Packaging 1, 2, 3, 4
Message Queuing
     JMQ 1, 2
     MQ/Series 1, 2
     MSMQ 1, 2
Messaging
     Asynchronous 1, 2, 3, 4, 5
     Polled 1, 2, 3
     Publish & Subscribe 1
     Synchronous 1, 2, 3, 4, 5, 6
Messaging Models 1, 2
Messaging Questionnaire 1, 2, 3
MOM 1, 2, 3

P
Protocols
     FTP 1, 2, 3, 4, 5
     HTTP 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20
     HTTPS 1, 2, 3, 4, 5, 6
     IIOP 1, 2, 3
     IP 1, 2, 3, 4
     IPSEC 1
     SMTP 1, 2, 3, 4, 5
     SOAP 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37
     SSL 1, 2, 3
     TCP 1, 2, 3, 4, 5
     TLS 1, 2, 3
Publish & Subscribe 1

Q
Quality of Service 1, 2, 3, 4

R
Remote Procedure Call 1, 2, 3
Routing 1, 2

S
Secure Socket Layer 1
Security 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
SOAP 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37
SOAP message attachments
     DIME 1, 2
     SOAPwA 1, 2, 3
     WS-Attachments 1, 2
SOAP Versions
     1.1 1, 2, 3, 4, 5
     1.2 1
SOAP with Attachments 1, 2, 3
Synchronous 1, 2, 3, 4, 5, 6

T
TCP 1, 2, 3, 4, 5
TLS 1, 2, 3
Transaction 1, 2, 3, 4
Transmission Control Protocol 1, 2, 3
Transport Layer Security 1, 2, 3

U
UDDI 1, 2, 3, 4, 5, 6, 7, 8, 9
Unified Modelling Language 1, 2, 3, 4, 5
     UML 1, 2, 3, 4, 5

V
Versioning 1, 2
Virtual Private Network 1

W
W3C 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
Web Service Architecture 1, 2, 3
Web Services 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16
     SOAP 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37
     SOAPwA 1, 2, 3
     WS-Attachments 1, 2
     WSDL 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29
     WS-Security 1, 2, 3, 4, 5
Web Services Interoperability Organization 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
WSA 1, 2, 3, 4
WS-Attachments 1, 2
WSDL 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29
WSDL Versions
     1.1 1, 2, 3, 4
     2.0 1
WS-I
     Basic Profile 1, 2, 3, 4, 5, 6, 7, 8
     Simple SOAP Binding Profile 1, 2, 3, 4, 5
WS-I Basic Profile 1, 2, 3, 4, 5, 6, 7, 8
WS-I Simple SOAP Binding Profile 1, 2, 3, 4, 5
WS-Security 1, 2, 3, 4, 5

X
XMI 1, 2, 3
XML 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32
XML Metadata Interface 1, 2
XML Schema 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
XML Schema Definition 1, 2, 3, 4
XML Stylesheet Language Transformations 1
XSD 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16
XSLT 1, 2, 3