1EdTech Enterprise Services Specification 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 Specification
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 Nomenclature
     1.4 References

2. Core Use Case Descriptions

3. Enterprise Service Description
     3.1 An Abstract Representation
     3.2 Enterprise Service Architecture Model
     3.3 Enterprise Services Domain Model

4. Person Management Service

5. Group Management Service

6. Membership Management Service

7. Extending the Enterprise Service
     7.1 Proprietary Extensions
     7.2 Further Work

About This Document
     List of Contributors

Revision History

Index

1. Introduction

1.1 Enterprise Services Overview

The Enterprise Services specification is the definition of how systems manage the exchange of information that describes people, groups 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 the concepts of:

• Interoperability - Enterprise Services focuses on the exchange of information between Enterprise systems. There are no assumptions in the specification 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 Specification v1.0 and as such it is used as the basis for the development of the following documents:

1. 1EdTech Enterprise Services Conformance Specification v1.0 [EntServices, 04b] - the definition of the conformance criteria that must be followed by systems that wish to claim compliance to the Enterprise Services Information model;
2. 1EdTech Enterprise Services with WSDL Binding Best Practices & Implementation Guide v1.0 [EntServices, 03c] - the recommended best practices to be adopted when implementing the Enterprise Services using a webs services binding;

The core uses cases for the Enterprise Services are described in [EntServices, 04a]. 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 specification is based upon the aggregation of the Person Management, Group Management and Membership Management Services specifications, namely:

1. 1EdTech Person Management Services Information Model v1.0 [PersonServices, 04a];
2. 1EdTech Person Management Services WSDL Binding v1.0 [PersonServices, 04b];
3. 1EdTech Group Management Services Information Model v1.0 [GroupServices, 04a];
4. 1EdTech Group Management Services WSDL Binding v1.0 [GroupServices, 04b];
5. 1EdTech Membership Management Services Information Model v1.0 [MemberServices, 04a];
6. 1EdTech Membership Management Services WSDL Binding v1.0 [MemberServices, 04b].

This information model defines the Enterprise Service Abstract Application Programming Interface (a-API). The original Enterprise specification was based upon the description of the data model for the information to be exchanged between communicating enterprise systems. The Enterprise Services specification extends this work by adding a series of behavioral models that define how the data models are to be manipulated. These behavioral models are described using UML and the syntax adopted for the description of the UML is given in the 1EdTech Specifications, Methods and Best Practices document [SpecDev, 03].

The Enterprise Services Specification v1.0 is to be implemented using a Web Services infrastructure based upon a SOAP/HTTP transport mechanism. These web service bindings are detailed in the corresponding service binding documents [PersonServices, 04b], [GroupServices, 04b], [MemberServices, 04b].

1.3 Nomenclature

1.4 References

2. Core Use Case Descriptions

The following use cases1 are the core subset adopted to represent key requirements for this version of the Enterprise Services (the full description for each of these use cases is given in [EntServices, 04a]):

• Person management service
  • Create person (Person01/01)
  • Read person (Person01/02)
  • Update person (Person01/03)
  • Delete person (Person01/04);
• Group management service
  • Create group (Group01/01)
  • Read group (Group01/02)
  • Update group (Group01/03)
  • Delete group (Group01/04)
  • Delete group relationship (Group01/05);
• Membership management service
  • Create membership (Membership01/01)
  • Read membership (Membership01/02)
  • Update membership (Membership01/03)
  • Delete membership (Membership01/04)
  • Read a person's memberships (Membership01/05)
  • Read a group's memberships (Membership01/06).

The Enterprise Services core use case description document [EntServices, 04a] contains many use cases that are not supported by the v1.0. Support for those use cases will be addressed in later versions.

3. Enterprise Service Description

3.1 An Abstract Representation

It is important to remember that this document is describing the underlying information model in terms of the abstract API. The manner in which this abstract representation is visualized is not intended to dictate the implementation form of an Enterprise System. The breakdown of the service into its component services and the further breakdown of each service into the interface classes used is a convenient way to document the set of behaviors. The internal organization of an implementation of the full abstract API is beyond the scope of this specification. The only constraint is that the external behavior of the abstract API complies with this specification. This means that a .NET, Java, etc. physical implementation of this abstract API does not have to represent the functionality using the same breakdown of operations/methods. This physical implementation is not subject to the conformance specification.

It is important to note that the UML representation of the interfaces is used to help develop and document the Enterprise Services information Model. 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 Enterprise Service Architecture Model

The basic abstract architectural model for the Enterprise Services specification is shown in Figure 3.1.

In this architecture the scope of the 1EdTech enterprise services specification is shown as the dotted line. The scope of the interoperability is the data and behavioural models of the objects being exchanged. Figure 3.1 is an abstract model showing the interfaces that are under specification (see the 1EdTech Abstract Framework [AbsWhite, 03]; it is not a representation of how an Enterprise System should be constructed. 1EdTech Service Package is the definition of the 1EdTech Enterprise Services resulting in a WSDL binding. The WSDL binding is then mapped onto a SOAP/http Infrastructure Layer.

The 1EdTech Enterprise Services specification contains a very simple abstract messaging model that is assumed to underlie the exchange of the data between the communicating Enterprise systems. The basic data exchange mechanism is shown in Figure 3.2 in which the 'source' and 'target' Enterprise systems exchange an 1EdTech Enterprise Services 'message' using a 'Request/Response' transaction. This abstract messaging representation is adopted because the Enterprise System architecture is based upon loosely coupled system and the primary 1EdTech binding of this information model is based upon the exchange of XML documents/messages.

It is important to remember that the structure of the exchanged information has NO bearing on how the same information is contained within the 'source' and 'target' Enterprise systems. It is simply an exchange interoperability representation of the data (the information that crosses the dotted line in Figure 3.2).

The behavioral descriptions will describe:

• The data that is to be exchanged between the communicating Enterprise Systems;
• The operations that can be invoked to support the exchange of the data between the communicating Enterprise Systems;
• The permitted sequence of operations that can be used to support the exchange of data between the communicating Enterprise Systems.

3.3 Enterprise Services Domain Model

A schematic representation of the core objects exchanged using the 1EdTech Enterprise Services specification is given in Figure 3.3. Only those services that are shown in grey are defined in this information model. 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. The group is a generic container used to define any set of related activities e.g., a tutor group, a class, a curriculum, etc. 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. This will not be defined as part of the V1.0 information model but may be included in later releases.

The underlying set of services used by the core enterprise services composition application services (as defined in the Abstract Framework):

• IAF common services - provision of services such as authentication authorization, etc. In the case of the Enterprise Services the core common services include the 'StatusInfo and 'Identifier';
• IAF infrastructure - provision of the end-to-end communications services.

An underlying assumption in a message-based system is that the sequence of messages will, in general, refer to the same objects at different moments in time e.g., the 'creation' of a Person, the 'updating' of a person and eventually the 'deletion' of the Person record. This means that the objects must have a unique identifier and that this address/label is unique between the communicating systems (an object may have more that one identifier even between the same two systems). The 1EdTech Enterprise specification calls these identifiers the 'sourcedId' of the object and it consists of a 'source' (globally unique across all the Enterprise systems) and an 'id' (unique within the source Enterprise system).

The usage of the 'sourcedid' for labelling the objects being exchanged gives rise to the scenario shown in Figure 3.4. The consequence of this approach is that any object will have multiple identifiers depending on which part of the system is being considered, i.e.:

• The 'sourcedid' is the exchange identifier and will be unique to a particular source system;
• The local identifier within the source system. This could be a database record number, etc. The source system must maintain the local identifier mapping table between the local identifier and the 'sourcedid';
• The local identifier within the target systems. In general the local identifier in each target system will be different. It is the responsibility of the target systems to maintain the local mapping table between the 'sourcedid' and their local identifier.

Within the Person management, Group Management and Membership management services the 'sourcedid' is defined as a flat string Identifier. For compatibility with the Enterprise v1.1 and earlier specifications the 'sourcedid' will be mapped onto the flat string as: 'source:id,' i.e., the colon (:) is used to delimit the 'source' and the 'id' within the flat string.

4. Person Management Service

The PersonManagementService class is used to model the service responsible for manipulating information about people. The PersonManagementService package is shown in Figure 4.1.

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

5. Group Management Service

The GroupManagementService class is used to model the service responsible for manipulating information about groups. The GroupManagementService class diagram is shown in Figure 5.1.

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

6. 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 MembershipManagementService class diagram is shown in Figure 6.1.

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

7. Extending the Enterprise Service

7.1 Proprietary Extensions

The proprietary extensions of the specification are based upon two approaches:

1. The extension of the data models being manipulated by the current set of operations;
2. The inclusion of new operations to support new proprietary functionality.

It is NOT permitted to change the behavior of the current set of operations. Such changes MUST be supported by the creation of new operations.

Proprietary extensions must make use of the extensions facilities in the respectively components services. Refer to the appropriate specification documentation for the full details.

7.2 Further Work

The Enterprise Services Specification and is based on the composition of other clearly defined and functionally discrete services. This means that the addition of new services and the extension of the established services can be supported without compatibility problems. The areas of work that will be addressed in new versions of the Enterprise Services are:

• Inclusion of the 'queryObject()' operation for each of the current and new services. This will enable each service to be queried to supply details of the objects that conform to the set of search criteria;
• Inclusion of operations that support direct manipulation of some of the sub-objects within the main services e.g., the ability to add/delete/read/change a name without recourse to the manipulation of the full Person object. The corresponding operations for all aggregated Enterprise Services will be considered;
• Inclusion of operations that support higher-level Enterprise Service business model requirements will be considered. Such requirements may require the definition of a set of Enterprise Services explicit because they require coordinated manipulation of more than one of the aggregated services, e.g., 'copyCourse' that creates a duplicate of the course and all its memberships;
• Inclusion of the Grade-book Management Service. This will enable Enterprise Services to management grade books. This work will look at the Grade-book specification available from SIF;
• Inclusion of the Course Catalog Management Service. This will enable Enterprise Services to management course catalogs for learning.

About This Document

List of Contributors

The following individuals contributed to the development of this document:

Revision History

Index

A
Abstract Framework 1, 2, 3, 4, 5
API 1, 2
Attributes
     Common
 

extension 1

sourcedId 1, 2, 3, 4      Membership
 

membership 1, 2, 3, 4, 5, 6      Org
 

id 1      Relationship
 

label 1      Result
 

result 1, 2, 3, 4, 5, 6, 7, 8      Role
 

status 1, 2, 3      StatusInfo
 

description 1, 2, 3      UserId
 

authentication 1

B
Binding technologies
     SOAP 1, 2
     WSDL 1, 2, 3, 4
 

C
Classes
     Common
 

Identifier 1, 2

StatusInfo 1      Group 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
 

Description 1, 2, 3, 4, 5, 6      Member 1, 2
     Membership 1, 2, 3, 4, 5, 6, 7
     Person 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
Conformance 1, 2, 3
 

E
Enterprise Service 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

G
Group Management Service 1, 2, 3, 4, 5

I
Interface Class
     GroupManager 1
     GroupsManager 1
     MembershipManager 1
     MembershipsManager 1
     PersonManager 1
     PersonsManager 1
 

M
Membership Management Service 1, 2, 3, 4

O
Operations
     Group
 

changeGroupIdentifier 1

changeGroupsIdentifier 1

createByProxyGroup 1

createByProxyGroups 1

createGroup 1

createGroups 1

deleteGroup 1

deleteGroupRelationship 1

deleteGroups 1

deleteGroupsRelationship 1

readGroup 1

readGroups 1

readGroupsForPerson 1

replaceGroup 1

replaceGroups 1

updateGroup 1

updateGroups 1      Membership
 

changeMembershipIdentifier 1

changeMembershipsIdentifier 1

createByProxyMembership 1

createByProxyMemberships 1

createMembership 1

createMemberships 1

deleteMembership 1

deleteMemberships 1

readMembership 1

readMemberships 1

readMembershipsForGroup 1

readMembershipsForPerson 1

replaceMembership 1

replaceMemberships 1

updateMembership 1

updateMemberships 1      Person
 

changePersonIdentifier 1

changePersonsIdentifier 1

createByProxyPerson 1

createByProxyPersons 1

createPerson 1

createPersons 1

deletePerson 1

deletePersons 1

readPerson 1

readPersons 1

readPersonsForGroup 1

replacePerson 1

replacePersons 1

updatePerson 1

updatePersons 1

P
Person Management Service 1, 2, 3, 4

S
Schools Interoperability Framework 1, 2
Services
     Group Management 1, 2, 3, 4, 5
     Membership Management 1, 2, 3, 4
     Person Management 1, 2, 3, 4
SOAP 1, 2
Specifications
     Other
 

Schools Interoperability Framework 1, 2

W
WDSL 1, 2, 3, 4