IMS Logo

IMS General Web Services Primer

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 Primer
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.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

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.


Overview

The IMS General Web Services specification promotes interoperability across web service based specification implementations on different software and vendor platforms. The principal component of the IMS General Web Services specification is the Base Profile that identifies a core set of specifications that are to be used to produce a service-oriented architecture using Web Services. It is not a goal of the Base Profile to create a plug-and-play architecture for web services or to guarantee complete interoperability. The IMS General Web Services Base Profile addresses interoperability in the application layer, in particular, the description of behaviors exposed via Web Services. The Base Profile can be extended using one or more of the IMS General Web Services extension profiles. These extension profiles are the Addressing Profile, Security Profile and the Attachments Profile.

From a technical perspective, the IMS General Web Services specification is produced to ensure that all of the services defined by IMS Global Learning Consortium (IMS/GLC) use a common, and thus compatible, message exchange infrastructure. A consequence of this is that the creation of a service specification is focused on the business process and the service methods required which realise that process. This is because the realisation of the service as a Web Service has been reduced to a computer-automated technique. Once a service has been defined using the IMS/GLC specification methodology then the corresponding IMS Binding Auto-generation Toolkit is used to create the corresponding web services binding.

Table of Contents


Overview

1. Introduction
1.1 Context for the General Web Services Specification
1.2 The General Web Services Specification
1.3 Structure of the Primer
1.4 References
1.5 List of Acronyms

2. General Web Services Profile
2.1 GWS Base Profile
2.2 GWS Addressing Profile
2.3 GWS Security Profile
2.4 GWS Attachments Profile

3. Using the Profiles

4. Creating a WSDL Binding of the Profiles

About This Document
List of Contributors

Revision History

Index


1. Introduction

1.1 Context for the General Web Services Specification

The objective of the IMS General Web Services (GWS) specification 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 GWS service binding will provide a methodology and an application profile that meets the following criteria:

  • Interoperability - artefacts produced under the GWS 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 GWS activity will be designed to help other IMS specification activities efficiently and effectively evaluate web services protocols as they pertain to the functional requirements;
  • Consistency - artefacts produced under the GWS activity will be designed to facilitate the implementation of consistent approach to the implementation of web service protocols across IMS activities and specifications;
  • Flexibility - artefacts produced under the GWS activity will be flexible enough to adapt to evolving web service protocols such as 'SOAP' and to work with a variety of binding methods for web services such as Web Services Description Language (WSDL);
  • Practicality - artefacts produced under the GWS 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.

1.2 The General Web Services Specification

The IMS General Web Services specification consists of the following documentation:

  • IMS GWS Primer - the introduction and overview to the IMS GWS specification (this document);
  • IMS GWS Base Profile [Base, 05] - the underlying profile that defines the core protocols and message choreography;
  • IMS GWS Addressing Profile [Address, 05] - extension of the GWS Base Profile to enable transport independent end-to-end addressing;
  • IMS GWS Security Profile [Secure, 05] - extension of the GWS Base Profile to enable the support of different security architectures;
  • IMS GWS Attachments Profile [Attachments, 05] - extension of the GWS Base Profile to enable the exchange on non-XML information.

The bindings for the IMS GWS specification are created using the IMS Binding Auto-generation Toolkit (I-BAT). The I-BAT is used to enable a service specification whose information model is created using the IMS approach to have the corresponding WSDL binding automatically generated from that model. The I-BAT consists of:

  • I-BAT Manual [I-BAT, 05] - the documentation that explains how to use the I-BAT (this includes the installation guide, user manual, tutorial and reference manual);
  • I-BAT Tool-kit - the set of templates for the development of the model of the specification (using the Unified Modelling Language) and the corresponding XML Style-sheets (XSLs) that are used to convert the model to the WSDL binding.

Finally, reference implementation source code is supplied to simplify the adoption of the IMS GWS specification. The reference implementation materials consist of:

  • .NET reference implementation - the source code developed to implement IMS GWS within the .NET framework;
  • J2EE reference implementation - the source code to implement the IMS GWS using Java.

1.3 Structure of the Primer

The structure of the rest of this document is:

2. General Web Services Profiles The description of the set of profiles that constitute the IMS general Web Services specification;
3. Using the Profiles A description of how the profiles are used to support the development of service-oriented specifications based upon Web Services;
4. Creating a WSDL Binding of the Profiles A description of the process that must be undertaken to create a WSDL binding of a service-oriented specification;

1.4 References

[Address, 05] IMS General Web Services Addressing Profile v1.0 Final Specification, C.Schroeder, J.Simon and C.Smythe, IMS/GLC, December 2005.
[Attachments, 05] IMS General Web Services Attachments Profile v1.0 Final Specification, C.Schroeder, J.Simon and C.Smythe, IMS/GLC, December 2005.
[Base, 05] IMS General Web Services Base Profile v1.0 Final Specification, C.Schroeder, J.Simon and C.Smythe, IMS/GLC, December 2005.
[I-BAT, 05] IMS Binding Auto-generation Tool-kit Manual v1.0, C.Smythe, IMS/GLC, December 2005.
[Security, 05] IMS General Web Services Security Profile v1.0 Final Specification, C.Schroeder, J.Simon and C.Smythe, IMS/GLC, December 2005.
[WSI, 04a] Web Services Interoperability Basic Profile Version 1.1, Eds K.Ballinger, D.Ehnebuske, C.Ferris, M.Gudgin, C.K.Liu, M.Nottingham and P.Yendluri, Web Services-Interoperability Organization, August 2004.
[WSI, 04b] WS-I Simple SOAP Binding Profile Version 1.0, Ed M.Nottingham, Web Services-Interoperability Organization, August 2004.

1.5 List of Acronyms

GWS General Web Services
HTML HyperText Mark-up Language
HTTP HyperText Transfer Protocol
I-BAT IMS Binding Auto-generation Toolkit
IMS/GLC IMS Global Learning Consortium
J2EE Java 2 Enterprise Edition
MIME Multipurpose Internet Mail Extensions
MTOM Messaging Transmission Optimization Mechanism
SWA SOAP with Attachments
TCP/IP Transmission Control Protocol/Internet Protocol
UDDI Universal Description Discovery & Integration
UML Unified Modelling Language
WSDL Web Service Description Language
WS-I Web Services Interoperability Organization
XMI XML Meta-data Interchange
XML Extensible Mark-up Language
XOP XML-binary Optimization Packaging
XSD XML Schema Definition
XSL XML Style-sheets
W3C World Wide Web Consortium

2. General Web Services Profile

2.1 GWS Base Profile

The IMS GWS Base Profile [Base, 05] 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. The information exchange model for the IMS GWS is shown in Figure 2.1.

Information exchange model for the IMS GWS
Figure 2.1 Information exchange model for the IMS GWS.

The salient feature of this model is that the lower level profiles are primarily responsible for defining the 'Messaging Infrastructure'. Once an IMS/GLC service information model has been defined the binding rules are applied to create the messaging choreography. The other advantage of these binding rules is that the corresponding web service adapter for different services have many similar features thereby enabling a common web services adapter framework to be created.

Table 2.1 IMS GWS base profile.

Core Specification Description
XML Schema V1.0 All data models in IMS specifications will be defined in terms of XML Schema and will require the definition of the corresponding control documents (XSD).
HTTP V1.1 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 WSDL v1.1.

The IMS GWS Base Profile is based upon the Web Services Interoperability Organization (WS-I) Basic Profile v1.1 [WSI, 04a] and the WS-I Simple SOAP Binding Profile v1.0 [WSI, 04b]. The IMS GWS Base Profile is defined in Table 2.1. The only difference between the IMS profile and that of the WS-I Basic Profile is that the Universal Description Discovery & Integration (UDDI) specification is not included in the IMS/GLC profile due to the limited availability of UDDI-based repositories. The WS-I Basic Profile consists of a set of non-proprietary Web Services specifications, along with clarifications and amendments to those specifications that promote interoperability. The WS-I Basic Profile has been selected as the basis for the IMS GWS Base Profile because it is has wide adoption in many different business sectors.

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.

2.2 GWS Addressing Profile

The IMS GWS Addressing Profile [Address, 05] extends the IMS GWS Base Profile to allow transport-independent end-to-end addressing. The IMS GWS Addressing Profile recommends the usage of the WS-Addressing standard from W3C. The WS-Addressing standard enables a SOAP message to be extended to contain the source of the information, the final destination address, the specific endpoint at the destination and instructions for processing if delivery is not possible. Many other WS-*1 specifications rely upon the usage of WS-Addressing. The IMS GWS Addressing Profile describes how the addressing information is inserted in the SOAP header and how the 'endpoint reference' is defined. The 'endpoint reference' is used to provide an identifier that pinpoints a particular instance of a service. In most cases the 'endpoint reference' is dynamically generated from the properties defined in the associated WSDL file.

2.3 GWS Security Profile

The IMS GWS Security Profile [Security, 05] extends the IMS GWS Base Profile to allow the support of a range of secure architectures. The WS-I is developing their Basic Security Profile but this profile is too immature for immediate adoption by IMS/GLC. Therefore, the IMS GWS Security Profile contains only general recommendations and these will be revisited once the WS-I Basic Security Profile has matured. Security for web services, as with any network-oriented information technology, is vital. Web services security builds on existing security standards for confidentiality, integrity, non-repudiation, authentication and authorization at the transport, platform and application level. The key to security is analyzing the potential threats and implementing countermeasures to reduce risk to an acceptable level. Selecting the appropriate countermeasures and defining the acceptable level of risk is best done on an individual basis for each implementation. Securing the network traffic is a simple way to provide message integrity and confidentiality between points. Mechanisms for securing network traffic include Secure Socket layer, Transport Layer Security, Virtual Private Network and IP Security.

2.4 GWS Attachments Profile

The IMS GWS Attachments Profile [Attachments, 05] extends the IMS GWS Base Profile to support the exchange of non-XML information in the SOAP messages. This enables MS Word documents, images, zip files, etc. to be exchanged using SOAP messages. Non-XML information is attached to the SOAP messages using the Message Transmission Optimization Mechanism (MTOM). MTOM combines the transport efficiency of SOAP with Attachments (SWA) and the flexibility of Base64 encoding. WS-I recommends the usage of SWA however SWA is based upon an inefficient MIME encoding technique (as per email) and is incompatible with WS-Security (WS-Security will eventually form the basis of the IMS Security Profile). MTOM uses the XML-binary Optimization Packaging (XOP) mechanism for efficiently placing non-XML content into MIME packages.

3. Using the Profiles

From a technical perspective, the IMS GWS specification is produced to ensure that all of the services defined by IMS/GLC use a common, and thus compatible, message exchange infrastructure. A consequence of this is that the creation of a service specification is focused on the business process and the service methods required which realise that process. This is because the realisation of the service as a Web Service has been reduced to a computer-automated technique. Figure 3.1 is a schematic representation of the relationship between an IMS/GLC specification and the IMS GWS.

General web services specification as the common messaging mechanism for IMS services
Figure 3.1 General web services specification as the common messaging mechanism for IMS services.

In Figure 3.1 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 the 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. WSDL is the context mapping language and the IMS GWS defines how the service-description is transformed into the WSDL equivalent;
  • XML-based Envelope - the common XML messaging system can be supported using several types of XML envelope encapsulation i.e. SOAP/SOAP with message attachments, etc. The IMS GWS defines the message structure, choreography and other messaging considerations;
  • Generic transport - the envelope is then transported across the network using an appropriate end-to-end file transfer protocol using the HyperText Transfer Protocol (HTTP);
  • 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.

To use the IMS GWS profiles the specification creators must make the following decisions:

  • Which set of profiles are to be adopted i.e. is it just the Base Profile or will one or more of the extension profiles also be used (Security, Addressing and/or Attachments);
  • The nature of the service in terms of being synchronous, asynchronous, polled, publish-and-subscribe, etc. This issue does not impact the service definition but is used to decide the final form of the service binding;
  • The breakdown of the business process into its constituent services and the corresponding behaviours (this is the predominant activity for the specification creators and it is where the creative aspects of the work are undertaken).

The service(s) is created using an abstract representation that is then transformed into the corresponding Web Service binding. All of this process is supported using the IMS specification development tools developed specifically for this need.

4. Creating a WSDL Binding of the Profiles

The process for creating a WSDL binding for a service that is based upon the IMS GWS Base Profile is shown schematically in Figure 4.1. The steps in the process are:

  1. The Information Model for the service must be defined using the IMS Service Unified Modelling Language Profile [I-BAT, 05]. This profile describes how the Unified Modelling Language (UML) must be used to create a description of the specification that can be used by the IMS auto-generation tools. The specification is created without explicit identification of the type of communications model to be supported by the binding i.e. the nature of the communication model supported is defined when the binding is created;
  2. The UML description is made available as an XML Meta-data Interchange (XMI) file i.e. this is an XML instance that conforms to the XMI specification. At the present time only XMI files that have been created by the Poseidon tool, v2.5 or later, are valid. The Poseidon tool creates a '.zuml' file that must be unzipped and the XMI file within used as input to the I-BAT;

The XMI file is now used as input to the I-BAT. The XSL file 'UMLtoWSDLTransform.xsl' is applied to the XMI file, using an appropriate XSLT tool (Oxygen is the tool recommended by IMS/GLC) to generate the WSDL files. The XSL files automatically create the full set of WSDL files using a predetermined naming convention for the corresponding directory structure, the name(s) of the services and the communications model. The generation process also creates a validation report text file that can be used to identify any problems that the I-BAT found while creating the binding files. The XSL 'WSDLtoHTML.xsl' is used to generate a HTML document that contains the description of the services defined by the WSDL.

Schematic representation of creating a WSDL binding for an IMS web service
Figure 4.1 Schematic representation of creating a WSDL binding for an IMS web service.

The following points should be noted when using the I-BAT:

  • The I-BAT creates several different sets of the binding that are categorised as:
    • Single file WSDL/XSD representation in which the WSDL and XSD descriptions are contained in a single file (this is the recommended binding as many of the WSDL-processing tools do not support the multiple file WSDL bindings)
    • Split file representation in which the WSDL and XSD descriptions are contained in separate files i.e. one file for the WSDL and a second file for the XSD
    • Split service representation in which the WSDL and XSD descriptions are contained in separate files i.e. two files for the WSDL (one for the abstract description and the other for the service specific description) and a third file for the XSD
    • Multiple file representation in which the WSDL descriptions are contained in two files (one for the abstract description and the other for the service specific description) and the XSD is spread over several linked files;
  • The I-BAT will attempt to generate the binding files irrespective of any problems described in the validation report;
  • The I-BAT cannot be used to correct problems with the UML-based service description. Any problems in the Information Model must be corrected using the appropriate UML authoring tool. The binding creation process must then be repeated using the new XMI file;
  • Any hand edits of the WSDL/XSD files will be lost when new binding files are created.

The I-BAT is made available to support the development of non-IMS specifications. All of the templates and XSLs are supplied with the toolkit.

About This Document

Title IMS General Web Service Services Primer
Editor Colin Smythe (IMS)
Team Co-Leads Cathy Schroeder (Microsoft Corp.), James Simon (SUN Microsystems Corp.)
Version 1.0
Version Date 19 December 2005
Status Final Specification
Summary This document contains an overview of the IMS General Web Services. This primer gives an introduction to the set of profiles (Basic Profile, Addressing Profile, Security Profile and Attachments Profile). The overview also contains a description of how these profiles are to be used to support the development of an IMS specification and how the corresponding Web Services Description Language bindings are produced.
Revision Information 19 December 2005
Purpose This document is circulated for public adoption. This document should be used to introduce the IMS General Web Services specification.
Document Location http://www.imsglobal.org/gws/gwsv1p0/imsgws_primerv1p0.html

To register any comments or questions about this specification please visit: http://www.imsglobal.org/developers/ims/imsforum/categories.cfm?catid=20

List of Contributors

The following individuals contributed to the development of this document:

Name Organization
Fred Beshears UC Berkeley
John Evdemon Microsoft Corp.
Ron Kleinman SUN Micrsosystems Corp.
Sherman Mohler Cisco Learning Institute, Inc.
Cathy Schroeder Microsoft Corp.
James Simon SUN Microsystems Corp.
Colin Smythe Dunelm Services Ltd.
Scott Thorne MIT

Revision History

Version No. Release Date Comments
Final v1.0 19 December 2005 This is the first formal version of the Final Release.

Index

B
Base Profile 1, 2, 3, 4

C
Context 1, 2

I
IMS Auto-generation Binding Tool 1, 2, 3, 4
IMS General Web Services 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Addressing Profile 1, 2, 3
Attachments Profile 1, 2, 3
Base Profile 1, 2, 3, 4, 5, 6, 7
Security Profile 1, 2, 3
Internet Protocol 1, 2
IP Security 1
 

P
Protocols
HTTP 1, 2, 3
IP 1, 2, 3
IPSEC 1
SOAP 1, 2, 3, 4, 5
TCP 1, 2
 

S
Security 1, 2, 3, 4, 5
SOAP 1, 2, 3, 4, 5
SOAP with Attachments 1, 2

T
TCP 1, 2
Transmission Control Protocol 1, 2
Transport Layer Security 1

U
UDDI 1, 2
Unified Modelling Language 1, 2, 3, 4
UML 1, 2, 3
 

V
Virtual Private Network 1

W
W3C 1, 2
Web Services 1, 2, 3, 4, 5, 6
SOAP 1, 2, 3, 4, 5
WSDL 1, 2, 3, 4, 5, 6, 7
WS-Security 1
Web Services Interoperability Organization 1, 2, 3
WSDL 1, 2, 3, 4, 5, 6, 7
WS-I
Basic Profile 1
Basic Security Profile 1
Simple SOAP Binding Profile 1, 2
WS-I Basic Profile 1
WS-I Basic Security Profile 1
WS-I Simple SOAP Binding Profile 1, 2
WS-Security 1
 

X
XMI 1, 2, 3
XML 1, 2, 3, 4, 5
XML Schema 1, 2
XML Schema Definition 1
XSD 1, 2, 3
XSLT 1

1 WS-* refers to the second generation Web Services specifications/standards. Many of these new specifications/standards are referred to using a 'WS-' prefix e.g. WS-Security, WS-Addressing, etc. The first generation refers to the SOAP, WSDL and UDDI standards..

 

 

 

IMS Global Learning Consortium, Inc. ("IMS/GLC") is publishing the information contained in this IMS General Web Services Primer ("Specification") for purposes of scientific, experimental, and scholarly collaboration only.

IMS/GLC makes no warranty or representation regarding the accuracy or completeness of the Specification.
This material is provided on an "As Is" and "As Available" basis.

The Specification is at all times subject to change and revision without notice.

It is your sole responsibility to evaluate the usefulness, accuracy, and completeness of the Specification as it relates to you.

IMS/GLC would appreciate receiving your comments and suggestions.

Please contact IMS/GLC through our website at http://www.imsglobal.org

Please refer to Document Name:
IMS General Web Services Primer Revision: 19 December 2005