 |
1EdTech Enterprise Services Conformance 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 Conformance 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.
1. Introduction
1.1 Enterprise Services Overview
The Enterprise Services specification [EntServices, 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 Services, Group Services, and Membership Services;
- Component-based - the set of services will be supplied such that they can be combined to form a range of services. The Person Services, Group Services, and Membership 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 binding of immediate importance is 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 Conformance Specification v1.0 and it is based on the following documents:
- 1EdTech Enterprise Services Core Use Cases v1.0 [EntServices, 04a] - the set of use-cases that are the basis for the definition of the information model;
- 1EdTech Enterprise Services Specification v1.0 [EntServices, 04b] - the description of the overall Enterprise Services as created by the combination of the Person Management Services, Group Management Services, and Membership Management Services specifications;
- 1EdTech Person Management Services Information Model v1.0 [PersonService, 04];
- 1EdTech Group Management Services Information Model v1.0 [GroupService, 04];
- 1EdTech Member Management Services Information Model v1.0 [MemberService, 04].
As such the Enterprise Services specification supersedes the original Enterprise specifications:
- 1EdTech Enterprise Information Model Final Specification v1.1 [Enterprise, 02a].
- 1EdTech Enterprise XML Binding Final Specification v1.1 [Enterprise, 02b];
- 1EdTech Enterprise Services Best Practice and Implementation Guide Final Specification v1.0 [Enterprise, 02c].
This Conformance Specification defines the formal test specification for the 1EdTech Enterprise Service Information Model. This test specification is used to define the criteria by which an implementation can be evaluated to determine whether or not it complies with the Enterprise Services Information Model.
1.3 Structure of this Document
The structure of this document is:
1.4 Nomenclature
1.5 References
2. The Context for Enterprise Services Conformance
Conformance is based upon the following considerations:
- Nature of system - whether the system is a consumer, provider or combined supplied of the service;
- Level of compliance - the degree to which the system claims it conforms to the specification.
2.1 Nature of System
It is assumed that the behaviors defined by an abstract API are invoked by the exchange of messages between the 'Service Requester' and 'Service Provider'. The physical construction and manner in which these messages are physically exchanged is outside the scope of the relevant information models and thus this Conformance Specification.
2.1.1 Service Requester
A 'Service Requester' is defined as the system that issues the 'Request' message of a behavior and receives in return the corresponding 'Response' message. The normative responsibilities of a 'Service Requester' are:
- It must construct the appropriate 'Request' messages as defined by the binding definition being used to support the information model;
- It must be capable of reliably generating unique 'sourcedIds' that are to be assigned to the data objects;
- It must be capable of processing the corresponding 'Response' messages as defined by the binding definition to be used to support the information model. It is the binding document that is responsible for detailing how a 'Service Consumer' must maintain the atomic relationship of the Request/Response message sequence. From the perspective of this Conformance Specification it is assumed that the service implementation guarantees that duplicate 'Response' messages do not occur;
- It must report the returned status codes and comments to the process invoking the behavior.
2.1.2 Service Provider
A 'Service Provider' is defined as the system that receives the 'Request' message for a behavior and issues in return the corresponding 'Response' message. The 'Service Provider' is responsible for maintaining the persistence of the data throughout its lifetime. The normative responsibilities of a 'Service Provider' are:
- It must be capable of processing the set of 'Request' messages that can be received as defined by the binding definition being used to support the information model. Invalid data received within a 'Request message should not cause a failure of the 'Service Provider' and should not result in incorrect information being stored;
- It must accurately implement the processing behavior invoked by the request. The completion of this processing must result in the reporting of the appropriate status information;
- It must construct the appropriate 'Response' messages as defined by the binding definition being used to support the information model. It is the binding document that is responsible for detailing how a 'Service Requester' must maintain the atomic relationship of the Request/Response message sequence;
- It must be capable of reliably generating unique 'sourcedIds' that are to be assigned to the data objects;
- It must maintain the persistence of the data objects once they have been created until they are deleted. This persistence must ensure that the data object can be accessed using the unique 'sourcedId' allocated to it.
2.2 System Assumptions
From a system perspective the following points must be noted:
- The underlying communications system is reliable. This mans that there is no loss, duplication or corruption of messages;
- The underlying detailed message choreography for the binding is such that a logical 'Request/Response' model is supported. The conformance statements are define with respect to this logical 'Request/Response' model. For example, the detailed message choreography for the asynchronous/polled bindings is not address in the conformance statement. Instead only the invoking 'Request' and data containing 'Response' messages are considered because it is only these that are responsible for maintaining the corresponding system behavior;
- Mechanisms such as security, service discovery, etc. are outside the scope of the conformance specification. Interoperability of real systems will also have to address these issues.
3. Level of Compliance
3.1 Level 1 Compliance
3.1.1 Service Requester Compliance
This level of compliance means that the service cannot be invoked by the 'Service Requester', i.e., the corresponding API call is not available.
3.1.2 Service Provider Compliance
This level denotes that the service is not supported by the 'Service Provider'. However, the 'Service Provider' must be capable of responding to a service request that the service is unavailable. Upon receipt of the 'Request' message the 'Service Provider' must:
- Transmit the corresponding 'Response' message with a status code of 'Unsupported'. No other form of status information is supplied by the 'Provider';
- Return no data within the message body;
- Make no change to the internal record database.
3.2 Level 2 Compliance
3.2.1 Service Requester Compliance
This level denotes that the 'Service Requester' can invoke the defined behavior, using the 'Request' message and can process the corresponding 'Response' message from the 'Service Provider'. Upon receipt of the appropriate trigger the consumer must issue the 'Request' message such that:
- The 'Request' message is constructed such that it contains all of the required parameters, arranged appropriately in the message;
- The 'Request' message will only contain the data model elements that are mandatory.
Upon receipt of the corresponding 'Response' message the 'Service Requester' must:
- Process the corresponding 'Response' messages as defined by the binding definition to be used to support the information model;
- Be capable of parsing the received XML data against the corresponding XSD. Only the mandated elements are supported at this level;
- Pass the returned status codes back to the process responsible for invoking the behavior.
3.2.2 Service Provider Compliance
Upon receipt of the 'Request' message the 'Service Provider' must:
- Be capable of processing the set of 'Request' messages that can be received as defined by the binding definition to be used to support the information model;
- Accurately implement the processing behavior invoked by the request. The completion of this processing must result in the reporting of the appropriate status information;
- Construct the appropriate 'Response' messages as defined by the binding definition to be used to support the information model;
- Return the appropriate status code. The status code 'Unsupported' must not be returned;
- Maintain the persistence of the data objects once they have been created until they are deleted. Only those elements that are mandatory, as defined by the appropriate data model XSD, are supported at this level.
3.3 Level 3 Compliance
3.3.1 Service Requester Compliance
As per level 2 compliance plus:
- 'Request' and 'Response' messages can be composed from the mandatory and a predefined sub-set of the optional elements, as defined by the appropriate data model XSD.
3.3.2 Service Provider Compliance
As per level 2 compliance plus:
- It must maintain the persistence of the data objects once they have been created until they are deleted. All mandatory and a predefined sub-set of the optional elements, as defined by the appropriate data model XSD.
3.4 Level 4 Compliance
3.4.1 Service Requester Compliance
As per level 2 compliance plus:
- 'Request' and 'Response' messages can be composed from any of the elements (mandatory and all optional), as defined by the appropriate data model XSD.
3.4.2 Service Provider Compliance
As per level 2 compliance plus:
- It must maintain the persistence of the data objects once they have been created until they are deleted. All elements (mandatory and all optional), as defined by the appropriate data model XSD.
3.5 Preferred Levels of Compliance
The preferred level of compliance is (in decreasing order of preference):
- Level 4 - extending 'Level 2' by supporting all of the optional elements;
- Level 3 - extending 'Level 2' by supporting some of the optional elements;
- Level 2 - only the mandatory data model elements are supported;
- Level 1 - this states that the service is unsupported.
Interoperability is determined by the system that supports the compliance highest in the order of preference. If a system supports only Level 2 compliance, then it will reject any data contained within an optional element. The rejection of the data will result in a behavior failure status code.
4. Interoperability and Conformance
An implementation of an Enterprise Service is expected to accurately complete a Conformance Statement - see Appendix A for the format of the Conformance Statement. The Conformance Statement lists the level of compliance claimed for each of the behaviors defined within the Enterprise Service specification. Interoperability between two systems is then identified by comparing their Conformance Statements, i.e., a comparison of the 'Service Requester' and 'Service Provider' statements.
Table 4.1 lists the interoperability implications for each possible combination of the service requester and service provider compliance claims. The key points from Table 4.1 with regard to interoperability are (all matrix points are denoted as {i,j} with 'i' referring to the level of conformance of the Service Provider - this gives rise to sixteen possible interoperability states):
- Seven states result in no interoperability - {1,1}, {1,2}, {1,3}, {1,4}, (2,1}, {3,1} and {4,1};
- Two states result in symmetric but limited interoperability - {2,2} and {3,3};
- Three states results in 'Provider Constrained' interoperability i.e. the capabilities of the Service Provider determine the extent of interoperability - {2,2}, {2,3} and {3,4};
- Three states results in 'Requester Constrained' interoperability i.e. the capabilities of the Service Requester determine the extent of interoperability - {3,2}, {4,2} and {4,3};
- One state provides full interoperability - {4,4}.
It must be stressed that the matrix in Table 4.1 reflects the level of interoperability for a single behavior. The same matrix comparison needs to be supplied for each of the behaviors. An example of this comparison based upon the Conformance Statement given in Appendix A is shown in Table 4.2.
In the example in Table 4.2 the Service Provider is defined as a full service (Level 4 conformance) for many behaviors, i.e., it can support all of the mandatory and optional data structures. The Service Requester provides Level 3 conformance for many behaviors. This results in many behaviors being 'Requester Constrained'. The notable differences are the 'deletePerson' and 'deletePersons' behaviors for which no Person data information is required.
Appendix A - ES Conformance Statement
A typical Conformance Statement for the Enterprise Services is shown in Tables A.1, A.2, and A.3. A full Enterprise Services Conformance Statement would entail all three tables being combined.
For each of these tables the 'Service Requester Conformance' and 'Service Provider Conformance' columns need to be completed. The 'Service Requester Conformance' column is used to denote the level of conformance supported by a system that issues Request messages and receives response messages, whereas, the 'Service Provider Conformance' column is used to denote the level of conformance supported by a system that receives Request messages and issues response messages. The possible values in the 'Service Requester Conformance' column are:
- N/A - the system cannot act as a Service Requester;
- 1 - not available i.e. this behavior cannot be requested;
- 2-4 - conformance levels one to three.
The possible values in the 'Service Provider Conformance' column are:
- N/A - the system cannot act as a Service Provider;
- 1 - the service is not supported by the System Provider;
- 2-4 - conformance levels two to three.
Every Service Provider must provide at least level 1 conformance for each behavior. If a system cannot act as a Service Provider then every row must have the entry 'N/A'. Similarly, if a system cannot act as a Service Requester then every row must have the entry 'N/A'.
About This Document
| Title | 1EdTech Enterprise Services Conformance Specification |
| Editor | Colin Smythe (1EdTech) |
| Team Co-Lead | Chris Vento (WebCT Inc.) |
| Version | 1.0 |
| Version Date | 11 June 2004 |
| Status | Final Specification |
| Summary | This document presents the 1EdTech Enterprise Services Conformance Specification. 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. The material in this document describes the Conformance Specification as applied to the Enterprise Services Information Model. This version supersedes the 1EdTech Enterprise v1.1 specifications. |
| Revision Information | 11 June 2004 |
| Purpose | This document has been approved by the 1EdTech Technical Board and is made available for adoption. |
| Document Location | http://www.imsglobal.org/es/ |
| To register any comments or questions about this specification please visit: http://www.imsglobal.org/developers/ims/imsforum/categories.cfm?catid=20 |
List of Contributors
The following individuals contributed to the development of this document:
Revision History
Index
A
Abstract Framework 1, 2
API 1, 2, 3
Attributes
Common
sourcedId 1 RecordMetaData
comments 1 Result
B
Binding technologies
WSDL 1
Description 1, 2 Member 1
Membership 1, 2
Person 1, 2, 3, 4
Conformance 1, 2, 3, 4, 5, 6, 7, 8
E
Enterprise Service 1, 2, 3, 4, 5
Enterprise Service Information Model 1
G
Group Management Service 1, 2, 3
M
Membership Management Service 1, 2, 3
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
P
Person Management Service 1, 2, 3, 4, 5
S
Services
Group Management 1, 2, 3
Membership Management 1, 2, 3
Person Management 1, 2, 3, 4, 5
Specifications
1EdTech
Information Model 1 Status Codes
unsupported 1
1EdTech Consortium, Inc. ("1EdTech") is publishing the information contained in this 1EdTech Enterprise Services Conformance Specification ("Specification") for purposes of scientific, experimental, and scholarly collaboration only.
1EdTech makes no warranty or representation regarding the accuracy or completeness of the Specification.
This material is provided on an "As Is" and "As Available" basis.
The Specification is at all times subject to change and revision without notice.
It is your sole responsibility to evaluate the usefulness, accuracy, and completeness of the Specification as it relates to you.
1EdTech would appreciate receiving your comments and suggestions.
Please contact 1EdTech through our website at http://www.imsglobal.org
Please refer to Document Name: 1EdTech Enterprise Services Conformance Specification Revision: 11 June 2004
