1EdTech Enterprise Services Best Practice and Implementation Guide Version 1.0 Final Specification

Copyright © 2004 1EdTech Consortium, Inc. All Rights Reserved.
The 1EdTech Logo is a registered trademark of 1EdTech Consortium, Inc.
Document Name: 1EdTech Enterprise Services Best Practice and Implementation Guide
Revision: 11 June 2004

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.

1EdTech 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 1EdTech's procedures with respect to rights in 1EdTech specifications can be found at the 1EdTech Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Copyright © 2004 1EdTech 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 1EdTech found on the 1EdTech website: http://www.imsglobal.org/license.html.

The limited permissions granted above are perpetual and will not be revoked by 1EdTech 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.

Table of Contents

1. Introduction
     1.1 Enterprise Services Overview
     1.2 Scope and Context
     1.3 Structure of this Document
     1.4 Nomenclature
     1.5 References

2. Related Specifications and Activities
     2.1 1EdTech Enterprise v1.1 Specification
     2.2 Other 1EdTech Specifications
           2.2.1 1EdTech Learner Information Package v1.0 Specification
           2.2.2 1EdTech General Web Services Recommendations
     2.3 The Abstract Framework
     2.4 Related Activities
           2.4.1 World Wide Web Consortium (W3C)
           2.4.2 Web Services Interoperability Organization (WS-I)
           2.4.3 Open Knowledge Initiative (OKI)
     2.5 Related Specifications
           2.5.1 WSDL Specification
           2.5.2 WS-I Profile
           2.5.3 Internet vCard Specification
           2.5.4 Internet2 eduPerson
           2.5.5 LDAP Specification
           2.5.6 OKI Open Services Interface Definition (OSID)

3. Overall Services Model
     3.1 Overall Domain Model
     3.2 Class Summaries
           3.2.1 Person Management Service
           3.2.2 Group Management Service
           3.2.3 Membership Management Service
     3.3 WSDL Bindings
           3.3.1 Person Management Services
           3.3.2 Group Management Services
           3.3.3 Membership Management Services
           3.3.4 Namespacing

4. SOAP/HTTP Messages for Synchronous Services
     4.1 The SOAP/HTTP Message Structures
           4.1.1 Request Messages
           4.1.2 Response Messages
     4.2 Person Management Service Messages
     4.3 Group Management Service Messages
     4.4 Membership Management Service Messages

5. SOAP/HTTP Messages for Asynchronous Services

6. Mapping for Other Specifications
     6.1 1EdTech Enterprise Specification v1.1
           6.1.1 Person Management Service
           6.1.2 Group Management Service
           6.1.3 Membership Management Service
     6.2 1EdTech Learner Information Package (LIP)
     6.3 IETF vCard Support
     6.4 Internet2/Educause 'eduPerson' Support
     6.5 LDAP Attribute Mapping
     6.6 OKI Enterprise Service OSIDs

7. Best Practice
     7.1 Achieving Interoperability
           7.1.1 Human Resource Management System
           7.1.2 Corporate Training Management System
           7.1.3 Student Administration System
           7.1.4 Library Management System
     7.2 Implementing the Abstract API
           7.2.1 Single Transaction/Single Operation
           7.2.2 Multiple Transactions/Multiple Operations
           7.2.3 Multiple Transactions/Single Operation
           7.2.4 Single and Multiple Sessions
           7.2.5 Identifiers and SourcedIds
           7.2.6 Passing More Parameters
           7.2.7 Creating an Implementation API
     7.3 Status Codes and SOAP Fault Messages
           7.3.1 Status Codes
           7.3.2 SOAP Fault Codes
           7.3.3 Handling the Status Codes
     7.4 Architectural Considerations
           7.4.1 Information Synchronization
           7.4.2 Push and Pull Transactions
           7.4.3 'Snapshot' and Event Driven Transactions
           7.4.4 Common Services and Service Choreography
     7.5 Synchronous and Asynchronous Communications
     7.6 Using the Person Data Model
           7.6.1 Changes from Enterprise Specification v1.1
           7.6.2 Considerations for Each Operation
     7.7 Using the Group Data Model
           7.7.1 Changes from Enterprise Specification v1.1
           7.7.2 Groups and Sub-groups
           7.7.3 Cross-listed Course Sections
     7.8 Using the Membership Data Model
           7.8.1 Considerations for Each Operation
           7.8.2 Assigning Group Membership Role-type
     7.9 1EdTech Harmonization

8. Supporting the Use Cases
     8.1 Person Management Service Use Cases
     8.2 Group Management Service Use Cases
     8.3 Membership Management Service Use Cases

9. Extending the Services
     9.1 Proprietary Extensions to the Enterprise Services
           9.1.1 Extensions to the Data Models
           9.1.2 Extensions to the Behaviors
     9.2 Planned Extensions for the Enterprise Services
           9.2.1 Potential New Behaviors for Established Services
           9.2.2 Potential New Services

Appendix A - Glossary of Terms

Appendix B - OKI Enterprise Services OSIDs

About This Document
     List of Contributors

Revision History

Index

1. Introduction

1.1 Enterprise Services Overview

The Enterprise Services specification [EntService, 04b] is the definition of how systems manage the exchange of information that describes people, group and memberships within the context of learning. The Enterprise Services specification is constructed following the recommendations documented in the 1EdTech Abstract Framework (IAF) [AbsGloss, 03], [AbsASC, 03], [AbsWhite, 03]. This means that this specification is based upon:

• Interoperability - Enterprise Services focuses on the exchange of information between Enterprise systems. The specification makes no assumptions on how the data is managed within the Enterprise systems;
• Service-oriented - Enterprise Services defines the exchange of information in terms of the services being supplied by the collaboration of the systems. This takes the form of Person Management Services, Group Management Services and Membership Management Services;
• Component-based - the set of services will be supplied such that they can be combined to form a range of services. The Person Management Services, Group Management Services and Membership Management Services can be combined to provide other services and the Enterprise Service will have other services added to it in later releases;
• Layering - the Enterprise Service and its constituent services (Person, Group and Membership) are part of the Application Services layer;
• Behaviors and Data Models - the Enterprise Services are defined in terms of their behaviors and data models. The behaviors cause changes in the state of the data model and the state of the data model will only be altered as a result of a clearly defined behavior;
• Multiple Bindings - the Enterprise Services information model is to be defined using the Unified Modelling Language (UML). This enables reliable mapping of the information model into a range of different bindings. The bindings of immediate importance are to the Web Services Description Language (WSDL);
• Adoption - the Enterprise Services are based upon the original Enterprise specification data model. While there are significant changes the underlying data model has been maintained and the core Person, Group and Membership structures remain.

1.2 Scope and Context

This document is the 1EdTech Enterprise Services Best Practice and Implementation Guide v1.0 and as such it is used to support the following documents:

1. 1EdTech Enterprise Services Core Use Cases v1.0 [EntService, 04a] - the set of use cases that are the basis for the definition of the information model;
2. 1EdTech Enterprise Services Specification v1.0 [EntServices, 04b] - this presents the overall structure and capabilities of the Enterprise Services specification;
3. 1EdTech Enterprise Services Conformance Specification v1.0 [EntServices, 04c] - the definition of the conformance criteria that must be followed by systems that wish to claim compliance to the Enterprise Services Information model;
4. 1EdTech Person Management Services Information Model v1.0 [PersonServices, 04a] - the information model of the Person Management Services;
5. 1EdTech Person Management Services WSDL Binding v1.0 [PersonServices, 04b] - the description of the WSDL binding of the Person Management Services information model;
6. 1EdTech Group Management Services Information Model v1.0 [GroupServices, 04a] - the information model of the Group Management Services;
7. 1EdTech Group Management Services WSDL Binding v1.0 [GroupServices, 04b] - the description of the WSDL binding of the Group Management Services information model;
8. 1EdTech Membership Management Services Information Model v1.0 [MemberServices, 04a] - the information model of the Membership Management Services;
9. 1EdTech Membership Management Services WSDL Binding v1.0 [MemberServices, 04b] - the description of the WSDL binding of the Membership Management Services information model.

As such the Enterprise Services specification supersedes the original Enterprise specifications:

1. 1EdTech Enterprise Information Model Final Specification v1.1 [Enterprise, 02a].
2. 1EdTech Enterprise XML Binding Final Specification v1.1 [Enterprise, 02b];
3. 1EdTech Enterprise Services Best Practice and Implementation Guide Final Specification v1.0 [Enterprise, 02c].

This best practice and implementation guide describes some of the issues that need to be addressed during various stages of adoption. This is the first version of these services and so most of the best practice is derived from experience of proprietary implementations of similar functionality.

1.3 Structure of this Document

The structure of this document is:

1.4 Nomenclature

1.5 References

2. Related Specifications and Activities

2.1 1EdTech Enterprise v1.1 Specification

The 1EdTech Enterprise Services specification supersedes the 1EdTech Enterprise v1.1 specification. The services specification adds behaviors to the data model defined in the Enterprise v1.1 specification. The Enterprise Service uses a similar data model to that of the Enterprise v1.1 specification. All of the data-oriented information model features of the Enterprise v1.1 Specification are supported by the new Enterprise Services. The only core feature of the Enterprise v1.1 specification that is not supported is the <property> element. This element was used to provide some behavior capabilities and as such it is not required and is replaced by the usage of the service definitions.

2.2 Other 1EdTech Specifications

2.2.1 1EdTech Learner Information Package v1.0 Specification

There is some overlap of functionality between the 1EdTech Enterprise Services and the 1EdTech Learner Information Package (LIP) specification [LIP, 01a], [LIP, 01b], [LIP, 01c]. The overlap is between the 1EdTech Person Management Service (I-PMS) and the 1EdTech LIP <identification> element. The I-PMS should be used for interactions that involve the 1EdTech Group Management and 1EdTech Membership Management services. The 1EdTech LIP functionality should be used when working with individual profiles e.g., ePortfolios, life-long learning logs, etc.

2.2.2 1EdTech General Web Services Recommendations

The web service binding of the Enterprise Services specification is based upon the 1EdTech General Web Services recommendations [GWS, 04a], [GWS, 04b]. The 1EdTech General Web Services Base Profiles [GWS, 04a] provide a basic structure for the definition of Web Services. They consist 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 Profiles address the most common problems experienced when implementing web service specifications. The 1EdTech Enterprise Service is based upon the General Web Services Base Profile.

The 1EdTech General Web Services UML to WSDL Binding Transformation Rules [GWS, 04b] outlines a process for creating web service bindings using the Base Profiles, Abstract Framework and business domain knowledge intrinsic to the Information Model of a particular Specification. This includes guidelines that instruct project teams in how to use the Work Aids in gathering information, processing information, and specifying a Web Services protocols and binding as appropriate. The methodology includes information and graphics describing the role and relationship of the General Web Services methodology to the 1EdTech Specifications. The 1EdTech Enterprise Services bindings have been created using these transformation rules.

2.3 The Abstract Framework

The 1EdTech Abstract Framework is an approach to enable the 1EdTech to describe the context within which it develops its e-learning technology specifications. This framework is not an attempt to define the 1EdTech architecture, rather it is a mechanism to define the set of interfaces for which 1EdTech may or may not produce a set of interoperability specifications. It is the intention of 1EdTech that the Abstract Framework and the associated 1EdTech specifications produced to realize the exchange of information between the identified services will be adopted in a manner suitable for a particular system requirement. The core features of the framework are:

• Application layer - the set of systems, tools and applications that are constructed from the suite of application and common services to provide a particular set of e-learning functionality;
• Application services layer - the set of entities that provide the e-learning specific services e.g., course management. It is these services that constitute the primary focus for 1EdTech specification development;
• Common services layer - the set of entities that provide the generic services to be used by the application services e.g., authentication;
• Infrastructure layer - the underlying services that enable the exchange of the data structures in terms of physical communications, messaging and corresponding transaction needs;
• Service access points - the access points, or interface, to the corresponding service. Each access point provides access to one service capability;
• Entities - the processes that are used to represent a particular service. The realization of an entity with its service access points is termed a component and its abstract representation is called a Class.

The Enterprise Service and its component services (the Person Management Service, the Group Management Service and the Membership Management Service) are all entities within the Applications Services layer of the IAF. The binding of these services is based upon the usage of a web services infrastructure of SOAPv1.1/HTTPv1.1 defined using WSDLv1.1.

2.4 Related Activities

2.4.1 World Wide Web Consortium (W3C)

The World Wide Web Consortium (W3C) develops interoperable technologies (specifications, guidelines, software, and tools) to lead the Web to its full potential. The 1EdTech makes extensive usage of some of the W3C specifications, in particular:

• XML and related technologies - this is used by 1EdTech as the basis for the data model bindings;
• SOAP - this is used by 1EdTech as one of communication protocols for the service model bindings;
• Web services and WSDL - this is used by 1EdTech as the basis for the service model bindings.

Further information is available at: http://www.w3c.org.

2.4.2 Web Services Interoperability Organization (WS-I)

WS-I is an open, industry organization chartered to promote Web services interoperability across platforms, operating systems, and programming languages. The organization works across the industry and standards organizations to respond to customer needs by providing guidance, best practices, and resources for developing Web services solutions. WS-I was formed specifically for the creation, promotion, or support of Generic Protocols for Interoperable exchange of messages between services. Generic Protocols are protocols that are independent of any specific action indicated by the message beyond actions necessary for the secure, reliable, or efficient delivery of messages; "Interoperable" means suitable for and capable of being implemented in a neutral manner on multiple operating systems and in multiple programming languages.

More details are available at: http://www.ws-i.org.

2.4.3 Open Knowledge Initiative (OKI)

The core deliverable of the Open Knowledge Initiative (OKI) is an architectural specification in support of learning management and educational application development, the primary feature of which is a set of application programming interface (API) definitions. OKI are specifying the architecture by identifying a set of services, a framework, upon which learning tool developers can base their work. See Appendix B for more details.

2.5 Related Specifications

2.5.1 WSDL Specification

The 1EdTech service model bindings are expressed using WSDL v1.1. Version 1.1 is used in preference to version 2.0 due to the maturity of the earlier version and the availability of tools to support the development and adoption of the accompanying 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.

The 1EdTech Enterprise Services bindings are expressed as WSDL files. The structure of these files is summarized in Section 3.3.

2.5.2 WS-I Profile

The WS-I Basic Profile is shown in Table 2.1.

It is recognized that SOAP v1.2 and WSDL v1.2 are later versions of the SOAP and WSDL specifications respectively, however, there are no sufficiently robust tools that support these versions. The 1EdTech GWS Basic Profile uses the WS-I basic profile with the exception of the UDDI. See [GWS, 04a] and [GWS, 04b] for further details.

2.5.3 Internet vCard Specification

The vCard specification allows the open exchange of Personal Data Interchange (PDI) information typically found on traditional paper business cards. The specification defines a format for an electronic business card, or vCard. The vCard specification is suitable as an interchange format between applications or systems. The format is defined independent of the particular method used to transport it. The transport for this exchange might be a file system, point-to-point public switched telephone networks, wired-network transport, or some form of unwired transport. The vCard has direct application to the way users utilize the Internet network. The vCard can be used to forward personal data in an electronic mail message. The numerous forms a user of the WWW fills out on a homepage can also be automated using the vCard. The Internet Mail Consortium is working with the Internet Engineering Task Force (IETF) to complete work on an extension to the Internet MIME-based electronic mail standard to allow for this capability. An XML binding of the vCard specification has produced a DTD [vCard, 98] and this has been used to inform the development of the 1EdTech Enterprise Person structure.

The mapping between the 1EdTech Enterprise Service and vCard is shown in Section 6.3.

2.5.4 Internet2 eduPerson

In February 2001, the joint Internet2(R) and EDUCAUSE working group announced the release of the 'eduPerson' specification for services that provide seamless access to network-accessible information regardless of where or how the original information is stored. The eduPerson specification provides a set of standard higher-education attributes for an enterprise directory, which facilitate inter-institutional access to applications and resources across the higher education community. The EDUCAUSE/Internet2 eduPerson task force has the mission of defining a Lightweight Directory Access Protocol (LDAP) object class that includes widely-used person attributes in higher education.

The mapping between the 1EdTech Enterprise Service and eduPerson is shown in Section 6.4.

2.5.5 LDAP Specification

The Lightweight Directory Access Protocol (LDAP) is an Internet protocol for accessing distributed directory services that act in accordance with X.500 data and service models. The terms "LDAP" and "LDAPv3" are commonly used to informally refer to the protocol specified by this technical specification. The LDAP suite, as defined here, should be formally identified in other documents by a normative reference to this document. LDAP is an extensible protocol. More detail is available from: http://www.ietf.org.

The mapping between the 1EdTech Enterprise Service and LDAP is shown in Section 6.5.

2.5.6 OKI Open Services Interface Definition (OSID)

Further detail on the OKI OSIDs is given in Appendix B. The mapping between the 1EdTech Enterprise Service and vCard is shown in Section 6.6.

3. Overall Services Model

3.1 Overall Domain Model

A schematic representation of the core objects exchanged using the 1EdTech Enterprise Services specification is given in Figure 3.1; this diagram is based upon the 1EdTech Abstract Framework.

The core enterprise services are:

• Person management service - the management of information about individuals who are undertaking some form of study and/or group related activity e.g., they are members of a particular course. The person record is designed to be a data model for all of the personal information to be exchanged about an individual;
• Group management service - the management of information about a collection of objects related to learning activities or individuals. There is no restriction on how the Group and sub-group structures can be used with respect to containing other groups, persons, etc.;
• Membership management service - the management of information about the membership structure is used to define the members of a Group. A member can be a Person or another Group. A Group or Person can be a member of any number of groups. The Group and the member are identified using their sourcedIds.

Two other Enterprise Services have been identified: Gradebook management service and Course catalog management service. They are not be defined as part of the V1.0 information model but may be included in later releases.

3.2 Class Summaries

It is important to note that the UML representation of the interfaces is used to help develop and document the corresponding service information models. It is not a requirement for an implementation to implement this interface as defined i.e., to use the same parameters, etc. Conformance against this specification will be confirmed by inspecting the appropriate binding of the information model and ensuring that the relevant information is present and that different sequences of activity result in the predicted and mandated behavior. It is essential that the behaviors described by each of the operations are fully supported and it is also essential that the behaviors described by different sequences are also maintained.

3.2.1 Person Management Service

The PersonManagementService class is used to model the service responsible for manipulating information about people. The PersonManagementService is split into two interface classes: PersonManager that supports the manipulation of a single Person object; PersonsManager that supports the manipulation of two or more Person objects bound in a single transaction [PMS, 04a]. The manipulation of multiple Person objects can also be supported by the iteration over the PersonManager however this will result in multiple independent transactions. The data-types used to support the PersonsManager class are derived as sets of the equivalent data-types used for the PersonManager class. The service operations are summarized in Table 3.1.

3.2.2 Group Management Service

The GroupManagementService class is used to model the service responsible for manipulating information about groups. The Group Management Service is split into two interface classes: GroupManager that supports the manipulation of a single Group object; GroupsManager that supports the manipulation of two or more Group objects bound in a single transaction [GMS, 04a]. The manipulation of multiple Group objects can also be supported by the iteration over the GroupManager however this will result in multiple independent transactions. The data-types used to support the GroupsManager class are derived as sets of the equivalent data-types used for the GroupManager class. The operations are summarized in Table 3.2.

3.2.3 Membership Management Service

The MembershipManagementService class is used to model the service responsible for manipulating information about the membership of people or groups in groups. The Membership Management Service is split into two interface classes: MembershipManager that supports the manipulation of a single Membership object; MembershipsManager that supports the manipulation of two or more Membership objects bound in a single transaction [MMS, 04a]. The manipulation of multiple Membership objects can also be supported by the iteration over the Membership Manager however this will result in multiple independent transactions. The data-types used to support the MembershipsManager class are derived as sets of the equivalent data-types used for the Membership Manager class. The operations are summarized in Table 3.3.

3.3 WSDL Bindings

The WSDL bindings have been generated using the methodology documented in [GWS 04a] and [GWS, 04b].

3.3.1 Person Management Services

The composition of the synchronous Person Management Services WSDL binding files is listed below [PMS, 04b]:

• 'imsPersonManServiceSyncv1p0.wsdl' - the synchronous service specific WSDL binding file. For the Person Management Service this is based upon SOAP/http. This file imports the abstract definitions using the <wsdl:import> construct;
• 'imsPersonManAbstractSyncv1p0.wsdl' - the synchronous abstract message definitions that represent the behavior of the Person Management Service operations. This file imports the message XSD using the <xsd:import> construct;
• 'imsPersonManSyncv1p0.wsdl' - the synchronous WSDL binding file. This is the single file equivalent of the combination of the 'imsPersonManServiceSyncv1p0.wsdl' and 'imsPersonManAbstractSyncv1p0.wsdl' files;
• 'imsPersonManMessSchemav1p0.xsd' - the XSD definitions for the synchronous and asynchronous messages. This file imports the Person data model XSD using the <xsd:import> construct;
• 'imsPersonManDataSchemav1p0.xsd' - the definition of the Person data model. This is the file that was produced by the equivalent data model binding in Enterprise v1.1;
• 'imsMessBindSchemav1p0.xsd' - the XSD binding of the message header parts. This includes the message headers for synchronous, polled and asynchronous message models;
• 'imsEnterpriseCommonSchemav1p0.xsd' - the XSD binding of the 1EdTech Enterprise Services common data objects. This file is used by the Person message and data model XSDs as well as the 1EdTech message binding XSD;
• 'wsiwsdlv1p1.xsd' - this is the reference XSD for the WSDL definition. This file is the WS-I amended version of the original file from W3C;
• 'wsisoapv1p1.xsd' - this is the reference XSD for the SOAP extensions to WSDL. This file is from WS-I.

3.3.2 Group Management Services

The composition of the synchronous and asynchronous Group Management Services WSDL binding files is listed below [GMS, 04b]:

• 'imsGroupManServiceSyncv1p0.wsdl' - the synchronous service specific WSDL binding file. For the Group Management Service this is based upon SOAP/http. This file imports the abstract definitions using the <wsdl:import> construct;
• 'imsGroupManAbstractSyncv1p0.wsdl' - the synchronous abstract message definitions that represent the behavior of the Group Management Service operations. This file imports the message XSD using the <xsd:import> construct;
• 'imsGroupManSyncv1p0.wsdl' - the synchronous WSDL binding file. This is the single file equivalent of the combination of the 'imsGroupManServiceSyncv1p0.wsdl' and 'imsGroupManAbstractSyncv1p0.wsdl' files;
• 'imsGroupManMessSchemav1p0.xsd' - the XSD definitions for the synchronous and asynchronous messages. This file imports the Group data model XSD using the <xsd:import> construct;
• 'imsGroupManDataSchemav1p0.xsd' - the definition of the Group data model. This is the file that was produced by the equivalent data model binding in Enterprise v1.1;
• 'imsMessBindSchemav1p0.xsd' - the XSD binding of the message header parts. This includes the message headers for synchronous, polled and asynchronous message models;
• 'imsCommonSchemav1p0.xsd' - the XSD binding of the 1EdTech common data objects. This file is used by the Group message and data model XSDs as well as the 1EdTech message binding XSD;
• 'wsiwsdlv1p1.xsd' - this is the reference XSD for the WSDL definition. This file is the WS-I amended version of the original file from W3C;
• 'wsisoapv1p1.xsd' - this is the reference XSD for the SOAP extensions to WSDL. This file is from WS-I.

3.3.3 Membership Management Services

The composition of the synchronous and asynchronous Person Management Services WSDL binding files is listed below [MMS, 04b]:

• 'imsMemberManServiceSyncv1p0.wsdl' - the synchronous service specific WSDL binding file. For the Membership Management Service this is based upon SOAP/http. This file imports the abstract definitions using the <wsdl:import> construct;
• 'imsMemberManAbstractSyncv1p0.wsdl' - the synchronous abstract message definitions that represent the behavior of the Membership Management Service operations. This file imports the message XSD using the <xsd:import> construct;
• 'imsMemberManSyncv1p0.wsdl' - the synchronous WSDL binding file. This is the single file equivalent of the combination of the 'imsMemberManServiceSyncv1p0.wsdl' and 'imsMemberManAbstractSyncv1p0.wsdl' files;
• 'imsMemberManMessSchemav1p0.xsd' - the XSD definitions for the synchronous and asynchronous messages. This file imports the Membership data model XSD using the <xsd:import> construct;
• 'imsMemberManDataSchemav1p0.xsd' - the definition of the Membership data model. This is the file that was produced by the equivalent data model binding in Enterprise v1.1;
• 'imsMessBindSchemav1p0.xsd' - the XSD binding of the message header parts. This includes the message headers for synchronous, polled and asynchronous message models;
• 'imsCommonSchemav1p0.xsd' - the XSD binding of the 1EdTech common data objects. This file is used by the Membership message and data model XSDs as well as the 1EdTech message binding XSD;
• 'wsiwsdlv1p1.xsd' - this is the reference XSD for the WSDL definition. This file is the WS-I amended version of the original file from W3C;
• 'wsisoapv1p1.xsd' - this is the reference XSD for the SOAP extensions to WSDL. This file is from WS-I.

3.3.4 Namespacing

The name spaces used within the bindings are listed in Table 3.4.

4. SOAP/HTTP Messages for Synchronous Services

4.1 The SOAP/HTTP Message Structures

All of the messages described in the following examples have the same basic structure. The structure of these Request/Response messages is now described.

4.1.1 Request Messages

The basic SOAP/HTTP request message is shown below. The HTTP components are shown in lines (1-5). The invoking service name is shown in line (1) with the host server identified in line (2). The associated SOAP Action is given in line (5). The associated SOAP message structure is supplied in lines (7-9) i.e., enclosed in the element <SOAP-ENV:Envelope>. The usage of the namespace 'SOAP-ENV:' is defined in line (7).

0001

0002

0003

0004

0005

0006

0007

0008

0009

POST /PersonManagementService HTTP/1.1

Host: www.personmanagementserver.com

Content-Type: text/xml; charset="utf-8"

Content-Length: nnnn

SOAPAction: "http://www.imsglobal.org/soap/pms/deletePerson"

 

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

...

</SOAP-ENV:Envelope>

The detailed structure of the SOAP envelope is shown below. The contents of the SOAP envelope are listed in lines (7-15). The envelope consists of the SOAP header, lines (8-12) and the SOAP body, lines (13-15). The SOAP header is used to contain the message control information that is required for the synchronous end-to-end messaging to support the service behaviors. The header namespace is defined in line (9).

Every request message has a unique message identifier, i.e., line (10). The transmitting system is responsible for creating this unique identifier. The structure for this header is shown in the file 'imsMessBindSchemav1p0.xsd'.

0001

0002

0003

0004

0005

0006

0007

0008

0009

0010

0011

0012

0013

0014

0015

0016

POST /PersonManagementService HTTP/1.1

Host: www.personmanagementserver.com

Content-Type: text/xml; charset="utf-8"

Content-Length: nnnn

SOAPAction: "http://www.imsglobal.org/soap/pms/deletePerson"

 

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

   <SOAP-ENV:Header>

      <h:syncRequestHeaderInfo xmlns:h="../imsMessBindSchemav1p0.xsd">

         <h:messageIdentifier>AB12345e4t6789</h:messageIdentifier>

      </h:syncRequestHeaderInfo>

   </SOAP-ENV:Header>

   <SOAP-ENV:Body>

   ...

   </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

The SOAP body is shown below in lines (13-19). The namespace to be used in the body is defined in line (14). Line (14) also contains the associated XSD control document file.

0001

0002

0003

0004

0005

0006

0007

0008

0009

0010

0011

0012

0013

0014

0015

0016

0017

0018

0019

0020

POST /PersonManagementService HTTP/1.1

Host: www.personmanagementserver.com

Content-Type: text/xml; charset="utf-8"

Content-Length: nnnn

SOAPAction: "http://www.imsglobal.org/soap/pms/deletePerson"

 

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

   <SOAP-ENV:Header>

      <h:syncRequestHeaderInfo xmlns:h="../imsMessBindSchemav1p0.xsd">

         <h:messageIdentifier>AB12345e4t6789</h:messageIdentifier>

      </h:syncRequestHeaderInfo>

   </SOAP-ENV:Header>

   <SOAP-ENV:Body>

      <m:deletePersonRequest xmlns:m="../imsPersonManMessSchemav1p0.xsd">

         <m:sourcedId>

            <esx:identifier>oldsource:oldidentifier</esx:identifier>

         </m:sourcedId>

      </m:deletePersonRequest>

   </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

4.1.2 Response Messages

The basic SOAP/HTTP response message is shown below. The associated SOAP message structure is supplied in lines (5-7) i.e., enclosed in the element <SOAP-ENV:Envelope>. The usage of the namespace 'SOAP-ENV:' is defined in line (5).

0001

0002

0003

0004

0005

0006

0007

HTTP/1.1 200 OK

Content-Type: text/xml; charset="utf-8"

Content-Length: nnnn

 

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

...

</SOAP-ENV:Envelope>

The detailed structure of the SOAP envelope is shown below. The contents of the SOAP envelope are listed in lines (5-19). The envelope consists of the SOAP header, lines (6-15) and the SOAP body, lines (16-18). The SOAP header is used to contain the message control information that is required for the synchronous end-to-end messaging to support the service behaviors. The header namespace is defined in line (7).

Every response message has a unique message identifier, i.e., line (8). The transmitting system is responsible for creating this unique identifier. The structure for this header is shown in the file 'imsMessBindSchemav1p0.xsd'.

Every response message has a status field. The status field for a single transaction it is supplied as <h:statusInfo> whereas for multiple transactions it is supplied as <h:statusInfoSet>. The content of the status information is defined in the 1EdTech Common Data Model [ESCommon, 04].

0001

0002

0003

0004

0005

0006

0007

0008

0009

0010

0011

0012

0013

0014

0015

0016

0017

0018

0019

HTTP/1.1 200 OK

Content-Type: text/xml; charset="utf-8"

Content-Length: nnnn

 

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

   <SOAP-ENV:Header>

      <h:syncResponseHeaderInfo xmlns:h="../imsMessBindSchemav1p0.xsd">

         <h:messageIdentifier>AB12345e4t6889</h:messageIdentifier>

         <h:statusInfo>

            <h:codeMajor>success</h:codeMajor>

            <h:severity>status</h:severity>

            <h:messageIdRef>AB12345e4t6789</h:messageIdRef>

         </h:statusInfo>

      </h:syncResponseHeaderInfo>

   </SOAP-ENV:Header>

   <SOAP-ENV:Body>

      ...

   </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

The SOAP body is shown below in lines (16-18). The namespace to be used in the body is defined in line (17). Line (17) also contains the associated XSD control document file.

0001

0002

0003

0004

0005

0006

0007

0008

0009

0010

0011

0012

0013

0014

0015

0016

0017

0018

0019

HTTP/1.1 200 OK

Content-Type: text/xml; charset="utf-8"

Content-Length: nnnn

 

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

   <SOAP-ENV:Header>

      <h:syncResponseHeaderInfo xmlns:h="../imsMessBindSchemav1p0.xsd">

         <h:messageIdentifier>AB12345e4t6889</h:messageIdentifier>

         <h:statusInfo>

            <h:codeMajor>success</h:codeMajor>

            <h:severity>status</h:severity>

            <h:messageIdRef>AB12345e4t6789</h:messageIdRef>

         </h:statusInfo>

      </h:syncResponseHeaderInfo>

   </SOAP-ENV:Header>

   <SOAP-ENV:Body>

      <m:deletePersonResponse xmlns:m="../imsPersonManMessSchemav1p0.xsd"/>

   </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

4.2 Person Management Service Messages

The set of example Person Management Service SOAP/HTTP messages are described in Table 4.1. These files are stored in the directory '/examples/pms/sync/<operationname>/'. To access the example click on the corresponding filename listed in Table 4.1.

4.3 Group Management Service Messages

The set of example Group Management Service SOAP/HTTP messages are described in Table 4.2. These files are stored in the directory '/examples/gms/sync/<operationname>/'. To access the example click on the corresponding filename listed in Table 4.2.

4.4 Membership Management Service Messages

The set of example Membership Management Service SOAP/HTTP messages are described in Table 4.3. These files are stored in the directory '/examples/mms/sync/<operationname>/'. To access the example click on the corresponding filename listed in Table 4.3.

5. SOAP/HTTP Messages for Asynchronous Services

Note: At the time of publication the Asynchronous Binding had not been tested. The Asynchronous Binding example details will be issued in V2.0 of this document once testing has been completed.

6. Mapping for Other Specifications

6.1 1EdTech Enterprise Specification v1.1

6.1.1 Person Management Service

The Person Management Services is the service that is used to exchange the equivalent information contained within the Person data model as described in the 1EdTech Enterprise Information Model v1.1 [Enterprise, 03a]. The support of the v1.1 Person data model by the new Person Management Service is shown in Table 6.1.

6.1.2 Group Management Service

The Group Management Services is the service that is used to exchange the equivalent information contained within the Group data model as described in the 1EdTech Enterprise Information Model v1.1 [Enterprise, 03a]. The support of the v1.1 Group data model by the new Group Management Service is shown in Table 6.2.

6.1.3 Membership Management Service

The Membership Management Services is the service that is used to exchange the equivalent information contained within the Membership data model as described in the 1EdTech Enterprise Information Model v1.1 [Enterprise, 03a]. The support of the v1.1 Membership data model by the new Membership Management Service is shown in Table 6.3.

6.2 1EdTech Learner Information Package (LIP)

The mapping between the 1EdTech Person Management Services <person> element and the 1EdTech LIP <identification> element is shown in Table 6.4.

6.3 IETF vCard Support

The 1EdTech Enterprise Service is compatible with the IETF vCard specification i.e., many of the vCard fields can be contained by an Enterprise-XML instance and the rest are supported through the use of the Person extension element. This relationship is shown in Table 6.5, namely:

6.4 Internet2/Educause 'eduPerson' Support

The eduPerson specification is an object class for LDAP services whereas Enterprise is a set of data objects for the exchange of learner Enterprise information and not just directory-related information. The relationship between the eduPerson V1.0 specification and the 1EdTech Person management Services is summarized in Table 6.6.

6.5 LDAP Attribute Mapping

Most enterprise systems utilize a directory to store organizational and person information. Many directories use the Lightweight Directory Access Protocol (LDAP) to store this data and make it accessible to other Enterprise applications. It is likely that Learning Management Systems will use some of the data in an LDAP directory to populate equivalent fields in the 1EdTech Enterprise XML binding. Table 6.7 represents a preliminary mapping between LDAP base schema items and 1EdTech Enterprise elements. This is provided only as an example. The reader who wishes to incorporate LDAP data into learning management applications is encouraged to consult authoritative sources regarding LDAP.

6.6 OKI Enterprise Service OSIDs

The OKI definition of 'Group' is different to that by 1EdTech, but there are still ways to relate the concepts found in both. The idea of a 'Group' in OKI is a set of people, whose purpose is left undefined and who are undifferentiated. A 'Group' can have subgroups as well as members, but the membership in a group is undifferentiated i.e., you are either a member or not.

The concept of 'Membership' in 1EdTech is that a person has one or more roletypes within a group. In OKI this would be expressed using the Authorization SID, by mapping 1EdTech roletypes as functions and treating 1EdTech groups as qualifiers.

These are really two different uses of group. In one sense it is a just a set of people and in another it is just a placeholder for some other entity such as a course. In OKI a 'Group' represents a set of people and what this means is left to the application. Therefore, a group could be constructed to represent the set of students in a course, but it wouldn't represent the course itself. In an application you would associate the group to the course. In this case the Course would be represented as a Qualifier in (OKI Authorization OSID). The Qualifier Identifier in the Authorization Service would be set to the CourseIdentifier. You would use the Authorization OSID to maintain and query peoples roles associated with the course. Groups used for mailing lists etc. could be created using the OKI Shared OSID, if this is also needed.

The 1EdTech Membership structure also contains results information. Results information in OKI is associated with a Course and a Person, and the methods found in the CourseManagement OSID.

In OKI there are different levels of abstractions, some more general and some more specific. In the Enterprise domain, OKI has three constructs for relationships:

• Groups - sets of people;
• Authorizations - assertions about people and their functions (or roles) within some context;
• CourseOfferings - represent courses and their information.

Therefore, depending on what your using 1EdTech Group and membership for, you may want to relate it to OKI in different ways.

Further detail on the relevant OKI OSIDs is given in Appendix B.

7. Best Practice

7.1 Achieving Interoperability

The following list describes some types of systems for which the 1EdTech Enterprise Services specification may support Learning Management interoperability. It includes a list of some interfaces that the current specification can support.

7.1.1 Human Resource Management System

Human Resource Management Systems (HRMS) manage personnel records, payroll, benefits, competency management, and other functions for an enterprise. Interoperability that can be supported by this specification include:

From HRMS to LMS:

• Person data maintained in the HRMS and passed to the LMS;
• HR departments passed as groups, and employees of those departments passed as members;
• Special groups of employees (new hires for example) passed to the LMS as training groups.

From LMS to HRMS:

• After the completion of training courses, course information is returned to the HRMS as groups, and completion of training courses, or it could come back as membership in those groups, with result information included.

7.1.2 Corporate Training Management System

Corporate Training Administration systems keep track of employee training plans, schedule training courses (including instructors and resources), enroll people in training, record training completed, and update employee competencies in an HRMS. They are also used to manage training delivered to customers. Interoperability that can be supported by this specification include:

From Training to LMS:

• Person data might be passed to the LMS from the training system;
• Training groups (courses) and memberships could be passed from training to the LMS.

From LMS to Training:

• After the completion of training courses, membership objects could be sent to the Training Administration system from the LMS with result (completion) information included.

7.1.3 Student Administration System

Student Administration Systems (SAS) keep track of student education plans, schedule courses (including instructors and resources), enroll people in courses, record course results, and update student academic progress. Interoperability that can be supported by this specification include:

From SAS to LMS:

• Person data for people enrolled in groups that are managed by the LMS;
• Group data could be passed from SAS to the LMS to create the groups;
• Group membership (course enrollment) data may be passed from SAS to the LMS;
• Final grade information may be passed to the LMS from the SAS in an updated Membership object if final grading occurs in the SAS, and the LMS needs the final grade for its records.

From LMS to SAS:

• Final grades could be returned to SAS from the LMS by passing back Membership records with the Result data provided. This data could then be entered into a formal grade roster process on the SA side.

7.1.4 Library Management System

Library Management systems can be thought of as a particular class of Learning Management system, in that they provide a set of services for managing the interaction of learners with learning objects. Therefore, it is appropriate to use this specification to support interfaces from other enterprise systems to Library Management systems in much the same way that these interfaces are supported with Learning Management Systems.

From SAS or HRMS to Library:

• People data;
• Groups - course sections for access to specific material, HR departments for access to services, alumni for access to limited services, etc.;
• Group membership.

7.2 Implementing the Abstract API

7.2.1 Single Transaction/Single Operation

The three services have operations that allow individual data objects to be manipulated. Each of these operations, contained within the 'PersonManager', 'GroupManager' and 'MembershipManager' interface classes, results in a single request/response message exchange. Each operation manipulates the state of one object (in some cases there may be ripple effects to ensure consistency across the full data set) and reports the result of that action. Therefore, these operations support a single transaction.

7.2.2 Multiple Transactions/Multiple Operations

If multiple transactions are required then this can be achieved by iterating across the single operations i.e., if five new person objects are to be created then five create operations can be issued sequentially. Each operation will carry a single transaction and so five operation calls results in five individual response/message exchanges. The advantage of this approach is that no new implementation features are required and there is an incremental change of state and it's reporting. The disadvantage is that for a large number of similar operations there is a significant communication overhead that could result in the communications network becoming overloaded. At the very least there will be a significant communications delay before all of the transactions are completed.

7.2.3 Multiple Transactions/Single Operation

An alternative approach for multiple transactions is to use the operations contained within the 'PersonsManager', 'GroupsManager' and 'MembershipsManager' interface classes. The corresponding operations enable many transactions on the same category of objects to be invoked in a single operation. In the above example of the creation of five new person objects, this would result in a single operation call containing the five bundled transactions. This results in a single request/response message. The advantage of this approach is that there is no extra communication overhead i.e., there is a single request/response message interaction. The disadvantage is that for a synchronous service there is no response until all of the transactions have been completed - this could be a long delay. The response reports on the status of each transaction and so the service requester must process the received message to pair the status information in the SOAP header with the corresponding data in the SOAP body. The SOAP messages contain all of the relevant linkage information.

7.2.4 Single and Multiple Sessions

The concept of a session is outside the scope of the specification. New operations can be defined to introduce the concept of a session but for asynchronous bindings this will need to address the implications of multiple sessions.

7.2.5 Identifiers and SourcedIds

In the 1EdTech Enterprise v1.1 specification the 'sourcedId' was a structured object i.e., it consisted of 'source' and 'id' sub-structures. In the 1EdTech Enterprise Services specification the 'sourcedId' is based upon the 'identifier' structure that is defined as a flat string. This flat string can be used to contain the sub-structured format from Enterprise v1.1 specification using the following algorithm:

1EdTech Enterprise Services 'sourcedId' = <source>&...&<id>

Where:

<source> is the value of the source element in the 1EdTech Enterprise v1.1 specification implementation;

<id> is the value of the id element in the 1EdTech Enterprise v1.1 specification implementation;

'&...&' is the delimiter between the 'source' and 'id' values. The number of '&' in the sequence must be one greater than the number of concatenated occurrences elsewhere i.e., in either the 'source' or the 'id' values.

In the case where the 'source' = 1EdTech and 'id' = wehu12kio then the new 'sourcedId' = 1EdTech&wehu12kio. In the case where the 'source' = IM&S and 'id' = wehu1&&2kio then the new 'sourcedId' = IM&S&&&wehu1&&2kio.

7.2.6 Passing More Parameters

The information models define what parameters are to be passed within the SOAP message body. At the current time there is no way to extend this set of parameters. If more parameters need to be passed then the following approaches can be considered:

• New operations are defined with similar functionality to those who parameters must be extended. The new definitions will include the new parameters;
• New operations are defined that establish an end-to-end session. The parameters passed in these session-establishing behaviors would then have meaning throughout the session.

1EdTech welcomes feedback on the issue of adding new parameters and how to best facilitate this in the specification.

7.2.7 Creating an Implementation API

The 1EdTech Enterprise Services specification defines an abstract API. This API is defined to enable the corresponding request/response to be created and represented in WSDL. There is no requirement to directly convert the abstract API to a language dependent implementation equivalent i.e., a Java API does not have to provide the 'createPerson' method, etc.

It is recommended that an appropriate implementation API be created to insulate the rest of the application from the communications handler responsible for Enterprise systems interoperability. This API should take the form most appropriate to the business process being supported by the Enterprise Services specification. This API will then provide the adaptation between those business processes and the creation and handling of the SOAP messages that are defined within the Enterprise Services binding.

The implementation API could also support other operations that have not been defined with the 1EdTech Enterprise Services specification. This is one way in which the 1EdTech specification can be extended. The only constraint is that the same message structure and choreography is followed. This ensures that any Service Provider can reject an unknown service request by returning the stats code 'unsupported' in the SOAP message header. Conversely, every implementation must be capable of rejecting unknown service requests. Any subsequent local error message logging etc. is implementation dependent.

7.3 Status Codes and SOAP Fault Messages

7.3.1 Status Codes

The 1EdTech Enterprise Services documentation and the 1EdTech Common Data Definitions documents give an extension description of the set of status codes that can be reported and the conditions under which the codes are to be reported. There are two further issues to be considered:

• Request authority - if the Service Requester does not have the appropriate authority for the issued request then the Service Provider will reject the request issuing the appropriate status code. The default codeMinor value is: 'authorizationfail';
• Conformance level mismatch - if there is a mismatch between the conformance levels of the two systems then there will be data exchange problems. In these cases the systems must exchange the maximum amount of data from their perspective. If the Service Provider cannot store all of the data it has been given then it returns a codeMajor/severity value of 'Success/Warning' with a codeMinor value of 'partialdatastorage'. If the Service Provider supplies too much information for the Service Requester then the invoking application receive the report of codeMajor/severity value of 'Success/Warning' with a codeMinor value of 'receivedataoverload'

7.3.2 SOAP Fault Codes

The SOAP faults are reported in the SOAP header. This means that when a SOAP request message is issued the response message may contain SOAP fault codes with no further useful information. It is the responsibility of the implementations of the Service Requester and Service Provider to convert the SOAP fault codes to the equivalent 1EdTech Enterprise Services status codes. The default codeMajor/severity values are 'Failure/Error' and the codeMinor value is 'soapfault'. More detailed codeMinor codes can be created if required.

7.3.3 Handling the Status Codes

The 1EdTech Enterprise Services specification does not describe how the status codes are to be passed from the Service Requester and Service Provider communications handlers i.e., the usage of the 'StatusInfo' and 'StatusInfoSet' objects is a part of the abstract API. An implementation API must describe how the status information is to be passed t the driving applications. There are several alternatives including being passed as a parameter in the API interface and requiring interrogation using a special status code API interface call. Clearly, the manner in which the status codes are handled in the Service Requester and Service Provider do not have to be the same. The only requirement is that all of the status information must be passed in the SOAP message header. It is also required that the SOAP fault codes will also be passed in the same manner as the 1EdTech Enterprise Services status code information.

7.4 Architectural Considerations

7.4.1 Information Synchronization

The 1EdTech Enterprise Service bindings provide mechanisms through which the synchronization of data transfers can be maintained. These mechanisms are:

• Synchronous and asynchronous communications - two different message choreographies are available. The synchronous binding requires the Service Requester to wait for the response from the Service Provider whereas the asynchronous binding allows many service requests to be issued and outstanding;
• Message identifiers - all of the SOAP messages have unique message identifiers. The status information in the response message includes the message identifier of the original request message;
• Sourced identifiers - every data object is allocated a unique identifier. This identifier must be unique in the context of the two systems that access the object i.e., the identifiers do not have to be globally unique. The end systems are responsible for maintaining the integrity of these identifiers.

7.4.2 Push and Pull Transactions

The Enterprise Services are defined in such a way that any system can be either a Service Requester or Service provider or both. Data can be pushed or pulled depending on how the 1EdTech Enterprise Services are used. Pushed data requires the source to issue 'create', createByProxy', 'delete', 'write' and 'replace' operations. Pulled data requires the source to issue 'read' operations.

7.4.3 'Snapshot' and Event Driven Transactions

The 1EdTech Enterprise team's consensus is that the most robust and easily implemented interface would involve the passing of a complete 'snapshot' of the Person, Group, and Group Membership data. The target system would examine this snapshot to determine what changes had occurred. This very basic type of interface allows a receiving system to pick up an interface at any time and synchronize its data with the source system - regardless of how many interfaces had been passed in the interim. A purely event driven 'transactional' interface, on the other hand, cannot tolerate any loss or skipping of interface records. The snapshot approach requires the usage of the iterated operations in the three services.

This basic interface also allows the target system to implement many different strategies for dealing with the interface data. Taking a "snapshot" means that the full set of relevant data from the source system can be moved to the target system environment on any timing needed to support the business processes. This interface architecture has the advantage of being very tolerant of lost messages or missed data objects because the next transmittal will always get the target system back in synchronization with the source system. However, the major drawback is that the target system can never be sure that the data has not changed in the source system since the last snapshot was received. Also, this interface architecture does not effectively support two-way interfaces. In a two-way interface, data object maintenance occurs in both systems, and the data objects are passed in both directions.

In an event driven interface, the source system publishes data object messages when events occur. This changes the relevant data, and the target system receives and processes the event transactions. The existence of an event driven interface does not eliminate the usefulness of the "snapshot" interface. Because an event driven interface is not tolerant of missed transactions, the "snapshot" interface can be used at regular intervals to "re-synchronize" the data in the target system with that in the source system. This increases the fault tolerance of the overall interface architecture.

7.4.4 Common Services and Service Choreography

The interaction of the services with each other and with common services is outside the scope of this specification. However, there are recommendations on how these interactions should be managed in the context of the Enterprise Services:

• Authorization, authentication and other similar information should be passed in the SOAP headers. The SOAP headers can be extended using the W3C recommendations;
• The WS-I Basic Profile 1.0 defines the usage of UDDI 2.0 for service discovery etc. At the current time there is little experience in the usage of UDDI but this approach should be considered in any implementation.

7.5 Synchronous and Asynchronous Communications

The information models are created agnostic of the communications infrastructure choreography. Synchronous and asynchronous bindings of the 1EdTech Enterprise Services have been developed and the key differences from an implementation perspective are:

• The synchronous binding has the simple request/response message choreography whereas the asynchronous binding has request/acknowledge and response/acknowledge message exchanges. The co-ordination between the two message sets is implementation dependent;
• For the synchronous binding the service requester is blocked until the response message has been received. It is still important to verify that the response message is correctly matched to the request message (use the 'messageIdentifier' and 'messageRefIdentifier' structures in the SOAP message headers) because the underlying communications infrastructure may result in unexpected behavior. In the asynchronous binding the service requester is only blocked until the initial acknowledgement message is received from the service provider;
• For the asynchronous binding the service requester must either poll the communications handler for data reception or the communications handler must announce the arrival of data for the service requester. The mechanism adopted is implementation dependent.

For both the synchronous and asynchronous bindings it is assumed that the end-to-end communications is error-free, there is no message re-ordering and no message duplication (the correct usage of the message identifiers in the SOAP headers will protect against some of these problems). In the binding there is no provision of reliable messaging but this will be investigated for adoption once the W3C has completed its work in this area.

7.6 Using the Person Data Model

7.6.1 Changes from Enterprise Specification v1.1

The changes from the <person> structure in the Enterprise Specification v1.1 are:

• There are no XSD attributes used in the I-PMS. All of the attributes have been replaced by elements (this is to avoid the occurrence of attributes in SOAP messages) and when appropriate the content of the element has been constrained using an enumerated list;
• In the I-PMS binding a 'camel case' naming convention has been adopted. In the Enterprise Specification v1.1 the naming convention was lower case;
• In the I-PMS there are no mandatory children of the <person> element. This is because the 'Create/Read/Update/Delete' approach only needs the data required for the operation e.g., an update of the name does not need any other non-name data;
• The 'recstatsus' attribute in Enterprise Specification v1.1 has been removed. This is now replaced by the service operation definitions;
• The <comments> element, in the Enterprise Specification v1.1, has been replaced by the <recordInfo> element;
• The <sourcedId> element in Enterprise Specification v1.1 has been removed. This information is now passed as a parameter in the request/response messages i.e., it is passed in the SOAP message but not as part of the <person> data model;
• The <sort>, <nickname>, <family>, <given>, <other>, <prefix> and <suffix> elements in the in Enterprise Specification v1.1 have been removed from the <name> element. These have been redundant by the usage of the <partname> element;
• Within the I-PMS some elements are name-spaced entries from a common definitions. These elements are <esx:dataSource>, <esx:email> and <esx:url>;
• In the I-PMS the structure of the <extension> element has been changed. Within the data model, extensions must use the defined layout template. This change was made to ensure that the Service Provider will always be able to unmarshal the received SOAP message;
• Whenever possible data-types in the I-PMS have been used. In some cases in the Enterprise Specification the string data-type was used to contain values that could have been defined as Boolean, etc. Whenever the string data-type has been used an effort has been made to constrain its length in the binding as defined in the information model. The Enterprise Specification v1.1. DTD binding did not constrain the lengths of the strings.

7.6.2 Considerations for Each Operation

Some useful notes to consider when implementing each operation as a Service Provider are:

• CreatePerson - it is possible to create an object that is empty i.e., a 'sourcedId' has been allocated, the base record structure space is reserved but no content is added at the time of creation. The reception of an empty data structure from the Service Requester should not result in the reporting of an error status code;
• CreateByProxyPerson - as per the 'CreatePerson' operation, it is possible to create an object that is empty i.e., a 'sourcedId' is allocated, and the base record structure space reserved but no content is added at the time of creation. The reception of an empty data structure from the Service Requester should not result in the reporting of an error status code;
• DeletePerson - it is implementation dependent as to whether the object is actually destroyed or merely marked as deleted in the server database. It is recommended that no object is destroyed due to the delete request;
• ReadPerson - if the data record is empty then it must still be returned and the success status code reported. The Service provider must return all of the data it stores for the object;
• UpdatePerson - this is an additive operation but the actions on each data structure are determined by the multiplicity defined in the information model i.e., an update for a data structure that has multiplicity of '0' or '1' is equivalent to replacing that structure. The Service Provider should complete as much of the change as possible e.g., if some data is supplied that cannot be stored then this should not result in the complete rejection/failure of the request;
• ReplacePerson - this results in the original data for the identified object being deleted and replaced by this new information. All of the established membership relationships are still maintained because the 'sourcedId' for the Person has not changed. The Service Provider should complete as much of the change as possible e.g., if some data is supplied that cannot be stored then this should not result in the complete rejection/failure of the request;
• ChangePersonIdentifier - the successful completion of this request requires that all of the associated membership records must be changed to use the new 'sourcedId';
• CreatePersons - look at the notes for the 'CreatePerson' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• CreateByProxyPersons - look at the notes for the 'CreateByProxyPerson' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• DeletePersons - look at the notes for the 'DeletePerson' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• ReadPersons - look at the notes for the 'ReadPerson' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• ReadPersonsForGroup - the Service Provider must return all of the Person records it locates that are members of the defined Group;
• UpdatePersons - look at the notes for the 'UpdatePerson' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• ReplacePersons - look at the notes for the 'ReplacePerson' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• ChangePersonsIdentifier - look at the notes for the 'ChangePersonIdentifier' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction.

Some useful notes to consider when implementing each operation as a Service Requester are:

• CreatePerson - the specification makes no recommendations as to what the Service Requester should do if the create request is rejected by the Service Provider. The nature of the rejection will determine the recovery approach e.g., if the new 'sourcedId' has already been allocated in the Service Provider then a change of sourcedId may result in success;
• CreateByProxyPerson - the specification makes no recommendations as to what the Service Requester should do if the 'sourcedId' allocated by the Service Provider has already been allocated to another object in the Service Requester. Consistency suggests that the object in the Service Provider should either be deleted, and then perhaps recreated, or have its 'sourcedId' changed;
• DeletePerson - it is recommended that the local version of the object not be deleted until confirmation has been received that the Service Provider has successfully completed the deletion request. This avoids the two systems becoming inconsistent;
• ReadPerson - the Service Provider can return an empty data record (see the notes for CreatePerson from the perspective of the Service Provider). The Service Provider may return more information than can be handed by the Service Requester. The Service Requester should supply as much of this data as possible to the invoking application;
• UpdatePerson - the specification makes no recommendations as to what the Service Requester should do if the request is rejected. Some remedial action is required otherwise the system will remain in an inconsistent state;
• ReplacePerson - the specification makes no recommendations as to what the Service Requester should do if the request is rejected. Some remedial action is required otherwise the system will remain in an inconsistent state;
• ChangePersonIdentifier - look at the notes for the 'CreateByProxyPerson' operation. The set of status reports in the SOAP message header must be matched to the 'sourcedId's returned in the SOAP message body by the Service Provider and the original individual create requests. A status error code for a transaction will mean that there is no corresponding 'sourcedId' in the SOAP message body;
• CreatePersons - look at the notes for the 'CreatePerson' operation. The set of status reports in the SOAP message header must be matched to the individual create requests;
• CreateByProxyPersons - look at the notes for the 'CreateByProxyPerson' operation. The set of status reports in the SOAP message header must be matched to the 'sourced's returned in the SOAP message body by the Service Provider and the original individual create requests. A status error code for a transaction will mean that there is no corresponding 'sourcedId' in the SOAP message body;
• DeletePersons - look at the notes for the 'DeletePerson' operation. The set of status reports in the SOAP message header must be matched to the individual delete requests;
• ReadPersons - look at the notes for the 'ReadPerson' operation. The set of status reports in the SOAP message header must be matched to the data returned in the SOAP message body by the Service Provider and the original individual read requests. A status error code for a transaction will mean that there is no corresponding person record in the SOAP message body;
• ReadPersonsForGroup - the Service Provider does not report the number of Person records supplied. Instead it just supplies the records themselves. There is a single status report for this operation;
• UpdatePersons - look at the notes for the 'UpdatePerson' operation. The set of status reports in the SOAP message header must be matched to the individual update requests;
• ReplacePersons - look at the notes for the 'ReplacePerson' operation. The set of status reports in the SOAP message header must be matched to the individual replace requests;
• ChangePersonsIdentifier - look at the notes for the 'ChangePersonIdentifier' operation. The set of status reports in the SOAP message header must be matched to the individual change requests.

7.7 Using the Group Data Model

7.7.1 Changes from Enterprise Specification v1.1

The changes from the <group> structure in the Enterprise Specification v1.1 are:

• There are no XSD attributes used in the I-GMS. All of the attributes have been replaced by elements (this is to avoid the occurrence of attributes in SOAP messages) and when appropriate the content of the element has been constrained using an enumerated list;
• In the I-GMS binding a 'camel case' naming convention has been adopted. In the Enterprise Specification v1.1 the naming convention was lower case;
• In the I-GMS there are no mandatory children of the <person> element. This is because the 'Create/Read/Update/Delete' approach only needs the data required for the operation e.g., an update of the name does not need any other non-name data;
• The 'recstatsus' attribute in Enterprise Specification v1.1 has been removed. This is now replaced by the service operation definitions;
• The <comments> element, in the Enterprise Specification v1.1, has been replaced by the <recordInfo> element;
• The <sourcedId > element in Enterprise Specification v1.1 has been removed as a direct child of the <group> element. This information is now passed as a parameter in the request/response messages i.e., it is passed in the SOAP message but not as part of the <person> data model;
• Within the I-GMS some elements are name-spaced entries from a common definitions. These elements are <esx:dataSource>, <esx:email> and <esx:url>;
• In the I-GMS the structure of the <extension> element has been changed. Within the data model, extensions must use the defined layout template. This change was made to ensure that the Service Provider will always be able to unmarshal the received SOAP message;
• Whenever possible data-types in the I-GMS have been used. In some cases in the Enterprise Specification the string data-type was used to contain values that could have been defined as Boolean, etc. Whenever the string data-type has been used an effort has been made to constrain its length in the binding as defined in the information model. The Enterprise Specification v1.1. DTD binding did not constrain the lengths of the strings.

7.7.2 Considerations for Each Operation

Some useful notes to consider when implementing each operation as a Service Provider are:

• CreateGroup - it is possible to create an object that is empty i.e., a 'sourcedId' has been allocated, the base record structure space is reserved but no content is added at the time of creation. The reception of an empty data structure from the Service Requester should not result in the reporting of an error status code;
• CreateByProxyGroup - as per the 'CreateGroup' operation, it is possible to create an object that is empty i.e., a 'sourcedId' is allocated, and the base record structure space reserved but no content is added at the time of creation. The reception of an empty data structure from the Service Requester should not result in the reporting of an error status code;
• DeleteGroup - it is implementation dependent as to whether the object is actually destroyed or merely marked as deleted in the server database. It is recommended that no object be destroyed due to the delete request. The deletion of a group requires that all of the child sub-groups are also deleted and the associated membership records of the Group are deleted;
• ReadGroup - if the data record is empty then it must still be returned and the success status code reported. The Service provider must return all of the data it stores for the object. Only the record of the identified group is returned i.e., information about related groups requires further read requests using the appropriate 'sourcedId';
• UpdateGroup - this is an additive operation but the actions on each data structure are determined by the multiplicity defined in the information model i.e., an update for a data structure that has multiplicity of '0' or '1' is equivalent to replacing that structure. The Service Provider should complete as much of the change as possible e.g., if some data is supplied that cannot be stored then this should not result in the complete rejection/failure of the request;
• ReplaceGroup - this results in the original data for the identified object being deleted and replaced by this new information. All of the established membership relationships are still maintained because the 'sourcedId' for the Group has not changed. All of the child sub-groups are deleted. The Service Provider should complete as much of the change as possible e.g., if some data is supplied that cannot be stored then this should not result in the complete rejection/failure of the request;
• ChangeGroupIdentifier - the successful completion of this request requires that all of the associated membership records must be changed to use the new 'sourcedId';
• CreateGroups - look at the notes for the 'CreateGroup' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• CreateByProxyGroups - look at the notes for the 'CreateByProxyGroup' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• DeleteGroups - look at the notes for the 'DeleteGroup' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• ReadGroups - look at the notes for the 'ReadGroup' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• ReadGroupsForPerson - the Service Provider must return all of the Group records it locates that are members of the defined Person;
• UpdateGroups - look at the notes for the 'UpdateGroup' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• ReplaceGroups - look at the notes for the 'ReplaceGroup' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• ChangeGroupsIdentifier - look at the notes for the 'ChangeGroupIdentifier' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction.

Some useful notes to consider when implementing each operation as a Service Requester are:

• CreateGroup - the specification makes no recommendations as to what the Service Requester should do if the create request is rejected by the Service Provider. The nature of the rejection will determine the recovery approach e.g., if the new 'sourcedId' has already been allocated in the Service Provider then a change of sourcedId may result in success;
• CreateByProxyGroup - the specification makes no recommendations as to what the Service Requester should do if the 'sourcedId' allocated by the Service Provider has already been allocated to another object in the Service Requester. Consistency suggests that the object in the Service Provider should either be deleted, and then perhaps recreated, or have its 'sourcedId' changed;
• DeleteGroup - it is recommended that the local version of the object not be deleted until confirmation has been received that the Service Provider has successfully completed the deletion request. This avoids the two systems becoming inconsistent;
• ReadGroup - the Service Provider can return an empty data record (see the notes for CreateGroup from the perspective of the Service Provider). The Service Provider may return more information than can be handed by the Service Requester. The Service Requester should supply as much of this data as possible to the invoking application;
• UpdateGroup - the specification makes no recommendations as to what the Service Requester should do if the request is rejected. Some remedial action is required otherwise the system will remain in an inconsistent state;
• ReplaceGroup - the specification makes no recommendations as to what the Service Requester should do if the request is rejected. Some remedial action is required otherwise the system will remain in an inconsistent state;
• ChangeGroupIdentifier - the specification makes no recommendations as to what the Service Requester should do if the request is rejected because the new 'sourcedId' has already been allocated to another object in the Service Provider or if the original object cannot be identified in the Service Provider;
• CreateGroups - look at the notes for the 'CreateGroup' operation. The set of status reports in the SOAP message header must be matched to the individual create requests;
• CreateByProxyGroups - look at the notes for the 'CreateByProxyGroup' operation. The set of status reports in the SOAP message header must be matched to the 'sourcedId's returned in the SOAP message body by the Service Provider and the original individual create requests. A status error code for a transaction will mean that there is no corresponding 'sourcedId' in the SOAP message body;
• DeleteGroups - look at the notes for the 'DeleteGroup' operation. The set of status reports in the SOAP message header must be matched to the individual delete requests;
• ReadGroups - look at the notes for the 'ReadGroup' operation. The set of status reports in the SOAP message header must be matched to the data returned in the SOAP message body by the Service Provider and the original individual read requests. A status error code for a transaction will mean that there is no corresponding person record in the SOAP message body;
• ReadGroupsForPerson - the Service Provider does not report the number of Group records supplied. Instead it just supplies the records themselves. There is a single status report for this operation;
• UpdateGroups - look at the notes for the 'UpdateGroup' operation. The set of status reports in the SOAP message header must be matched to the individual update requests;
• ReplaceGroups - look at the notes for the 'ReplaceGroup' operation. The set of status reports in the SOAP message header must be matched to the individual replace requests;
• ChangeGroupsIdentifier - look at the notes for the 'ChangeGroupIdentifier' operation. The set of status reports in the SOAP message header must be matched to the individual change requests.

7.7.2 Groups and Sub-groups

The Group structure is used as a generic collection structure for objects that have a similar functionality, responsibility, etc. It can be a Group of other Groups or a Group of Person records. Sub-groups are defined by creating a relationship between Group and another and by establishing the relationship as either 'Parent' or 'Child'.

The relationship between two Groups is defined using the <relationship> element. This allows the definition of uni-directional and bi-directional references depending on the desired implementation. The sub-group hierarchy is defined using the '1=Parent' and '2=Child' values in the <relation> attribute of the <relationship> element. This tree structure can be defined to have any number of roots and the equivalence of Groups can be defined using the '3-Cross Listing' value for <relation>.

7.7.3 Cross-listed Course Sections

Cross-Listed course sections are a fairly common scenario in higher education. A Cross-Listed course section refers to a situation where the same course is offered under more than one name. This is typically done because different groups of students will enroll in different sections based on the program they are studying. For example, Statistics 101 section 1 and Psychology 101 section 1 are really the same course section, offered by the same instructor, meeting at the same time and place (physical or virtual), using the same course materials. The only difference is that Math students enroll in Statistics 101, and Psychology students enroll in Psychology 101. A problem arises in this situation when the Enterprise system treats these sections as separate groups. In the Learning Management System, they need to be treated as a single group, or at least the LMS needs to know they are related.

One approach is to resolve this in the source system before passing Groups and Memberships over to the target system. In other words, a single group (perhaps called "Introductory Statistics", without the Math or Psychology designator) would be created in the Learning Management System and membership from both groups in the Enterprise system would be passed to this single group in the LMS. Another approach is to pass two separate groups to the target system, but relate them to each other through the use of the Relationship element. In this case, the two groups could be tagged as follows in the Relationship element:

• Sourced ID - The ID of the cross-listed course section in the source system;
• Label - Would contain something like 'Cross Listed Section';
• Relation - Would contain "3" (also known as).

In general, the best practice would be to resolve the issue in the source system, before passing the group and membership data to the target system, but there may be cases where the second approach is required.

7.8 Using the Membership Data Model

The changes from the <membership> structure in the Enterprise Specification v1.1 are:

• There are no XSD attributes used in the I-MMS. All of the attributes have been replaced by elements (this is to avoid the occurrence of attributes in SOAP messages) and when appropriate the content of the element has been constrained using an enumerated list;
• In the I-MMS binding a 'camel case' naming convention has been adopted. In the Enterprise Specification v1.1 the naming convention was lower case;
• In the I-MMS there are no mandatory children of the <person> element. This is because the 'Create/Read/Update/Delete' approach only needs the data required for the operation e.g., an update of the name does not need any other non-name data;
• In the I-MMS the <membership> element can only contain one <member> record but this may contain more than one <role> record;
• In the I-MMS each Membership record is allocated its own 'sourcedId'. All operations on the Membership record must use this 'sourcedId'. In the Enterprise Specification v1.1 a Membership record was referenced using the 'sourcedid's of the appropriate Member and Group;
• The 'recstatsus' attribute in Enterprise Specification v1.1 has been removed. This is now replaced by the service operation definitions;
• The <comments> element, in the Enterprise Specification v1.1, has been replaced by the <recordInfo> element;
• The <sourcedId> element in Enterprise Specification v1.1 has been removed. This information is now passed as a parameter in the request/response messages i.e., it is passed in the SOAP message but not as part of the <person> data model;
• Within the I-MMS some elements are name-spaced entries from a common definitions. These elements are <esx:dataSource> and <esx:email>;
• In the I-MMS the structure of the <extension> element has been changed. Within the data model, extensions must use the defined layout template. This change was made to ensure that the Service Provider will always be able to unmarshal the received SOAP message;
• Whenever possible data-types in the I-MMS have been used. In some cases in the Enterprise Specification the string data-type was used to contain values that could have been defined as Boolean, etc. Whenever the string data-type has been used an effort has been made to constrain its length in the binding as defined in the information model. The Enterprise Specification v1.1. DTD binding did not constrain the lengths of the strings.

7.8.1 Considerations for Each Operation

Some useful notes to consider when implementing each operation as a Service Provider are:

• CreateMembership - it is possible to create an object that is empty i.e., a 'sourcedId' has been allocated, the base record structure space is reserved but no content is added at the time of creation. The reception of an empty data structure from the Service Requester should not result in the reporting of an error status code;
• CreateByProxyMembership - as per the 'CreatePerson' operation, it is possible to create an object that is empty i.e., a 'sourcedId' is allocated, and the base record structure space reserved but no content is added at the time of creation. The reception of an empty data structure from the Service Requester should not result in the reporting of an error status code;
• DeleteMembership - it is implementation dependent as to whether the object is actually destroyed or merely marked as deleted in the server database. It is recommended that no object is destroyed due to the delete request. Only the membership record is deleted;
• ReadMembership - if the data record is empty then it must still be returned and the success status code reported. The Service provider must return all of the data it stores for the object. Only the Membership record is returned;
• UpdateMembership - this is an additive operation but the actions on each data structure are determined by the multiplicity defined in the information model i.e., an update for a data structure that has multiplicity of '0' or '1' is equivalent to replacing that structure. The Service Provider should complete as much of the change as possible e.g., if some data is supplied that cannot be stored then this should not result in the complete rejection/failure of the request;
• ReplaceMembership - this results in the original data for the identified object being deleted and replaced by this new information. All of the established membership relationships are still maintained because the 'sourcedId' for the Person has not changed. The Service Provider should complete as much of the change as possible e.g., if some data is supplied that cannot be stored then this should not result in the complete rejection/failure of the request;
• ChangeMembershipIdentifier - the successful completion of this request requires that all of the associated membership records must be changed to use the new 'sourcedId';
• CreateMemberships - look at the notes for the 'CreateMembership' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• CreateByProxyMemberships - look at the notes for the 'CreateByProxyMembership' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• DeleteMemberships - look at the notes for the 'DeleteMembership' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• ReadMemberships - look at the notes for the 'ReadMembership' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• ReadMembershipsForGroup - the Service Provider must return all of the Membership records it locates that are members of the defined Group;
• ReadMembershipsForPerson - the Service Provider must return all of the Membership records it locates that are members of the defined Person;
• UpdateMemberships - look at the notes for the 'UpdateMembership' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• ReplaceMemberships - look at the notes for the 'ReplaceMembership' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction;
• ChangeMembershipsIdentifier - look at the notes for the 'ChangeMembershipIdentifier' operation. A status report must be supplied for every transaction in the request otherwise the Service Requester may not be able to accurately determine the status of any transaction.

Some useful notes to consider when implementing each operation as a Service Requester are:

• CreateMembership - the specification makes no recommendations as to what the Service Requester should do if the create request is rejected by the Service Provider. The nature of the rejection will determine the recovery approach e.g., if the new 'sourcedId' has already been allocated in the Service Provider then a change of sourcedId may result in success;
• CreateByProxyMembership - the specification makes no recommendations as to what the Service Requester should do if the 'sourcedId' allocated by the Service Provider has already been allocated to another object in the Service Requester. Consistency suggests that the object in the Service Provider should either be deleted, and then perhaps recreated, or have its 'sourcedId' changed;
• DeleteMembership - it is recommended that the local version of the object not be deleted until confirmation has been received that the Service Provider has successfully completed the deletion request. This avoids the two systems becoming inconsistent;
• ReadMembership - the Service Provider can return an empty data record (see the notes for CreateMembership from the perspective of the Service Provider). The Service Provider may return more information than can be handed by the Service Requester. The Service Requester should supply as much of this data as possible to the invoking application;
• UpdateMembership - the specification makes no recommendations as to what the Service Requester should do if the request is rejected. Some remedial action is required otherwise the system will remain in an inconsistent state;
• ReplaceMembership - the specification makes no recommendations as to what the Service Requester should do if the request is rejected. Some remedial action is required otherwise the system will remain in an inconsistent state;
• ChangeMembershipIdentifier - the specification makes no recommendations as to what the Service Requester should do if the request is rejected because the new 'sourcedId' has already been allocated to another object in the Service Provider or if the original object cannot be identified in the Service Provider;
• CreateMemberships - look at the notes for the 'CreateMembership' operation. The set of status reports in the SOAP message header must be matched to the individual create requests;
• CreateByProxyMemberships - look at the notes for the 'CreateByProxyMembership' operation. The set of status reports in the SOAP message header must be matched to the 'sourcedId's returned in the SOAP message body by the Service Provider and the original individual create requests. A status error code for a transaction will mean that there is no corresponding 'sourcedId' in the SOAP message body;
• DeleteMemberships - look at the notes for the 'DeleteMembership' operation. The set of status reports in the SOAP message header must be matched to the individual delete requests;
• ReadMemberships - look at the notes for the 'ReadMembership' operation. The set of status reports in the SOAP message header must be matched to the data returned in the SOAP message body by the Service Provider and the original individual read requests. A status error code for a transaction will mean that there is no corresponding person record in the SOAP message body;
• ReadMembershipsForGroup - the Service Provider does not report the number of Membership records supplied. Instead it just supplies the records themselves. There is a single status report for this operation;
• ReadMembershipsForPerson - the Service Provider does not report the number of Membership records supplied. Instead it just supplies the records themselves. There is a single status report for this operation;
• UpdateMemberships - look at the notes for the 'UpdateMembership' operation. The set of status reports in the SOAP message header must be matched to the individual update requests;
• ReplaceMemberships - look at the notes for the 'ReplaceMembership' operation. The set of status reports in the SOAP message header must be matched to the individual replace requests;
• ChangeMembershipsIdentifier - look at the notes for the 'ChangeMembershipIdentifier' operation. The set of status reports in the SOAP message header must be matched to the individual change requests.

7.8.2 Assigning Group Membership Role-type

Roletype is a data structure in the Group Membership object that has a defined set of domain values. This means that only those values defined in the domain can be used for this element. Recognizing that no defined list of roles can ever be absolutely complete; the optional element <subrole> can be used to further qualify a person's role in a group. It is essential to have a defined list of values for the mandatory <roletype> element so source systems can generate standard Group Membership data objects that target systems can process without having to first negotiate the meaning of role-types with the source system. To help developers understand what meaning is embedded in each of the role-type values, the Table 7.1 shows the LMS functions to which each <roletype> will typically have access. This is not intended to be a precise and exclusive list of all functions that these roles will have access to in all LMSs. Rather, it is provided as an interpretive guide intended to communicate the meaning the developers of the specification had in mind for each role. In addition, access to these functions will be less for some sub-roles. For example, a supervisor may be a sub-role for a manager, and a supervisor will likely not have access to results for the people they supervise.

The key is: X=Available, R=Read, M=Main, S=Some, T=Theirs.

In any particular implementation or in any specific vendor's product, the Instructor role and the Administrator role will frequently have several sub-roles.

In later versions of the 1EdTech Enterprise Service we will be revisiting the ways in which the role-type is defined and referenced. The changes will look at using a vocabulary that will be supported using the 1EdTech VDEX specification [VDEX, 04]. The current method is maintained for compatibility as this was used in the 1EdTech Enterprise Specification v1.1.

7.9 1EdTech Harmonization

The 1EdTech Enterprise specification is complemented by the 1EdTech LIP specification [LIP, 01a], [LIP, 01b], [LIP, 01c]. There is some confusion about when and where the two specifications should be used and so the following recommendations are made:

• Information that is limited to a small sub-set of the full personal details of an individual and to be used to populate an LMS for learning activities should be exchanged using the 1EdTech Person Management Service. The exception is personal information required to support computer-based accessibility that should be exchanged using the 1EdTech LIP <accessibility> data object;
• Information about Group activities, groups of people and membership information should be exchanged using the 1EdTech Group Management Services and 1EdTech Membership Management Services specifications;
• Information about a single individual, particularly when focused on their life-long learning log/profile, should be exchanged using the 1EdTech LIP specification e.g., their set of examination results.

There may be some confusion between the 1EdTech Enterprise, 1EdTech LIP and the 1EdTech Question & Test Interoperability (QTI) Results Reporting specifications with respect to exchanging assessment results. The following recommendations are made:

• Information from an Assessment Engine reporting the set of results for a single individual or group of people should be reported to another Assessment Engine or within the Assessment System using the 1EdTech QTI specification;
• Personal results being reported from an Assessment System to a Profiles System should be exchanged using the 1EdTech LIP;
• Personal and group results being reported from and LMS to an Enterprise System should be reported using the 1EdTech Membership Management Services.

8. Supporting the Use Cases

8.1 Person Management Service Use Cases

The manner in which the original ES Use Cases of the Person Management Service [EntServices, 04a] are supported is shown in Table 8.1.

8.2 Group Management Service Use Cases

The manner in which the original ES Use Cases of the Group Management Service [EntServices, 04a] are supported is shown in Table 8.2.

8.3 Membership Management Service Use Cases

The manner in which the original ES Use Cases of the Membership Management Service [EntServices, 04a] are supported is shown in Table 8.3.

9. Extending the Services

9.1 Proprietary Extensions to the Enterprise Services

9.1.1 Extensions to the Data Models

Extensions in a data model must use the 1EdTech Extension class. As an example consider an extension to the Person model in which the color of the person's eyes and hair is to be stored:

0001

0002

0003

0004

0005

0006

0007

0008

0009

0010

0011

0012

0013

0014

0015

0016

0017

0018

0019

0020

0021

0022

0023

0024

0025

0026

0027

0028

0029

0030

0031

0032

0033

0034

0035

POST /PersonManagementService HTTP/1.1

Host: www.personmanagementserver.com

Content-Type: text/xml; charset="utf-8"

Content-Length: nnnn

SOAPAction: "http://www.imsglobal.org/soap/pms/createPerson"



<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

   <SOAP-ENV:Header>

      <h:syncRequestHeaderInfo xmlns:h="../imsMessBindSchemav1p0.xsd">

         <h:messageIdentifier>AB12345e4t6789</h:messageIdentifier>

      </h:syncRequestHeaderInfo>

   </SOAP-ENV:Header>

   <SOAP-ENV:Body>

      <m:createPersonRequest xmlns:m="../imsPersonManMessSchemav1p0.xsd">

         <m:sourcedId>

            <esx:identifier>oldsource:oldidentifier</esx:identifier>

         </m:sourcedId>

         <m:person>

            <esx:email xmlns:esx = "http://...">hello</esx:email>

            <per:extension xmlns:per = "http://...">

               <esx:extensionField xmlns:esx = "http://...">

                  <esx:fieldName>eyeColour</esx:fieldName>

                  <esx:fieldType>String</esx:fieldType>

                  <esx:fieldValue>Blue</esx:fieldValue>

               </esx:extensionField>

               <esx:extensionField xmlns:esx = "http://...">

                  <esx:fieldName>hairColour</esx:fieldName>

                  <esx:fieldType>String</esx:fieldType>

                  <esx:fieldValue>Black</esx:fieldValue>

               </esx:extensionField>

            </per:extension>

         </m:person>

      </m:createPersonRequest>

   </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

The extensions are shown in lines 20-31. The points to note are:

• There is no requirement to define any new XSD structures;
• There is no hierarchical structure of the extensions. The extension structure must be expressed as a flat list;
• Any conditional relationship between the sub-elements are not validated by the parser e.g., if the <fieldType> was an enumerated list then the parser will not ensure that the <fieldValue> is an entry from that list.

9.1.2 Extensions to the Behaviors

The addition of proprietary behaviors should still maintain the format of the established behaviors. An example is shown in Figure 9.1 in which two new behaviors are defined (these use the current set of data classes). When new proprietary behaviors are added it is recommended that:

• A new interface type is declared and this has a unique name that indicates it is an extension;
• Each new behavior should have a unique name. All of the behaviors must return a status object either in the form of 'StatusInfo' or 'StatusInfoSet';
• Any new data classes should also be described. These new classes should be given their own namespace and linked, where appropriate, to the current XSDs;
• The corresponding new WSDL files must be created (these will extend but replace the original WSDL files). Each new behavior requires the appropriate message choreography (depending on the nature of the binding) and must use the established SOAP message header structures. The established transformation rules should be used [GWS, 04a], [GWS, 04b].

Note that a proprietary extension MUST NOT be defined to replace the behavior of an established operation. Instead it is permissible to add a new behavior that inherits its functionality form an established behavior.

9.2 Planned Extensions for the Enterprise Services

9.2.1 Potential New Behaviors for Established Services

There are three types of new behaviors that can be added to the current services, namely:

• Query behaviors - this is the capability to query the 'Service Provider' for objects that fit a search criteria e.g., list all Person objects that were changed since yesterday, etc. The query capability is to be added to all three of the current component Enterprise Services. 1EdTech is to develop an independent Query Service that will then be profiled for usage in the Person, Group and Membership Management services. The Query Service will not be available until May 2005 and so any new behaviors in the Enterprise Service will not be supplied until October 2005 at the earliest;
• Object management behaviors - this is the inclusion of more behaviors that support the low level management of the core objects. This could include the ability to delete all objects, read all objects, undelete an object, etc.;
• Business specific behaviors - new behaviors could be created to handle specific types of Person or Group e.g., create new student, create new course, etc. These behaviors would be based upon refinement and combination of some of the other behaviors for a service.

9.2.2 Potential New Services

In the original evaluation of the 1EdTech Enterprise v1.1 specification two new services were investigated for potential inclusion in V1.0 of the 1EdTech Enterprise Services specification. The two new services considered were:

• Grade-book Management Service - this is a considerable extension of the simple results reporting capability currently available in the membership Management Service. A separate service would enable the creation of a Grade-book Management capability that could be designed to be integrated with the 1EdTech Learner Information Package and the SIF Grade-book object;
• Course Catalog Management service - this is a development of a service capability to manage course catalogs, which themselves could consist of sub-catalogs etc. It is possible to provide a simplified capability using the Group Management Service but as yet there is no agreed approach for interoperability.

Other new business services could be added that reflect specific business operations. These new services could be based upon the combination of behaviors from the other services.

Appendix A - Glossary of Terms

Throughout the Enterprise Services specification 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].