IMS Outcomes Management Service Information Model
Version 1.0
Public Draft Release
Version 1.0
Date Issued: 15 March 2010
Latest version: http://www.imsglobal.org/lis/
IPR and Distribution Notices
Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.
IMS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on IMS's procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.
Copyright © IMS Global Learning Consortium 2010. All Rights Reserved.
If you wish to distribute this document or use this document to implement a product or service, you must complete a valid license registration with IMS and receive an email from IMS granting the license. To register, follow the instructions on the IMS website: http://www.imsglobal.org/specificationdownload.cfm.
This document may be copied and furnished to others by Licensee organizations registered on the IMS website provided that the above copyright notice and this paragraph are included on all such copies. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to IMS, except as needed for the purpose of developing IMS specifications, under the auspices of a chartered IMS work group.
Use of this specification to develop products or services is governed by the license with IMS found on the IMS website: http://www.imsglobal.org/lis/lisv2p0pd/lisv2p0pdspeclicense.html.
The limited permissions granted above are perpetual and will not be revoked by IMS or its successors or assigns.
THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.
Join the discussion and post comments on the LIS Public Forum: http://www.imsglobal.org/community/forum/categories.cfm?catid=59
Table of Contents
1.1 Outcomes Management Service Overview
1.3 Structure of this Document
2 Outcomes Management Service Description
2.1 An Abstract Representation
2.2 Outcomes Management Service Architecture & Specification Model
2.3 Outcomes Composite Objects
2.4 Synchronous & Asynchronous Services
2.5 Handling the Service Status Codes
3.2 LineItemManager Interface Description
3.2.1 CreateLineItem() Operation
3.2.2 CreateByProxyLineItem() Operation
3.2.3 DeleteLineItem() Operation
3.2.4 ReadLineItem() Operation
3.2.5 ReadAllLineItemIds() Operation
3.2.6 ReadLineItemIdsForPerson() Operation
3.2.7 ReadLineItemIdsForCourseOffering() Operation
3.2.8 ReadLineItemIdsWithLineItemType() Operation
3.2.9 ReadLineItemIdsForCourseSection() Operation
3.2.10 ReadLineItemIdsFromSavePoint() Operation
3.2.11 ReadLineItems() Operation
3.2.12 ReadLineItemsFromSavePoint() Operation
3.2.13 ReplaceLineItem() Operation
3.2.14 UpdateLineItem() Operation
3.2.15 DiscoverLineItemIds() Operation
3.2.16 ChangeLineItemIdentifier() Operation
3.3 ResultManager Interface Description
3.3.1 CreateResult() Operation
3.3.2 CreateByProxyResult() Operation
3.3.3 DeleteResult() Operation
3.3.5 ReadAllResultIds() Operation
3.3.6 ReadResultIdsForPerson() Operation
3.3.7 ReadResultIdsForLineItem() Operation
3.3.8 ReadResultIdsForCourseOffering() Operation
3.3.9 ReadResultIdsForCourseSection() Operation
3.3.10 ReadResultIdsForCourseSectionWthStatus() Operation
3.3.11 ReadResultIdsForLineItemWithLineItemType() Operation
3.3.12 ReadResultIdsFromSavePoint() Operation
3.3.13 ReadResults() Operation
3.3.14 ReadResultsFromSavePoint() Operation
3.3.15 ReplaceResult() Operation
3.3.16 UpdateResult() Operation
3.3.17 DiscoverResultIds() Operation
3.3.18 ChangeResultIdentifier() Operation
3.4 ResultValueManager Interface Description
3.4.1 CreateResultValue() Operation
3.4.2 CreateByProxyResultValue() Operation
3.4.3 DeleteResultValue() Operation
3.4.4 ReadResultValue() Operation
3.4.5 ReadAllResultValueIds() Operation
3.4.6 ReadResultValueIdForLineItem() Operation
3.4.7 ReadResultValueIdForResult() Operation
3.4.8 ReadResultValueIdsFromSavePoint() Operation
3.4.9 ReadResultValues() Operation
3.4.10 ReadResultValuesFromSavePoint() Operation
3.4.11 ReplaceResultValue() Operation
3.4.12 UpdateResultValue() Operation
3.4.13 DiscoverResultValueIds() Operation
3.4.14 ChangeResultValueIdentifier() Operation
4.3 LineItemRecord Class Description
4.4 LineItemRecordSet Class Description
4.5 LineItemType Class Description
4.6 QueryObject Class Description
4.7 ResultRecord Class Description
4.8 ResultRecordSet Class Description
4.9 ResultStatus Class Description
4.10 ResultValueRecord Class Description
4.11 ResultValueRecordSet Class Description
4.12 SequenceIdentifier Class Description
4.13 StatusInfo Class Description
5.2 The Structure of an Outcome
5.3 OutcomesDatabase Class Description
5.3.1 LineItemRecord Attribute Description
5.3.2 ResultRecord Attribute Description
5.3.3 ResultValueRecord Attribute Description
5.4 LineItemRecord Class Description
5.4.1 SourcedGUID Attribute Description
5.4.2 LineItem Attribute Description
5.5 ResultRecord Class Description
5.5.1 SourcedGUID Attribute Description
5.5.2 Result Attribute Description
5.6 ResultValueRecord Class Description
5.6.1 SourcedGUID Attribute Description
5.6.2 ResultValue Attribute Description
5.7 CourseTemplateRecord Class Description
5.8 CourseOfferingRecord Class Description
5.9 CourseSectionRecord Class Description
5.10 SectionAssociationRecord Class Description
5.11 GroupRecord Class Description
5.12 PersonRecord Class Description
5.13 OutcomesHandler Class Description
5.14 ResourceHandler Class Description
5.15 LineItem Class Description
5.15.1 ContextType Attribute Description
5.15.2 LineItemType Attribute Description
5.15.3 Label Attribute Description
5.15.4 ResultValueSourcedId Attribute Description
5.15.5 ResultValue Attribute Description
5.15.6 LineItemMessageSettings Attribute Description
5.15.7 OutcomesHandlerSourcedId Attribute Description
5.15.8 DataSource Attribute Description
5.15.9 RecordInfo Attribute Description
5.15.10 Extension Attribute Description
5.16 Context Class Description
5.16.1 ContextIdentifier Attribute Description
5.16.2 ContextType Attribute Description
5.17 LineItemType Class Description
5.17.1 LineItemTypeVocabulary Attribute Description
5.17.2 LineItemTypeValue Attribute Description
5.17.3 ResourceHandlerSourcedId Attribute Description
5.17.4 LocaleKey Attribute Description
5.17.5 DefaultDisplayName Attribute Description
5.18.1 StatusofResult Attribute Description
5.18.2 LineItemSourcedId Attribute Description
5.18.3 PersonSourcedId Attribute Description
5.18.4 Date Attribute Description
5.18.5 ResultValueSourcedId Attribute Description
5.18.6 ResultValue Attribute Description
5.18.7 ResultScore Attribute Description
5.18.8 ResultMessageSettings Attribute Description
5.18.9 DataSource Attribute Description
5.18.10 RecordInfo Attribute Description
5.18.11 Extension Attribute Description
5.19 ResultStatus Class Description
5.19.1 ResultStatusVocabulary Attribute Description
5.19.2 ResultStatusValue Attribute Description
5.19.3 LocaleKey Attribute Description
5.19.4 DefaultDisplayName Attribute Description
5.20 ResultValue Class Description
5.20.1 Label Attribute Description
5.20.2 ValueList Attribute Description
5.20.3 ValueRange Attribute Description
5.20.4 DataSource Attribute Description
5.20.5 RecordInfo Attribute Description
5.20.6 Extension Attribute Description
5.21 ValueList Class Description
5.21.1 OrderValue Attribute Description
5.22 OrderedValue Class Description
5.22.1 Ordinal Attribute Description
5.22.2 Grade Attribute Description
5.22.3 ValueRange Attribute Description
5.23 ValueRange Class Description
5.23.1 Min Attribute Description
5.23.2 Max Attribute Description
5.24 Common Classes Descriptions
5.24.1 Metadata Class Description
5.24.2 IMSExtension Class Description
5.24.3 ExtensionField Class Description
5.24.5 SourcedGUID Class Description
5.24.6 PropertySet Class Description
6 Extending and Profiling the Service
6.1.2 Proprietary Data Elements
Appendix A – Summary List of Service Status Codes
B1 Set of Defined Vocabularies
B2 Using Vocabularies for the Metadata Class
B3 Using Vocabularies for the IMSExtension Class
List of Figures
Figure 2.1 Outcomes management service architecture model.
Figure 2.2 Schematic representation of the outcomes data model.
Figure 2.3 Synchronous service action flow.
Figure 2.4 Asynchronous service action flow.
Figure 3.1 OutcomesManagementService LineItemManager interface definitions.
Figure 3.2 OutcomesManagementService ResultManager interface definitions.
Figure 3.3 OutcomesManagementService ResultValueManager interface definitions.
Figure 3.4 State machine for a ‘lineItem’ object.
Figure 3.5 State machine for a ‘result’ object.
Figure 3.6 State machine for a ‘resultValue’ object.
Figure 5.1 OutcomesDatabase class diagram.
Figure 5.2 LineItem class diagram.
Figure 5.3 Result class diagram.
Figure 5.4 ResultValue class diagram.
Figure 5.5 Common class diagram.
List of Tables
Table 3.1 Summary of operations for LineItemManager.
Table 3.2 Status codes for the ‘createLineItem’ operation.
Table 3.3 Status codes for the ‘createByProxyLineItem’ operation.
Table 3.4 Status codes for the ‘deleteLineItem’ operation.
Table 3.5 Status codes for the ‘readLineItem’ operation.
Table 3.6 Status codes for the ‘readAllLineItemIds’ operation.
Table 3.7 Status codes for the ‘readLineItemIdsForPerson’ operation.
Table 3.8 Status codes for the ‘readLineItemIdsForCourseOffering’ operation.
Table 3.9 Status codes for the ‘readLineItemIdsWithLineItemType’ operation.
Table 3.10 Status codes for the ‘readLineItemIdsForCourseSection’ operation.
Table 3.11 Status codes for the ‘readLineItemIdsFromSavePoint’ operation.
Table 3.12 Status codes for the ‘readLineItems’ operation.
Table 3.13 Status codes for the ‘readLineItemsFromSavePoint’ operation.
Table 3.14 Status codes for the ‘replaceLineItem’ operation.
Table 3.15 Status codes for the ‘updateLineItem’ operation.
Table 3.16 Status codes for the ‘discoverLineItemIds’ operation.
Table 3.17 Status codes for the ‘changeLineItemIdentifier’ operation.
Table 3.18 Summary of operations for ResultManager.
Table 3.19 Transitions associated with the ‘createResult’ operation.
Table 3.20 Status codes for the ‘createByProxyResult’ operation.
Table 3.21 Status codes for the ‘deleteResult’ operation.
Table 3.22 Status codes for the ‘readResult’ operation.
Table 3.23 Status codes for the ‘readAllResultIds’ operation.
Table 3.24 Status codes for the ‘readResultIdsForPerson’ operation.
Table 3.25 Status codes for the ‘readResultIdsForLineItem’ operation.
Table 3.26 Status codes for the ‘readResultIdsForCourseOffering’ operation.
Table 3.27 Status codes for the ‘readResultIdsForCourseSection’ operation.
Table 3.28 Status codes for the ‘readResultIdsForCourseSectionWithStatus’ operation.
Table 3.29 Status codes for the ‘readResultIdsForLineItemWithLineItemType’ operation.
Table 3.30 Status codes for the ‘readResultIdsFromSavePoint’ operation.
Table 3.31 Status codes for the ‘readResults’ operation.
Table 3.32 Status codes for the ‘readResultsFromSavePoint’ operation.
Table 3.33 Status codes for the ‘replaceResult’ operation.
Table 3.34 Status codes for the ‘updateResult’ operation.
Table 3.35 Status codes for the ‘discoverResultIds’ operation.
Table 3.36 Status codes for the ‘changeResultIdentifier’ operation.
Table 3.37 Summary of operations for ResultValueManager.
Table 3.38 Status codes for the ‘createResultValue’ operation.
Table 3.39 ‘createByProxyResultValue’ operation.
Table 3.40 Status codes for the ‘deleteResultValue’ operation.
Table 3.41 Status codes for the ‘readResultValue’ operation.
Table 3.42 Status codes for the ‘readAllResultValueIds’ operation.
Table 3.43 Status codes for the ‘readResultValueIdForLineItem’ operation.
Table 3.44 Status codes for the ‘readResultValueIdForResult’ operation.
Table 3.45 Status codes for the ‘readResultValueIdsFromSavePoint’ operation.
Table 3.46 Status codes for the ‘readResultValues’ operation.
Table 3.47 Status codes for the ‘readResultsFromSavePoint’ operation.
Table 3.48 Status codes for the ‘replaceResultValue’ operation.
Table 3.49 Status codes for the ‘updateResultValue’ operation.
Table 3.50 Status codes for the ‘discoverResultValueIds’ operation.
Table 3.51 Status codes for the ‘changeResultValueIdentifier’ operation.
Table 5.2 Description of the OutcomesDatabase class.
Table 5.3 Description of the ‘lineItemRecord’ attribute for the OutcomesDatabase class.
Table 5.4 Description of the ‘ResultRecord’ attribute for the OutcomesDatabase class.
Table 5.5 Description of the ‘ResultValueRecord’ attribute for the OutcomesDatabase class.
Table 5.6 Description of the LineItemRecord class.
Table 5.7 Description of the ‘sourcedGUID’ attribute for the LineItemRecord class.
Table 5.8 Description of the ‘lineItem’ attribute for the OutcomesDatabase class.
Table 5.9 Description of the ResultRecord class.
Table 5.10 Description of the ‘sourcedGUID’ attribute for the ResultRecord class.
Table 5.11 Description of the ‘result’ attribute for the ResultRecord class.
Table 5.12 Description of the ResultValueRecord class.
Table 5.13 Description of the ‘sourcedGUID’ attribute for the ResultValueRecord class.
Table 5.14 Description of the ‘ResultValue’ attribute for the ResultValueRecord class.
Table 5.15 Description of the CourseTemplateRecord class.
Table 5.16 Description of the CourseOfferingRecord class.
Table 5.17 Description of the CourseSectionRecord class.
Table 5.18 Description of the SectionAssociationRecord class.
Table 5.19 Description of the GroupRecord class.
Table 5.20 Description of the PersonRecord class.
Table 5.21 Description of the OutcomesHandler class.
Table 5.22 Description of the ResourceHandler class.
Table 5.23 Description of the LineItem class.
Table 5.24 Description of the ‘contextType’ attribute for the LineItem class.
Table 5.25 Description of the ‘lineItemType’ attribute for the LineItem class.
Table 5.26 Description of the ‘label’ attribute for the LineItem class.
Table 5.27 Description of the ‘resultValueSourcedId’ attribute for the LineItem class.
Table 5.28 Description of the ‘resultValue’ attribute for the LineItem class.
Table 5.29 Description of the ‘lineItemMessageSettings’ attribute for the LineItem class.
Table 5.30 Description of the ‘outcomesHandlerSourcedId’ attribute for the LineItem class.
Table 5.31 Description of the ‘dataSource’ attribute for the LineItem class.
Table 5.32 Description of the ‘recordInfo’ attribute for the LineItem class.
Table 5.33 Description of the ‘extension’ attribute for the LineItem class.
Table 5.34 Description of the Context class.
Table 5.35 Description of the ‘contextIdentifier’ attribute for the Context class.
Table 5.36 Description of the ‘contextType’ attribute for the Context class.
Table 5.37 Description of the LineItemType class.
Table 5.38 Description of the ‘lineItemTypeVocabulary’ attribute for the LineItemType class.
Table 5.39 Description of the ‘lineItemTypeValue’ attribute for the LineItemType class.
Table 5.40 Description of the ‘resourceHandlerSourcedId’ attribute for the LineItemType class.
Table 5.41 Description of the ‘localeKey’ attribute for the LineItemType class.
Table 5.42 Description of the ‘defaultDisplayName’ attribute for the LineItemType class.
Table 5.43 Description of the Result class.
Table 5.44 Description of the ‘statusofResult’ attribute for the Result class.
Table 5.45 Description of the ‘lineItemSourcedId’ attribute for the Result class.
Table 5.46 Description of the ‘personSourcedId’ attribute for the Result class.
Table 5.47 Description of the ‘date’ attribute for the Result class.
Table 5.48 Description of the ‘ResultValueSourcedId’ attribute for the Result class.
Table 5.49 Description of the ‘resultValue’ attribute for the Result class.
Table 5.50 Description of the ‘resultScore’ attribute for the Result class.
Table 5.51 Description of the ‘resultMessageSettings’ attribute for the Result class.
Table 5.52 Description of the ‘dataSource’ attribute for the Result class.
Table 5.53 Description of the ‘recordInfo’ attribute for the Result class.
Table 5.54 Description of the ‘extension’ attribute for the Result class.
Table 5.55 Description of the ‘resultStatusVocabulary’ attribute for the ResultStatus class.
Table 5.56 Description of the ‘resultStatusValue’ attribute for the ResultStatus class.
Table 5.57 Description of the ‘localeKey’ attribute for the ResultStatus class.
Table 5.58 Description of the ‘defaultDisplayName’ attribute for the ResultStatus class.
Table 5.59 Description of the ResultValue class.
Table 5.60 Description of the ‘label’ attribute for the ResultValue class.
Table 5.61 Description of the ‘valueList’ attribute for the ResultValue class.
Table 5.62 Description of the ‘valueRange’ attribute for the ResultValue class.
Table 5.63 Description of the ‘dataSource’ attribute for the ResultValue class.
Table 5.64 Description of the ‘recordInfo’ attribute for the ResultValue class.
Table 5.65 Description of the ‘extension’ attribute for the ResultValue class.
Table 5.66 Description of the ValueList class.
Table 5.67 Description of the ‘orderValue’ attribute for the ValueList class.
Table 5.68 Description of the OrderedValue class.
Table 5.69 Description of the ‘ordinal’ attribute for the OrderedValue class.
Table 5.70 Description of the ‘grade’ attribute for the OrderedValue class.
Table 5.71 Description of the ‘valueRange’ attribute for the OrderedValue class.
Table 5.72 Description of the ValueRange class.
Table 5.73 Description of the ‘min’ attribute for the ValueRange class.
Table 5.74 Description of the ‘max’ attribute for the ValueRange class.
Table 5.75 Description of the Metadata class.
Table 5.76 Description of the ‘metadataNameVocabulary’ attribute for the Metadata class.
Table 5.77 Description of the ‘metadataTypeVocabulary’ attribute for the Metadata class.
Table 5.78 Description of the ‘metadataField’ attribute for the Metadata class.
Table 5.79 Description of the IMSExtension class.
Table 5.80 Description of the ‘extensionNameVocabulary’ attribute for the IMSExtension class.
Table 5.81 Description of the ‘extensionTypeVocabulary’ attribute for the IMSExtension class.
Table 5.82 Description of the ‘extensionField’ attribute for the IMSExtension class.
Table 5.83 Description of the ExtensionField class.
Table 5.84 Description of the ‘fieldName’ attribute for the ExtensionField class.
Table 5.85 Description of the ‘fieldType’ attribute for the ExtensionField class.
Table 5.86 Description of the ‘fieldValue’ attribute for the ExtensionField class.
Table 5.87 Description of the ‘Text’ class.
Table 5.88 Description of the ‘language’ attribute for the Text class.
Table 5.89 Description of the ‘textString’ attribute for the Text class.
Table 5.90 Description of the SourcedGUID class.
Table 5.91 Description of the ‘refAgentInstanceID’ attribute for the SourcedGUID class.
Table 5.92 Description of the ‘sourcedId’ attribute for the SourcedGUID class.
Table 5.93 Description of the PropertySet class.
Table A1.1 Status codes for the service operations.
Table A1.2 Common status codes for the service operations.
Table B1.1 The lineItemType external vocabulary.
Table B1.2 The result status external vocabulary.
Table B1.3 The fieldType external vocabulary..
1 Introduction
1.1 Outcomes Management Service Overview
The Outcomes Management Service (OMS) specification is the definition of how systems manage the exchange of information that describes Outcomes. The Outcomes Management Service specification is constructed following the recommendations documented in the IMS GLC Abstract Framework (IAF) [IAF, 03a], [IAF, 03b], [IAF, 03c]. This means that this specification is based upon the concepts of:
· Interoperability – Outcomes Management Service focuses on the exchange of Outcomes information between systems. There are no definitions in the specification on how the data is managed within the systems;
· Service-oriented – Outcomes Management Service defines the exchange of information in terms of the services being supplied by the collaboration of the systems;
· Component-based – for example, the Outcomes Management Service is combined with the Group Management Service, Person Management Service, Course Management Service, Membership Management Service and Bulk Data Exchange Management Service to provide the Learning Information Services [LIS, 10a], [LIS, 10b];
· Layering – the Outcomes Management Service is a part of the Application Services layer but it interacts with the services available in the Common Services layer e.g. authentication;
· Behaviors and Data Models – the Outcomes Management Service 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 Outcomes Management Service 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 the Web Services Description Language (WSDL);
· Adoption – whenever appropriate, the Outcomes Management Services specification makes use of other IMS GLC and non-IMS GLC standards and specifications.
The logical structure of the Outcomes is composed of LineItems, Results and ResultValues. A LineItem is a collection of Results for a particular CourseOffering, CourseSection, etc. and each Result and/or LineItem may have an associated set of values, ResultValue, which are used to constrain the Result. The standard create, read, update, replace, delete and simple discovery operations are available for managing LineItems, Results and ResultValues. Other operations are defined to support specific business requirements. Full operation of all of the Behaviors in this service will require access to the data models of the corresponding IMS GLC Course Management Service (CMS) [CMS, 10] and the IMS GLC Membership Management Service (MMS) [MMS, 10] specifications.
1.2 Scope and Context
This document is the IMS GLC Outcomes Management Services Information Model v2.0 and as such it is used as the basis for the development of the following documents:
a) IMS GLC Outcomes Management Service WSDL Binding v2.0 [OMS, 10] – the description of the WSDL binding of the Information Model.
The core uses-cases for the Outcomes Management Service are described as a subset of the Learning Information Services Specification [LIS, 10b].
This information model defines the Outcomes Management Service Abstract Application Programming Interface (a-API). The Learning Information Services specification, of which the Outcomes Management Service is a component, is a series of Behavioral models that define how the data models are to be manipulated. These Behavioral models are described using the Unified Modelling Language (UML) [SDN07, 07].
1.3 Structure of this Document
The structure of this document is:
|
2. Outcomes Management Service Description |
The description of the overall structure and operation of the Outcomes Management Service. This includes the description of the architectural model and the domain object model; |
|
3. Behavioral Model |
The definition of the operations of Outcomes Management Service application service. This focuses on the description of the Behaviors supported by the service; |
|
4. Interface Data Model |
The definition of the data models exchanged between the Outcomes Management Service End Systems. These are the parameters exchanged across the interoperability interface; |
|
5. End System Data Model |
The definition of the data models for the Outcomes Management Service End Systems. This addresses the persistence of the data with respect to interoperability; |
|
6. Extending and Profiling the Service |
Identification of the ways in which the Outcomes Management Service can be extended both in terms of the addition of new constituent services and proprietary extensions to a service; |
|
Appendix A Summary List of Service Status Codes |
A summary list of the status codes by for the operations of the Outcomes Management Service; |
|
Appendix B Vocabularies |
A summary of the set of vocabularies that are used within the specification. |
1.4 Version Compatibility
The Outcomes Management Service was not developed in the IMS GLC Enterprise Services v1.0 specification [ES, 04]. Instead, a simplified form of functionality was supported using the IMS GLC Membership Management Services (MMS) v1.0 [MMS, 04]. In general, there is NO backwards compatibility between the usage of the OMSv2.0 and the ways in which MMSv1.0 has been implemented to support outcomes management. Vendors may define compatibility bridges for their own implementations but these are outside the scope of this specification.
1.5 Nomenclature
a-API Abstract Application Programming Interface
API Application Programming Interface
CMS Course Management Service
IAF IMS GLC Abstract Framework
LIS Learning Information Services
LTI Learning Tools Interoperability
MMS Membership Management Service
OMS Outcomes Management Service
PIM Platform Independent Model
PSM Platform Specific Model
RFC Request For Comment
SDN Specification Development Note
UML Unified Modelling Language
WSDL Web Services Description Language
1.6 References
[APG, 05a] IMS GLC Application Profile Guidelines Overview: Part 1 – Management Overview v1.0, IMS Global Learning Consortium, K.Riley, October 2005. http://www.imsglobal.org/ap/index.html.
[APG, 05b] IMS GLC Application Profile Guidelines White Paper: Part 2 Technical Manual, S.Wilson and K.Riley, Version 1.0, IMS Global Learning Consortium, October 2005. http://www.imsglobal.org/ap/index.html.
[BDEMS, 10] IMS GLC Bulk Data Exchange Management Service Information Model v1.0 Public Draft, L.Feng, W.Lee and C.Smythe, IMS Global Learning Consortium, March 2010.
[CMS, 10] IMS GLC Course Management Service Information Model v1.0 Public Draft, L.Feng, W.Lee and C.Smythe, IMS Global Learning Consortium, March 2010.
[ES, 04] IMS GLC Enterprise Services Overview v1.0 Final Release, C.Vento and C.Smythe, IMS Global Learning Consortium, June 2006.
[GMS, 10] IMS GLC Group Management Services Information Model v2.0 Public Draft, L.Feng, W.Lee and C.Smythe, IMS Global Learning Consortium, March 2010.
[GWS, 05] IMS GLC General Web Services WSDL Binding Guidelines v1.0 Final Specification, C.Schroeder, J.Simon and C.Smythe, IMS Global Learning Consortium, December 2005.
[IAF, 03a] IMS Abstract Framework: Applications, Services & Components v1.0, Ed. C.Smythe, IMS Global Learning Consortium, July 2003.
[IAF, 03b] IMS Abstract Framework: Glossary v1.0, Ed. C.Smythe, IMS Global Learning Consortium, July 2003.
[IAF, 03c] IMS Abstract Framework: White Paper v1.0, Ed. C.Smythe, IMS Global Learning Consortium, July 2003.
[LIS, 10a] IMS GLC Learning Information Services Overview v2.0 Public Draft, L.Feng, W.Lee and C.Smythe, IMS Global Learning Consortium, March 2010.
[LIS, 10b] IMS GLC Learning Information Services Specification v2.0. Public Draft, L.Feng, W.Lee and C.Smythe, IMS Global Learning Consortium, March 2010.
[LIS, 10c] IMS GLC Learning Information Services Best Practices & Implementation Guide v2.0 Public Draft, L.Feng, W.Lee and C.Smythe, IMS Global Learning Consortium, March 2010.
[MMS, 04] IMS GLC Membership Management Services Information Model v1.0 Final Release, C.Vento and C.Smythe, IMS Global Learning Consortium, June 2004.
[MMS, 10] IMS GLC Membership Management Service Information Model v2.0 Public Draft, L.Feng, W.Lee and C.Smythe, IMS Global Learning Consortium, March 2010.
[OMS, 10] IMS GLC Outcomes Management Service WSDL Binding v1.0 Public Draft, L.Feng, W.Lee and C.Smythe, IMS Global Learning Consortium, March 2010.
[SDN07, 06] IMS GLC Specification Note: UML Profile for Platform Independent Model Descriptions of Specifications for Data Models v1.0, C.Smythe, IMS Global Learning Consortium, October 2006.
[SDN11, 06] IMS GLC Specification Note 11: Vocabulary Definition, Registration & Maintenance Procedures, C.Smythe, IMS Global Learning Consortium, October 2006.
[VDEX, 04] IMS/GLC Vocabulary Definition Exchange Best Practice and Implementation Guide, Version 1.0 Final Specification, A. Cooper, IMS Global Learning Consortium, 2005. Online version: http://www.imsglobal.org/vdex/vdexv1p0/imsvdex_bestv1p0.html
2 Outcomes Management Service Description
2.1 An Abstract Representation
It is important to remember that this document contains the description of 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 Outcomes Management Service. The breakdown of the service into its interface classes 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, J2EE, 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 Outcomes Management Service 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 be also maintained.
2.2 Outcomes Management Service Architecture & Specification Model
The basic architectural model for the Outcomes Management Service specification is shown in Figure 2.1. In this architecture the scope of the IMS GLC Outcomes Management Service specification is shown as the dotted line. The scope of the interoperability is the data and Behavioral models of the objects being exchanged.
Figure 2.1 Outcomes management service architecture model.
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’ Learning Information Services systems (the Outcomes object repositories in the two end-systems). It is simply a representation of the data used to facilitate exchange between the end-systems. The only constraint on the end-system repositories is that they provide data persistence consistent with the required behavior.
2.3 Outcomes Composite Objects
It is important to note that this is an interoperability specification and as such it makes no statements about how information is stored within the exchanging end systems. The objects in the end-systems must be persistent otherwise sequences of operation on the same object will not be possible. Reference to these objects in the interface is through a ‘sourcedId’ however this identifier does not have to be the key stored within the end-systems. If different keys are used in the end-systems then it is the responsibility of the end-systems to maintain the mapping between that key and the ‘sourcedId’ i.e. the interface must never be exposed to the keys of the end-systems.
There is no such thing as an Outcomes object. Instead, Outcomes are reflected in three types of object each of which has its own ‘sourcedId’ which are linked to create the Outcomes data model as shown in Figure 2.2.
Figure 2.2 Schematic representation of the outcomes data model.
The three classes of object are:
· LineItem – the set of results for a particular CourseTemplate, CourseOffering, CourseSection and Group (each result is a Result object);
· Result – the container for a result for a particular Person (each result can be related to a ResultValue object);
· ResultValue – the permitted range of values for a Result and/or a LineItem.
As shown in Figure 2.2 the LineItem is the key object that is used to establish the relationship between course components and the results for each person. A LineItem has three fields:
· The identifier (that is the sourcedId) of the associated course components (denoted as Cp in Figure 2.2). More than one LineItem can point to the same course component;
· The type of LineItem (this is an open vocabulary as in Figure 2.2 this includes ‘Interim’, ‘Final’, etc.);
· The ResultValue that defines the nature of all of the results associated with the LineItem (each Result must be associated with one, and only one, LineItem).
Each Result is associated with a LineItem and a Person i.e. the Person who has received the result for that particular course component. A Person may have several results, for the same or different course components, and so more than one result may be associated with a Person. The unit of marking for the Result is defined by the ResultValue associated with the Result. In general, many Results will be associated with each type of ResultValue. A ResultValue can also be assigned to a LineItem thereby defining all Results to be of the same ResultValue.
A system that wishes to support all of the behaviors of the OMS must also contain the Course data model as defined in the IMS GLC Course Management Services Information Model v1.0 specification [CMS, 10] and may have to support the Group data model in the IMS GLC Group Management Services Information Model v2.0 specification [GMS, 10].
2.4 Synchronous & Asynchronous Services
Within the context of the Outcomes Management Service the definition of synchronous and asynchronous services is:
· Synchronous – the source service is blocked until the final response from the target service is received. A schematic representation of the information flow for a synchronous service is shown in Figure 2.3;
· Asynchronous – the source service is not blocked and so more than one request can be outstanding at any moment in time. A schematic representation of the information flow for an asynchronous service is shown in Figure 2.4.
Figure 2.3 Synchronous service action flow.
It is stressed that the abstract-API does not differentiate between synchronous and asynchronous services[1]. The support for these two approaches is differentiated at the binding level only.
Figure 2.4 Asynchronous service action flow.
The key difference is that for an asynchronous service more than one request can be issued at any one time (it should be noted that an asynchronous service can be supported using synchronous messaging). In both cases the service assumes a perfect messaging system i.e. request, response and acknowledgement messages have a guaranteed delivery grade of service.
2.5 Handling the Service Status Codes
Each operation in a service is mapped to an appropriate message exchange pattern. Any response/acknowledgement message will contain status information. This status information provides contextual information about the completed success or otherwise of the operation. There are two types of status information that are available to the end-systems:
· Business transaction – these are the status reports that reflect the business logic of the transactions being exchanged by the end-systems. This status information will be contained within the message header under a specially defined data structure. The status information contained herein is also used to contain any error codes i.e. error reporting is handled as a subset of status information reporting;
· Messaging fault– these are fault codes that are reported by the messaging infrastructure and which are carried in the messages.
It is important to note that messaging errors may indicate that the original request never reached the service provider end-system. In this case the service consumer implementation that handles the status information is responsible for mapping the message infrastructure failure codes to the equivalent business transaction status code. The message infrastructure failure codes have no meaning with respect to an IMS GLC specification. The IMS GLC specifications do not describe how the status information is to be handled within an end-system i.e. this will depend on how the abstract API is physically realized within an implementation. Therefore, it is important that an implementation can:
· Combine the transaction status information and any message fault error codes in a single integrated status reporting mechanism. Any other system failure information that is made available by an implementation should also use the same mechanism;
· Examine the status information reported after the completion of the appropriate phase of an operation and especially once the operation has been completed. This may require an explicit status information call or it may be reported as part of the API call;
· Differentiate the status information reports for each transaction within an operation. Remember that some specifications provide operations that can contain more than one transaction request and that a different status report may be given for each of those transactions.
Exception handling is the system’s response to known or unknown error conditions. Exception handling is outside the scope of an IMS GLC specification. However, an error condition should not cause the end-systems to fail in an uncontrolled manner. The requirement for every operation to return status information is to enable an implementation to terminate in a controlled fashion.
3 Behavioral Model
3.1 Service Definition
The OutcomesManagmentService is used to model the service responsible for manipulating information about outcomes. The OutcomesManagementService interfaces are shown in Figures 3.1, 3.2 and 3.3. The OutcomesManagementService is split into three interfaces: LineItemManager that supports the manipulation of LineItem objects; ResultManager that supports the manipulation of Result objects; ResultValueManager that supports the manipulation of ResultValue objects.
3.2 LineItemManager Interface Description
The LineItemManager interface class describes the operations that are permitted on LineItem objects (as shown in Figure 3.1). The set of operations are summarized in Table 3.1.
Figure 3.1 OutcomesManagementService LineItemManager interface definitions.
Table 3.1 Summary of operations for LineItemManager.
|
Operation |
Description |
|
createLineItem |
To request the creation of a populated LineItem object on the target system where the source is responsible for the allocation of the unique SourcedId. |
|
createByProxyLineItem |
To request the creation of a populated LineItem object on the target system where the target is responsible for the allocation of the unique SourcedId. |
|
deleteLineItem |
To request the deletion of a LineItem object. The LineItem object is deleted with all of its associated relationships. |
|
readLineItem |
To read the full contents of the identified LineItem object. The target must return all of the data it has for the identified LineItem object. |
|
readAllLineItemIds |
To obtain all the SourcedIds assigned to LineItem objects. |
|
readLineItemIdsWithLineItemType |
To obtain the set of SourcedIds for the LineItem objects which have a particular state. |
|
readLineItemIdsForPerson |
To obtain the set of SourcedIds for the LineItem objects which are associated with a particular Person object. |
|
readLineItemIdsForCourseOffering |
To obtain the set of SourcedIds for the LineItem objects which are associated with a particular CourseOffering object. |
|
readLineItemIdsForCourseSection |
To obtain the set of SourcedIds for the LineItem objects which are associated with a particular CourseSection object. |
|
readLineItemIdsFromSavePoint |
To obtain the set of SourcedIds for LineItem objects which have been altered since the requested reference point. The reference point is set as ‘zero’ at creation and incremented after every write operation. |
|
readLineItems |
To obtain the LineItem objects for a defined set of SourcedIds. This results in a single transaction that may require the exchange of a large volume of data in the response message. |
|
readLineItemsFromSavePoint |
To obtain the set of LineItem objects which have been altered since the requested reference point. The reference point is set as ‘zero’ at creation and incremented after every write operation. This results in a single transaction that may require the exchange of a large volume of data in the response message. |
|
updateLineItem |
To write new content into the identified LineItem object. The target must write the new data into the LineItem object. This is an additive operation. |
|
replaceLineItem |
To replace the content of the identified LineItem object. The target must write the new data into the LineItem object. This is a destructive write-over of all of the original information. |
|
discoverLineItemIds |
To obtain the set of SourcedIds for LineItem objects whose properties agree with those defined in the query/filter. |
|
changeLineItemIdentifier |
To change the SourcedId for a LineItem object. |
3.2.1 CreateLineItem() Operation
|
Name: |
createLineItem |
|
Return Function Parameter: |
StatusInfo – the status of the creation request. The permitted status codes are defined in Tables 3.2 and A.2. |
|
Supplied (in) Parameters: |
sourcedId:GUID – the sourcedId allocated by the source system. This is the identifier that must also be assigned within the target system. lineItemRecord:LineItemRecord – the LineItem data that is to be stored in the new object. |
|
Returned (out) Parameters: |
None. |
|
Behavior: |
When the source issues the ‘createLineItem’ request the target is instructed to create the populated LineItem object and to allocate that structure the SourcedId passed by the source. If the supplied SourcedId has already been allocated to another object then the request is rejected and the appropriate failure code is returned. The reference point identifier is set to ‘zero’ for the object in both the source and target. |
|
Notes: |
This request contains the initial content for the LineItem object. More content can be added/replaced using the ‘updateLineItem’ and/or ‘replaceLineItem’ requests. |
Table 3.2 Status codes for the ‘createLineItem’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The creation request has been fully and successfully implemented by the target system and the object has been created with the supplied SourcedId. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=idallocinusefail’ |
The target could not allocate the unique SourcedId to the object as the identifier is already in use. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=overflowfail’ |
The target could not create the LineItem record due to lack of target allocation memory. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the supplied data was detected as invalid by the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=incompletedata’ |
Some mandatory part of the data has been detected as missing by the target system. |
|
‘CodeMajor=Success’ ‘Severity=Warning’ ‘CodeMinor=partialdatastorage’ |
The target has only stored a subset of the sent data record e.g. only the mandatory parts. |
|
‘CodeMajor=Success’ ‘Severity=Warning’ ‘CodeMinor=unknownextension’ |
The target cannot process the proprietary extensions that are used in the object’s data model. |
3.2.2 CreateByProxyLineItem() Operation
|
Name: |
createByProxyLineItem |
|
Return Function Parameter: |
StatusInfo – the status of the creation request. The permitted status codes are defined in Tables 3.3 and A.2. |
|
Supplied (in) Parameters: |
lineItemRecord:LineItemRecord – the LineItem data that is to be stored in the new object. |
|
Returned (out) Parameters: |
sourcedId:GUID – the identifier allocated by the target to the newly created LineItem object. |
|
Behavior: |
When the source issues the ‘createByProxyLineItem’ request the target is instructed to create the populated CourseLineItem object and to allocate that record a unique SourcedId. The reference point identifier is set to ‘zero’ for the LineItem object in both the source and target. |
|
Notes: |
This request contains the initial content for the LineItem object. More content can be added/replaced using the ‘updateLineItem’ and/or ‘replaceLineItem’ requests. |
Table 3.3 Status codes for the ‘createByProxyLineItem’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The creation request has been fully and successfully implemented by the target system and the object has been created with the SourcedId generated by the target. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=idallocfail’ |
The target could not allocate a unique SourcedId to the object because there are no more spare identifiers available. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=overflowfail’ |
The target could not create the object due to lack of target allocation memory. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the supplied data was detected as invalid by the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=incompletedata’ |
Some mandatory part of the data has been detected as missing by the target system. |
|
‘CodeMajor=Success’ ‘Severity=Warning’ ‘CodeMinor=partialdatastorage’ |
The target has only stored a subset of the sent data record e.g. only the mandatory parts. |
|
‘CodeMajor=Success’ ‘Severity=Warning’ ‘CodeMinor=unknownextension’ |
The target cannot process the proprietary extensions that are used in the object’s data model. |
3.2.3 DeleteLineItem() Operation
|
Name: |
deleteLineItem |
|
Return Function Parameter: |
StatusInfo – the status of the deletion request. The permitted status codes are defined in Tables 3.4 and A.2. |
|
Supplied (in) Parameters: |
sourcedId:GUID – the identifier to be used by the target to identify the LineItem object. |
|
Returned (out) Parameters: |
None. |
|
Behavior: |
When the source issues the ‘deleteLineItem’ request the target is instructed to delete the identified LineItem object and to remove any associations. If the object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. The LineItem is deleted and all of the associated Result objects. |
|
Notes: |
Deletion of the LineItem object does not necessarily result in the destruction of the data within the server. The true state of the data in the target is unknown. |
Table 3.4 Status codes for the ‘deleteLineItem’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The deletion request has been fully and successfully implemented by the target system and the objects have been deleted. The corresponding child objects have been deleted. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The object identifier is unknown in the target system and so the object could not be deleted. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor= deletefailure’ |
The target system has not been able to delete the identified object because there are Result objects associated with the LineItem. |
3.2.4 ReadLineItem() Operation
|
Name: |
readLineItem |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.5 and A.2. |
|
Supplied (in) Parameters: |
sourcedId:GUID – the identifier of the LineItem object to be read. |
|
Returned (out) Parameters: |
lineItemRecord:LineItemRecord – the LineItem data that is read from the object. |
|
Behavior: |
When the source issues the ‘readLineItem’ request the target is charged with retrieving the identified object from its database and returning this data to the source. The target is responsible for ensuring that the object contains valid data. If the object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. |
|
Notes: |
The returned LineItem object can only be trusted if the corresponding status code is ‘success’. |
Table 3.5 Status codes for the ‘readLineItem’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the identified object has been read from the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The object identifier is unknown in the target system and so the object could not be read. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=targetreadfailure’ |
The target system has detected an error in the stored object and so cannot return the data. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=incompletedata’ |
Some mandatory part of the data has been detected as missing by the source system. |
|
‘CodeMajor=Success’ ‘Severity=Warning’ ‘CodeMinor=unknownextension’ |
The source cannot process the proprietary extensions that are used in the object’s data model. |
3.2.5 ReadAllLineItemIds() Operation
|
Name: |
readAllLineItemIds |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.6 and A.2. |
|
Supplied (in) Parameters: |
None. |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of sourcedIds for all of the LineItem objects in the target’s Outcomes database. |
|
Behavior: |
When the source issues the ‘readAllLineItemIds’ request the target is charged with returning the SourcedIds of all of the LineItems in its line item database. |
|
Notes: |
If no SourcedIds have been allocated then the returned data set is empty and the success status code returned. |
Table 3.6 Status codes for the ‘readAllLineItemIds’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the object identifiers have been read from the target system. |
|
‘CodeMajor=Success’
‘Severity=Status’ |
The read request has been fully and successfully implemented by the target system and no LineItem object identifiers were found. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
3.2.6 ReadLineItemIdsForPerson() Operation
|
Name: |
readLineItemIdsForPerson |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.7 and A.2. |
|
Supplied (in) Parameters: |
personSourcedId:GUID – the identifier of the Person object whose LineItem sourcedIds are required. |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of SourcedIds for all of the LineItem objects for the Person in the target’s Outcomes database. |
|
Behavior: |
The target system must return all of the LineItem SourcedIds for the identified Person object. If the Person object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. The association between a Person and the LineItems is defined through a Membership of a Course object e.g. a CourseOffering. The LineItems are then searched for those that have the association with the corresponding Course object. |
|
Notes: |
The returned object can only be trusted if the corresponding status code is ‘success’. This Behavior requires that the system support the Membership and Course data models [MMS, 09], [CMS, 09]. |
Table 3.7 Status codes for the ‘readLineItemIdsForPerson’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the identified object has been read from the target system. |
|
‘CodeMajor=Success’
‘Severity=Status’ |
The read request has been fully and successfully implemented by the target system and no LineItem object identifiers were found. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The Person object identifier is unknown in the target system and so the relationships could not be identified. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=targetreadfailure’ |
The target system has detected an error in the object databases and so cannot locate the identifiers. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
3.2.7 ReadLineItemIdsForCourseOffering() Operation
|
Name: |
readLineItemIdsForCourseOffering |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.8 and A.2. |
|
Supplied (in) Parameters: |
offeringSourcedId:GUID – the identifier of the CourseOffering object whose LineItem sourcedIds are required. |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of sourcedIds for all of the LineItem objects for the CourseOffering in the target’s Course database. |
|
Behavior: |
The target system must return all of the LineItem SourcedIds for the identified CourseOffering object. If the object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. |
|
Notes: |
None. |
Table 3.8 Status codes for the ‘readLineItemIdsForCourseOffering’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the LineItem identifiers have been read from the target system. |
|
‘CodeMajor=Success’
‘Severity=Status’ |
The read request has been fully and successfully implemented by the target system and no LineItem identifiers were found. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The CourseOffering object identifier is unknown in the target system and so the object could not be read. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=targetreadfailure’ |
The target system has detected an error in the LineItem database and so cannot return the data. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
3.2.8 ReadLineItemIdsWithLineItemType() Operation
|
Name: |
readLineItemIdsWithStatus |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.9 and A.2. |
|
Supplied (in) Parameters: |
lineItemType:LineItemType – the LineItem objects with a particular column type whose SourcedIds are required. |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of SourcedIds for all of the LineItem objects of the appropriate status value in the target’s Outcomes database. |
|
Behavior: |
The target system must return all of the LineItem SourcedIds that have the supplied status value. If an invalid status value is supplied then the request is rejected and the appropriate failure code is returned. |
|
Notes: |
The returned object can only be trusted if the corresponding status code is ‘success’. |
Table 3.9 Status codes for the ‘readLineItemIdsWithLineItemType’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the LineItem identifiers have been read from the target system. |
|
‘CodeMajor=Success’
‘Severity=Status’ |
The read request has been fully and successfully implemented by the target system and no LineItem identifiers were found. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invalidlineitemtype’ |
An invalid LineItemType value has been supplied. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=targetreadfailure’ |
The target system has detected an error in the LineItem database and so cannot return the data. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
3.2.9 ReadLineItemIdsForCourseSection() Operation
|
Name: |
readLineItemIdsForCourseSection |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.10 and A.2. |
|
Supplied (in) Parameters: |
lineItemSourcedId:GUID – the identifier of the CourseSection object whose LineItem sourcedIds are required. |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of SourcedIds for all of the LineItem objects for the CourseSection in the target’s Course database. |
|
Behavior: |
The target system must return all of the LineItem SourcedIds for the identified CourseSection object. If the object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. |
|
Notes: |
None. |
Table 3.10 Status codes for the ‘readLineItemIdsForCourseSection’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the LineItem identifiers have been read from the target system. |
|
‘CodeMajor=Success’
‘Severity=Status’ |
The read request has been fully and successfully implemented by the target system and no LineItem identifiers were found. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The CourseSection object identifier is unknown in the target system and so the object could not be read. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=targetreadfailure’ |
The target system has detected an error in the LineItem object and so cannot return the data. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=incompletedata’ |
Some mandatory part of the data has been detected as missing by the source system. |
3.2.10 ReadLineItemIdsFromSavePoint() Operation
|
Name: |
readLineItemIdsFromSavePoint |
|
Return Function Parameter: |
statusInfo:StatusInfo – the status of the read request. The permitted status codes are given in Tables 3.11 and A.2. |
|
Supplied (in) Parameters: |
fromSavePoint:SequenceIdentifier – the reference point from which all of the changed identifier actions are to be read. This is the value in the source system. |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of identifiers of the LineItem objects stored on the target. savePoint:SequenceIdentifier – the value of the reference point counter in the target system. |
|
Behavior: |
When the source issues the ‘readLineItemIdsFromSavePoint’ the target returns the set of SourcedIds that have been altered from the defined reference point, supplied by the source, to the latest reference point identified in the target. If the reference counter in the source is greater than that in the target then an error code is returned and the target value for the reference point is returned. |
|
Notes: |
If no SourcedIds have been allocated then the returned data set is empty and the success status code returned. |
Table 3.11 Status codes for the ‘readLineItemIdsFromSavePoint’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the identified LineItem identifiers have been read from the target system. |
|
‘CodeMajor=Success’
‘Severity=Status’ |
The read request has been fully and successfully implemented by the target system and no LineItem identifiers were found. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=savepointerror’ |
An error has occurred in the processing of the save-point identifier information making it impossible to read the correct objects from the database. |
|
‘CodeMajor=Failure’
‘Severity=Status’ |
The value of the save point reference from the source was later than that of the target system. No identifiers have been returned. The target system savepoint value has been updated to that supplied by the source system. |
3.2.11 ReadLineItems() Operation
|
Name: |
readLineItems |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.12 and A.2. |
|
Supplied (in) Parameters: |
sourcedIdSet:GUIDSet – the set of identifiers of the LineItem objects to be read. |
|
Returned (out) Parameters: |
lineItemRecordSet:LineItemRecordSet – the set of lineItem records. savePoint:SequenceIdentifier – the value of the reference point counter in the target system. |
|
Behavior: |
When the source issues the ‘readLineItems’ request the target is charged with retrieving the identified set of objects from its database. The associated read savePoint reference is updated and returned. If an object identified by the supplied set of SourcedIds cannot be located then the request is rejected and a partial success code is returned for the operation. The target is responsible for ensuring that the records contain valid data. The target should attempt to successfully complete as much of the request as possible. |
|
Notes: |
A lineItem object is only present in the data structure if it has been located in the target system. The enclosed data may result in a long response message. |
Table 3.12 Status codes for the ‘readLineItems’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the object identifiers have been read from the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
3.2.12 ReadLineItemsFromSavePoint() Operation
|
Name: |
readLineItemsFromSavePoint |
|
Return Function Parameter: |
statusInfo:StatusInfo – the status of the read request. The permitted status codes are given in Tables 3.13 and B.2. |
|
Supplied (in) Parameters: |
fromSavePoint:SequenceIdentifier – the reference point from which all of the changed identifier actions are to be read. This is the value in the source system. |
|
Returned (out) Parameters: |
lineItemRecordSet:LineItemRecordSet – the set of group records. savePoint:SequenceIdentifier – the value of the reference point counter in the target system. |
|
Behavior: |
When the source issues the ‘readLineItemsFromSavePoint’ request the target is charged with reading the objects that have been altered from the defined reference point. If the reference counter in the source is greater than that in the target then an error code is returned and the target value for the reference point is returned. |
|
Notes: |
If no objects have been allocated then the return message will be empty. The enclosed data may result in a long response message. |
Table 3.13 Status codes for the ‘readLineItemsFromSavePoint’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the identified LineItem object has been read from the target system. |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=partialreadfail’ |
Some of the LineItem object identifiers are unknown in the target system and so those objects could not be read. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=savepointerror’ |
An error has occurred in the processing of the save-point identifier information making it impossible to read the correct objects from the database. |
|
‘CodeMajor=Failure’
‘Severity=Status’ |
The value of the save point reference from the source was later than that of the target system. No identifiers have been returned. The target system savepoint value has been updated to that supplied by the source system. |
|
‘CodeMajor=Success’ ‘Severity=Warning’ ‘CodeMinor=partialdatareturn’ |
The target has only returned a subset of the data object e.g. only the mandatory parts. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=targetreadfailure’ |
The target system has detected an error in the stored LineItem object and so cannot return the data. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=incompletedata’ |
Some mandatory part of the data has been detected as missing by the target system. |
3.2.13 ReplaceLineItem() Operation
|
Name: |
replaceLineItem |
|
Return Function Parameter: |
statusInfo:StatusInfo – the status of the replace request. The permitted status codes are given in Tables 3.14 and A.2. |
|
Supplied (in) Parameters: |
sourcedId:GUID – the identifier of the LineItem object to be replaced. lineItemRecord:LineItemRecord – the LineItem data that is to be stored in the object. |
|
Returned (out) Parameters: |
None. |
|
Behavior: |
When the source issues the ‘replaceLineItem’ request the target is charged with writing the supplied information into the identified record. If any part of the write fails e.g. due to partial invalid data then the whole request is rejected and the record is left in its original state. This is a destructive write-over operation of the entire LineItem object. This is equivalent to a ‘createLineItem’ but for an object that already exists. If the object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. The reference counter for the object is incremented by one in the target system. |
|
Notes: |
The source is responsible for determining the reason of the failure. |
Table 3.14 Status codes for the ‘replaceLineItem’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The replace request has been fully and successfully implemented by the target system and the identified object has been changed on the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The object identifier is unknown in the target system and so the object could not be changed. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the supplied data was detected as invalid by the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=incompletedata’ |
Some mandatory part of the data has been detected as missing by the target system. |
|
‘CodeMajor=Success’ ‘Severity=Warning’ ‘CodeMinor=unknownextension’ |
The target cannot process the proprietary extensions that are used in the object’s data model. |
3.2.14 UpdateLineItem() Operation
|
Name: |
updateLineItem |
|
Return Function Parameter: |
StatusInfo – the status of the update request. The permitted status codes are given in Tables 3.15 and A.2. |
|
Supplied (in) Parameters: |
sourcedId:GUID – the identifier of the LineItem object to be updated. lineItemRecord:LineItemRecord – the LineItem data that is to be stored in the object. |
|
Returned (out) Parameters: |
None. |
|
Behavior: |
When the source issues the ‘updateLineItem’ request the target is charged with writing the supplied information into the identified record. If any part of the write fails e.g. due to partial invalid data then the whole request is rejected and the object is left in its original state. This is an additive write operation of all the data fields supplied in the update request and fields not supplied remain unchanged. If a field is constrained with a multiplicity of one then the ‘updateLineItem’ request acts as a replaceLineItem’ request for that field. If the object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. The reference counter for the object is incremented by one in the target system. |
|
Notes: |
The source is responsible for determining the reason of the failure. |
Table 3.15 Status codes for the ‘updateLineItem’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The update request has been fully and successfully implemented by the target system and the identified object has been changed on the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The object identifier is unknown in the target system and so the object could not be updated. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the supplied data was detected as invalid by the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=incompletedata’ |
Some mandatory part of the data has been detected as missing by the target system. |
|
‘CodeMajor=Success’ ‘Severity=Warning’ ‘CodeMinor=unknownextension’ |
The source cannot process the proprietary extensions that are used in the object’s data model. |
3.2.15 DiscoverLineItemIds() Operation
|
Name: |
discoverLineItemIds |
|
Return Function Parameter: |
statusInfo:StatusInfo – the status of the update request. The permitted status codes are given in Tables 3.16 and A.2. |
|
Supplied (in) Parameters: |
queryObject:QueryObject – this is the query/filter instruction that is to be applied by the target to discover the corresponding LineItem objects. |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of identifiers of the LineItem objects whose content conform to the query conditions. |
|
Behavior: |
When the source issues the ‘discoverLineItemIds’ the target applies the query instructions to the set of LineItem objects and returns the set of SourcedIds that uphold the query. If no LineItem objects have the required properties the returned data set is empty and the success status code returned. If the target does not understand or cannot apply the requested query then an error status is returned. |
|
Notes: |
The internal structure of this QueryObject is undefined (it is should be treated as a String). Later versions of this specification will look at the established best practices for clarification on the use of this operation. |
Table 3.16 Status codes for the ‘discoverLineItemIds’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The discover request has been fully and successfully implemented by the target system and the identifiers of the objects that uphold the search criteria are returned. |
|
‘CodeMajor=Success’
‘Severity=Status’ |
The discover request has been fully and successfully implemented by the target system and no LineItem object identifiers were found. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownquery’ |
The query/filter instruction is unknown in the target system and so the query/filter could not be executed. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
3.2.16 ChangeLineItemIdentifier() Operation
|
Name: |
changeLineItemIdentifier |
|
Return Function Parameter: |
StatusInfo – the status of the update request. The permitted status codes are given in Tables 3.17 and A.2. |
|
Supplied (in) Parameters: |
sourcedId:GUID – the identifier of the LineItem object to be changed. newSourcedId:GUID – the new identifier to be allocated to the ‘lineItem’ object. |
|
Returned (out) Parameters: |
None. |
|
Behavior: |
When the source issues the ‘changeLineItemIdentifier’ request the target is charged with replacing the original SourcedId with the new supplied SourcedId. All Membership entries must be similarly changed. All further references to the object must use the new ‘sourcedId’ otherwise an ‘unknown’ object failure status code is returned. If the object identified by the supplied ‘SourcedId’ cannot be located then the request is rejected and the appropriate failure code is returned. |
|
Notes: |
The reference pointer value remains unchanged. |
Table 3.17 Status codes for the ‘changeLineItemIdentifier’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The change identifier request has been fully and successfully implemented by the target system and the LineItem object SourcedId has been changed on the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=idallocinusefail’ |
The target could not allocate the new unique SourcedId to the LineItem object as the identifier is already in use. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The current LineItem SourcedId identifier is unknown in the target system and so the object identifier could not be changed. |
3.3 ResultManager Interface Description
The ResultManager interface class describes the operations that are permitted on Result objects (as shown Figure 3.2). The set of operations are summarized in Table 3.18.
Figure 3.2 OutcomesManagementService ResultManager interface definitions.
Table 3.18 Summary of operations for ResultManager.
|
Operation |
Description |
|
createResult |
To request the creation of a populated Result object on the target system where the source allocates the unique SourcedId. The Result object is tied to a LineItem object. |
|
createByProxyResult |
To request the creation of a populated Result object on the target system where the target allocates the unique SourcedId. The Result object is tied to a LineItem object. |
|
deleteResult |
To request the deletion of a Result object. The Result object is deleted but the associated ResultValue and LineItems remain. |
|
readResult |
To read the full contents of the identified Result object. The target must return all of the data it has for the identified Result object. |
|
readAllResultIds |
To obtain the set of SourcedIds assigned to Result objects. |
|
readResultIdsForPerson |
To obtain the set of SourcedIds for the Result objects which are associated with a particular Person object. |
|
readResultIdsForLineItem |
To obtain the set of SourcedIds for the Result objects which are associated with a particular LineItem object. |
|
readResultIdsForCourseOffering |
To obtain the set of SourcedIds for the Result objects which are associated with a particular CourseOffering object. |
|
readResultIdsForCourseSection |
To obtain the set of SourcedIds for the Result objects which are associated with a particular CourseSection object. |
|
readResultIdsForCourseSectionWithStatus |
To obtain the set of SourcedIds for the Result objects that are associated with a particular CourseSection object and have results of a particular status. |
|
readResultIdsForLineItemWithLineItemType |
To obtain the SourcedIds for the Result objects that are associated with a LineItem that has a particular LineItemType state. |
|
readResultIdsFromSavePoint |
To obtain the set of identifiers for Result objects which have been altered since the requested reference point. The reference point is set as ‘zero’ at creation and incremented after every write operation. |
|
readResults |
To obtain the Result objects for a defined set of identifiers. This results in a single transaction that may require the exchange of a large volume of data. |
|
readResultsFromSavePoint |
To obtain the set of Result objects which have been altered since the requested reference point. The reference point is set as ‘zero’ at creation and incremented after every write operation. This results in a single transaction that may require the exchange of a large volume of data in the response message. |
|
updateResult |
To add content to the identified Result object. The target must write the new data into the Result object. This is an additive operation. |
|
replaceResult |
To replace the content of the identified Result object. The target must write the new data into the Result object. This is a destructive write-over of all of the original information. |
|
discoverResultIds |
To obtain the set of SourcedIds for Result objects whose properties agree with those defined in the query/filter. |
|
changeResultIdentifier |
To change the SourcedId of a Result object. |
3.3.1 CreateResult() Operation
|
Name: |
createResult |
|
Return Function Parameter: |
StatusInfo – the status of the creation request. The permitted status codes are defined in Tables 3.19 and A.2. |
|
Supplied (in) Parameters: |
sourcedId:GUID – the sourcedId allocated by the source system. This is the identifier that must also be assigned within the target system. lineItemSourcedId:GUID – the sourcedId of the LineItem object to which the Result object is assigned. resultRecord:ResultRecord – the Result data that is to be stored in the new object. |
|
Returned (out) Parameters: |
None. |
|
Behavior: |
When the source issues the ‘createResult’ request the target is instructed to create the populated Result object and to allocate that structure the SourcedId passed by the source. If the supplied SourcedId has already been allocated to another object then the request is rejected and the appropriate failure code is returned. The reference point identifier is set to ‘zero’ for the Result object in both the source and target. The Result object is assigned to the identified LineItem object. If an invalid sourcedId is given for the LineItem object then an error code is returned and the Result object is not created. |
|
Notes: |
This request contains the initial content for the Result object. More content can be added/replaced using the ‘updateResult’ and/or ‘replaceResult’ requests. |
Table 3.19 Transitions associated with the ‘createResult’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The creation request has been fully and successfully implemented by the target system and the object has been created with the supplied SourcedId. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=idallocinusefail’ |
The target could not allocate the unique SourcedId to the object as the identifier is already in use. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The LineItem object identifier is unknown in the target system and so the Result object could not be created. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=overflowfail’ |
The target could not create the Result record due to lack of target allocation memory. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the supplied data was detected as invalid by the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=incompletedata’ |
Some mandatory part of the data has been detected as missing by the target system. |
|
‘CodeMajor=Success’ ‘Severity=Warning’ ‘CodeMinor=partialdatastorage’ |
The target has only stored a subset of the sent data record e.g. only the mandatory parts. |
|
‘CodeMajor=Success’ ‘Severity=Warning’ ‘CodeMinor=unknownextension’ |
The target cannot process the proprietary extensions that are used in the object’s data model. |
3.3.2 CreateByProxyResult() Operation
|
Name: |
createByProxyResult |
|
Return Function Parameter: |
StatusInfo – the status of the creation request. The permitted status codes are defined in Tables 3.20 and A.2. |
|
Supplied (in) Parameters: |
lineItemSourcedId:GUID – the sourcedId of the LineItem object to which the Result object is assigned. resultrecord:ResultRecord – the Result data that is to be stored in the new object. |
|
Returned (out) Parameters: |
sourcedId:GUID – the identifier allocated by the target to the newly created Result object. |
|
Behavior: |
When the source issues the ‘createByProxyResult’ request the target is instructed to create the populated Result object and to allocate that record a unique SourcedId. The reference point identifier is set to ‘zero’ for the Result object in both the source and target. The Result object is assigned to the identified LineItem object. If an invalid sourcedId is given for the LineItem object then an error code is returned and the Result object is not created. |
|
Notes: |
This request contains the initial content for the Result object. More content can be added/replaced using the ‘updateResult’ and/or ‘replaceResult’ requests. |
Table 3.20 Status codes for the ‘createByProxyResult’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The creation request has been fully and successfully implemented by the target system and the object has been created with the SourcedId supplied by the target. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=idallocfail’ |
The target could not allocate a unique SourcedId to the object because there are no more spare identifiers available. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The LineItem object identifier is unknown in the target system and so the Result object could not be created. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=overflowfail’ |
The target could not create the object due to lack of target allocation memory. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the supplied data was detected as invalid by the source system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=incompletedata’ |
Some mandatory part of the data has been detected as missing by the target system. |
|
‘CodeMajor=Success’ ‘Severity=Warning’ ‘CodeMinor=partialdatastorage’ |
The target has only stored a subset of the sent data record e.g. only the mandatory parts. |
|
‘CodeMajor=Success’ ‘Severity=Warning’ ‘CodeMinor=unknownextension’ |
The target cannot process the proprietary extensions that are used in the object’s data model. |
3.3.3 DeleteResult() Operation
|
Name: |
deleteResult |
|
Return Function Parameter: |
StatusInfo – the status of the deletion request. The permitted status codes are defined in Tables 3.21 and A.2. |
|
Supplied (in) Parameters: |
sourcedId:GUID – the identifier to be used by the target to identify the Result object. |
|
Returned (out) Parameters: |
None. |
|
Behavior: |
When the source issues the ‘deleteResult’ request the target is instructed to delete the identified Result object and to remove any associations. If the object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. |
|
Notes: |
Deletion of the Result object does not necessarily result in the destruction of the data within the server. The true state of the data in the target is unknown. |
Table 3.21 Status codes for the ‘deleteResult’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The deletion request has been fully and successfully implemented by the target system and the object has been deleted. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The object identifier is unknown in the target system and so the object could not be deleted. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor= deletefailure’ |
The target system has not been able to delete the identified object. |
3.3.4 ReadResult() Operation
|
Name: |
readResult |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.22 and A.2. |
|
Supplied (in) Parameters: |
sourcedId:GUID – the identifier of the Result object to be read. |
|
Returned (out) Parameters: |
resultRecord:ResultRecord– the Result data that is read from the object. |
|
Behavior: |
When the source issues the ‘readResult’ request the target is charged with retrieving the identified record from its database and returning this data to the source. The target is responsible for ensuring that the object contains valid data. If the object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. |
|
Notes: |
The returned Result object can only be trusted if the corresponding status code is ‘success’. |
Table 3.22 Status codes for the ‘readResult’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the identified object has been read from the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The object identifier is unknown in the target system and so the object could not be read. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=targetreadfailure’ |
The target system has detected an error in the stored object and so cannot return the data. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=incompletedata’ |
Some mandatory part of the data has been detected as missing by the source system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownextension’ |
The source cannot process the proprietary extensions that are used in the object’s data model. |
3.3.5 ReadAllResultIds() Operation
|
Name: |
readAllResultIds |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.23 and A.2. |
|
Supplied (in) Parameters: |
None. |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of SourcedIds for all of the Result objects in the target’s Result database. |
|
Behavior: |
When the source issues the ‘readAllResultIds’ request the target is charged with returning the SourcedIds of all of the Result identifiers in its Result database. |
|
Notes: |
The returned set of SourcedIds may or may not have completed results. If no SourcedIds have been allocated then the returned data set is empty and the success status code returned. Note that, in general, the set of Result objects will not be assigned to the same LineItem. |
Table 3.23 Status codes for the ‘readAllResultIds’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the object identifiers have been read from the target system. |
|
‘CodeMajor=Success’
‘Severity=Status’ |
The read request has been fully and successfully implemented by the target system and no Result object identifiers were found. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
3.3.6 ReadResultIdsForPerson() Operation
|
Name: |
readResultIdsForPerson |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.24 and A.2. |
|
Supplied (in) Parameters: |
sourcedId:GUID – the identifier of the Person object whose Result sourcedIds are required. |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of SourcedIds for all of the Result objects for the Person in the target’s Result database. |
|
Behavior: |
The target system must return all of the Result SourcedIds for the identified Person object. If the object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. |
|
Notes: |
None. |
Table 3.24 Status codes for the ‘readResultIdsForPerson’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the object identifiers have been read from the target system. |
|
‘CodeMajor=Success’
‘Severity=Status’ |
The read request has been fully and successfully implemented by the target system and no Result object identifiers were found. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The Person object identifier is unknown in the target system and so the associated Result could not be identified. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=targetreadfailure’ |
The target system has detected an error in the Outcomes database and so cannot return the data. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
3.3.7 ReadResultIdsForLineItem() Operation
|
Name: |
readResultIdsForLineItem |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.25 and A.2. |
|
Supplied (in) Parameters: |
sourcedId:GUID – the identifier of the LineItem object whose Result sourcedIds are required. |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of SourcedIds for all of the Result objects for the LineItem in the target’s Outcomes database. |
|
Behavior: |
The target system must return all of the Result SourcedIds for the identified LineItem object. The Result identifiers are read directly from the LineItem data model. If the object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. |
|
Notes: |
The returned object can only be trusted if the corresponding status code is ‘success’. |
Table 3.25 Status codes for the ‘readResultIdsForLineItem’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the identified object has been read from the target system. |
|
‘CodeMajor=Success’
‘Severity=Status’ |
The read request has been fully and successfully implemented by the target system and no Result object identifiers were found. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The LineItem object identifier is unknown in the target system and so the object could not be read. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=targetreadfailure’ |
The target system has detected an error in the LineItem object and so cannot return the data. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
3.3.8 ReadResultIdsForCourseOffering() Operation
|
Name: |
readResultIdsForCourseOffering |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.26 and A.2. |
|
Supplied (in) Parameters: |
offeringSourcedId:GUID – the identifier of the CourseOffering object whose Result SourcedIds are required. |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of SourcedIds for all of the Result objects for the CourseOffering in the target’s Course database. |
|
Behavior: |
The target system must return all of the Result SourcedIds for the identified CourseOffering object. This information is located by finding the LineItems that are associated with the identified CourseOffering. The corresponding Result identifiers listed in the LineItems are then returned. If the object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. |
|
Notes: |
None. |
Table 3.26 Status codes for the ‘readResultIdsForCourseOffering’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the object identifiers have been read from the target system. |
|
‘CodeMajor=Success’
‘Severity=Status’ |
The read request has been fully and successfully implemented by the target system and no Result object identifiers were found. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The CourseOffering object identifier is unknown in the target system and so the object could not be read. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=targetreadfailure’ |
The target system has detected an error in the object databases and so cannot return the data. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
3.3.9 ReadResultIdsForCourseSection() Operation
|
Name: |
readResultIdsForCourseSection |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.27 and A.2. |
|
Supplied (in) Parameters: |
sectionSourcedId:GUID – the identifier of the CourseSection object whose Result SourcedIds are required. |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of SourcedIds for all of the Result objects for the CourseSection in the target’s Course database. |
|
Behavior: |
The target system must return all of the Result SourcedIds for the identified CourseSection object. This information is located by finding the LineItems that are associated with the identified CourseSection. The corresponding Result identifiers listed in the LineItems are then returned. If the CourseSection object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. |
|
Notes: |
None. |
Table 3.27 Status codes for the ‘readResultIdsForCourseSection’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the object identifiers have been read from the target system. |
|
‘CodeMajor=Success’
‘Severity=Status’ |
The read request has been fully and successfully implemented by the target system and no Result object identifiers were found. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The CourseSection object identifier is unknown in the target system and so the object could not be read. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=targetreadfailure’ |
The target system has detected an error in the object databases and so cannot return the data. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
3.3.10 ReadResultIdsForCourseSectionWthStatus() Operation
|
Name: |
readResultIdsForCourseSectionWithStatus |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.28 and A.2. |
|
Supplied (in) Parameters: |
sectionSourcedId:GUID – the identifier of the CourseSection object whose Result SourcedIds are required. resultStatus:ResultStatus – the status of the Result of the SourcedIds required. This will be from an agreed vocabulary |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of SourcedIds for all of the Result objects for the CourseSection with the required status in the target’s CourseSection database. |
|
Behavior: |
The target system must return all of the Result SourcedIds, of the appropriate status, for the identified CourseSection object. This information is located by finding the LineItems that are associated with the identified CourseSection. The corresponding Result identifiers listed in the LineItems with the corresponding status are then returned. If the CourseSection object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. |
|
Notes: |
None. |
Table 3.28 Status codes for the ‘readResultIdsForCourseSectionWithStatus’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the identified object has been read from the target system. |
|
‘CodeMajor=Success’
‘Severity=Status’ |
The read request has been fully and successfully implemented by the target system and no Result object identifiers were found. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The CourseSection object identifier is unknown in the target system and so the object could not be read. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=targetreadfailure’ |
The target system has detected an error in the object database and so cannot return the data. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
The defined status for the Result objects is unknown in the target system. |
3.3.11 ReadResultIdsForLineItemWithLineItemType() Operation
|
Name: |
readResultIdsForLineItemWithLineItemType |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.29 and A.2. |
|
Supplied (in) Parameters: |
contextSourcedId:GUID – the identifier of the LineItem object whose Result SourcedIds are required. lineItemType:LineItemType – the type of the LineItems required for inspection. This will be from an agreed vocabulary. resultStatus:ResultStatus – the status of the Result of the SourcedIds required. This will be from an agreed vocabulary. |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of SourcedIds for all of the Result objects for the LineItem with the required LineItemType in the target’s Outcomes database. |
|
Behavior: |
The target system must return all of the Result SourcedIds for the identified LineItem object with the relevant LineItemType. This information is located by finding the LineItems that are associated with the identified. The corresponding Result identifiers listed in the LineItems with the corresponding LineItemType are then returned. If the LineItem object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. |
|
Notes: |
None. |
Table 3.29 Status codes for the ‘readResultIdsForLineItemWithLineItemType’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the identified object has been read from the target system. |
|
‘CodeMajor=Success’
‘Severity=Status’ |
The read request has been fully and successfully implemented by the target system and no Result object identifiers were found. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The LineItem object identifier is unknown in the target system and so the object could not be read. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=targetreadfailure’ |
The target system has detected an error in the object database and so cannot return the data. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invalidlineitemtype’ |
The defined LineItemType for the LineItem object is unknown in the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
The defined ResultStatus for the LineItem object is unknown in the target system. |
3.3.12 ReadResultIdsFromSavePoint() Operation
|
Name: |
readResultIdsFromSavePoint |
|
Return Function Parameter: |
statusInfo:StatusInfo – the status of the read request. The permitted status codes are given in Tables 3.30 and A.2. |
|
Supplied (in) Parameters: |
fromSavePoint:SequenceIdentifier – the reference point from which all of the changed identifier actions are to be read. This is the value in the source system. |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of identifiers of the Result objects stored on the target. savePoint:SequenceIdentifier – the value of the reference point counter in the target system. |
|
Behavior: |
When the source issues the ‘readResultIdsFromSavePoint’ the target returns the set of SourcedIds that have been altered from the defined reference point, supplied by the source, to the latest reference point identified in the target. If the reference counter in the source is greater than that in the target then an empty set is returned for the SourcedIds and the target value for the reference point is returned. |
|
Notes: |
If no SourcedIds have been allocated then the returned data set is empty and the success status code returned. |
Table 3.30 Status codes for the ‘readResultIdsFromSavePoint’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the identified Result object identifiers have been read from the target system. |
|
‘CodeMajor=Success’
‘Severity=Status’ |
The read request has been fully and successfully implemented by the target system and no Result object identifiers were found. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=savepointerror’ |
An error has occurred in the processing of the save-point identifier information making it impossible to read the correct objects from the database. |
|
‘CodeMajor=Failure’
‘Severity=Status’ |
The value of the save point reference from the source was later than that of the target system. No identifiers have been returned. The target system savepoint value has been updated to that supplied by the source system. |
3.3.13 ReadResults() Operation
|
Name: |
readResults |
|
Return Function Parameter: |
StatusInfo – the status of the read request. The permitted status codes are defined in Tables 3.31 and A.2. |
|
Supplied (in) Parameters: |
sourcedIdSet:GUIDSet – the set of identifiers of the Result objects to be read. |
|
Returned (out) Parameters: |
resultRecordSet:ResultRecordSet – the set of result records. savePoint:SequenceIdentifier – the value of the reference point counter in the target system. |
|
Behavior: |
When the source issues the ‘readResults’ request the target is charged with retrieving the identified set of objects from its database. The associated read savePoint reference is updated and returned. If the object identified by the supplied SourcedId cannot be located then the request is rejected and a partial success code is returned for the operation. The target is responsible for ensuring that the records contain valid data. The target should attempt to successfully complete as much of the request as possible. |
|
Notes: |
A result object is only present in the data structure if it has been located in the target system. The enclosed data may result in a long response message. |
Table 3.31 Status codes for the ‘readResults’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the object identifiers have been read from the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
3.3.14 ReadResultsFromSavePoint() Operation
|
Name: |
readLineItemsFromSavePoint |
|
Return Function Parameter: |
statusInfo:StatusInfo – the status of the read request. The permitted status codes are given in Tables 3.32 and A.2. |
|
Supplied (in) Parameters: |
fromSavePoint:SequenceIdentifier – the reference point from which all of the changed identifier actions are to be read. This is the value in the source system. |
|
Returned (out) Parameters: |
resultRecordSet:ResultRecordSet – the set of result records. savePoint:SequenceIdentifier – the value of the reference point counter in the target system. |
|
Behavior: |
When the source issues the ‘readResultsFromSavePoint’ request the target is charged with reading the objects that have been altered from the defined reference point. If the reference counter in the source is greater than that in the target then an error code is returned and the target value for the reference point is returned. |
|
Notes: |
If no objects have been allocated then the return message will be empty. The enclosed data may result in a long response message. |
Table 3.32 Status codes for the ‘readResultsFromSavePoint’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The read request has been fully and successfully implemented by the target system and the identified Result object has been read from the target system. |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=partialreadfail’ |
Some of the Result object identifiers are unknown in the target system and so those objects could not be read. |
|
‘CodeMajor=Success’ ‘Severity=Warning’ ‘CodeMinor=partialdatareturn’ |
The target has only returned a subset of the data object e.g. only the mandatory parts. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=savepointerror’ |
An error has occurred in the processing of the save-point identifier information making it impossible to read the correct objects from the database. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=targetreadfailure’ |
The target system has detected an error in the stored Result object and so cannot return the data. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=incompletedata’ |
Some mandatory part of the data has been detected as missing by the target system. |
3.3.15 ReplaceResult() Operation
|
Name: |
replaceResult |
|
Return Function Parameter: |
statusInfo:StatusInfo – the status of the replace request. The permitted status codes are given in Tables 3.33 and A.2. |
|
Supplied (in) Parameters: |
sourcedId:GUID – the identifier of the Result object to be replaced. resultRecord:ResultRecord – the Result data that is to be stored in the object. |
|
Returned (out) Parameters: |
None. |
|
Behavior: |
When the source issues the ‘replaceResult’ request the target is charged with writing the supplied information into the identified record. If any part of the write fails e.g. due to partial invalid data then the whole request is rejected and the record is left in its original state. This is a destructive write-over operation of the entire Result object. This is equivalent to a ‘createResult’ but for an object that already exists. If the object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. The reference counter for the object is incremented by one in the target system. |
|
Notes: |
The source is responsible for determining the reason of the failure. |
Table 3.33 Status codes for the ‘replaceResult’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The replace request has been fully and successfully implemented by the target system and the identified object has been changed on the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The object identifier is unknown in the target system and so the object could not be changed. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=incompletedata’ |
Some mandatory part of the data has been detected as missing by the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownextension’ |
The target cannot process the proprietary data model extensions used in the object. |
3.3.16 UpdateResult() Operation
|
Name: |
updateResult |
|
Return Function Parameter: |
StatusInfo – the status of the update request. The permitted status codes are given in Tables 3.34 and A.2. |
|
Supplied (in) Parameters: |
sourcedId:GUID – the identifier of the Result object to be updated. resultRecord:ResultRecord – the Result data that is to be stored in the object. |
|
Returned (out) Parameters: |
None. |
|
Behavior: |
When the source issues the ‘updateResult’ request the target is charged with writing the supplied information into the identified record. If any part of the write fails e.g. due to partial invalid data then the whole request is rejected and the record is left in its original state. This is an additive write operation of all the data fields supplied in the update request and fields not supplied remain unchanged. If a field is constrained with a multiplicity of one then the ‘updateResult’ request acts as a replaceResult’ request for that field. If the object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. The reference counter for the object is incremented by one in the target system. |
|
Notes: |
The source is responsible for determining the reason of the failure. |
Table 3.34 Status codes for the ‘updateResult’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The update request has been fully and successfully implemented by the target system and the identified object has been changed on the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The object identifier is unknown in the target system and so the object could not be updated. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=incompletedata’ |
Some mandatory part of the data has been detected as missing by the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownextension’ |
The target cannot process the proprietary data model extensions used in the object. |
3.3.17 DiscoverResultIds() Operation
|
Name: |
discoverResultIds |
|
Return Function Parameter: |
statusInfo:StatusInfo – the status of the discover request. The permitted status codes are given in Tables 3.35 and A.2. |
|
Supplied (in) Parameters: |
queryObject:QueryObject – this is the query/filter instruction that is to be applied by the target to discover the corresponding Result objects. |
|
Returned (out) Parameters: |
sourcedIdSet:GUIDSet – the set of identifiers of the Result objects whose content conform to the query conditions. |
|
Behavior: |
When the source issues the ‘discoverResultIds’ the target applies the query instructions to the set of Result objects and returns the set of SourcedIds that uphold the query/filter. If no Result objects have the required properties the returned data set is empty and the success status code returned. If the target does not understand or cannot apply the requested query/filter then an error status is returned. |
|
Notes: |
The internal structure of this QueryObject is undefined (it is should be treated as a String). Later versions of this specification will look at the established best practices for clarification on the use of this operation. |
Table 3.35 Status codes for the ‘discoverResultIds’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The discover request has been fully and successfully implemented by the target system and the object identifiers for the Results that uphold the search criteria. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownquery’ |
The query/filter instruction is unknown in the target system and so the query could not be executed. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=invaliddata’ |
Part or all of the returned data was detected as invalid by the source system. |
3.3.18 ChangeResultIdentifier() Operation
|
Name: |
changeResultIdentifier |
|
Return Function Parameter: |
StatusInfo – the status of the update request. The permitted status codes are given in Tables 3.36 and A.2. |
|
Supplied (in) Parameters: |
sourcedId:GUID – the identifier of the Result object to be changed. newSourcedId:GUID – the new identifier to be allocated to the Result object. |
|
Returned (out) Parameters: |
None. |
|
Behavior: |
When the source issues the ‘changeResultIdentifier’ request the target is charged with replacing the original SourcedId with the new supplied SourcedId. All further references to the object must use the new SourcedId otherwise an ‘unknown’ object failure status code is returned. If the object identified by the supplied SourcedId cannot be located then the request is rejected and the appropriate failure code is returned. |
|
Notes: |
The reference pointer value remains unchanged. |
Table 3.36 Status codes for the ‘changeResultIdentifier’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The change identifier request has been fully and successfully implemented by the target system and the Result object SourcedId has been changed on the target system. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=idallocinusefail’ |
The target could not allocate the new unique ‘identifier’ to the Result object as the identifier is already in use. |
|
‘CodeMajor=Failure’ ‘Severity=Status’ ‘CodeMinor=unknownobject’ |
The current Result SourcedId identifier is unknown in the target system and so the object identifier could not be changed. |
3.4 ResultValueManager Interface Description
The ResultValueManager interface class describes the operations that are permitted on ResultValue objects (as shown Figure 3.3). The set of operations are summarized in Table 3.37.
Figure 3.3 OutcomesManagementService ResultValueManager interface definitions.
Table 3.37 Summary of operations for ResultValueManager.
|
Operation |
Description |
|
createResultValue |
To request the creation of a populated ResultValue object on the target system where the source is responsible for the allocation of the unique SourcedId. |
|
createByProxyResultValue |
To request the creation of a populated ResultValue object on the target system where the target is responsible for the allocation of the unique SourcedId. |
|
deleteResultValue |
To request the deletion of a ResultValue object. The ResultValue object is deleted along with all of its associated relationships. |
|
readResultValue |
To read the full contents of the identified ResultValue object. The target must return all of the data it has for the identified ResultValue object. |
|
readAllResultValueIds |
To obtain the set of SourcedIds that have been assigned to ResultValue objects. |
|
readResultValueIdForLineItem |
To obtain the SourcedId for the ResultValue object which has been associated with a particular LineItem object. |
|
readResultValueIdForResult |
To obtain the SourcedId for the ResultValue object which is associated with a particular Result object. |
|
readResultValueIdsFromSavePoint |
To obtain the set of identifiers for ResultValue objects which have been altered since the requested reference point. The reference point is set as ‘zero’ at creation and incremented after every write operation. |
|
readResultValues |
To obtain the ResultValue objects for a defined set of identifiers. This results in a single transaction that may require the exchange of a large volume of data in the response message. |
|
readResultValuesFromSavePoint |
To obtain the set of ResultValue objects which have been altered since the requested reference point. The reference point is set as ‘zero’ at creation and incremented after every write operation. This results in a single transaction that may require the exchange of a large volume of data in the response message. |
|
updateResultValue |
To write new content into the identified ResultValue object. The target must write the new data into the ResultValue object. This is an additive operation. |
|
replaceResultValue |
To replace the content of the identified ResultValue object. The target must write the new data into the ResultValue object. This is a destructive write-over of all of the original information. |
|
discoverResultValueIds |
To obtain the set of SourcedIds for ResultValue objects whose properties agree with those defined in the query/filter. |
|
changeResultValueIdentifier |
To change the SourcedId for a ResultValue object. |
3.4.1 CreateResultValue() Operation
|
Name: |
createResultValue |
|
Return Function Parameter: |
StatusInfo – the status of the creation request. The permitted status codes are defined in Table 3.38 and A.2. |
|
Supplied (in) Parameters: |
sourcedId:GUID – the sourcedId allocated by the source system. This is the identifier that must also be assigned within the target system. resultValueRecord:ResultValueRecord – the ResultValue data that is to be stored in the new object. |
|
Returned (out) Parameters: |
None. |
|
Behavior: |
When the source issues the ‘createResultValue’ request the target is instructed to create the populated ResultValue object and to allocate that structure the SourcedId passed by the source. If the supplied SourcedId has already been allocated to another object then the request is rejected and the appropriate failure code is returned. The reference point identifier is set to ‘zero’ for the ResultValue object in both the source and target. |
|
Notes: |
This request contains the initial content for the ResultValue object. More content can be added/replaced using the ‘updateResultValue’ and/or ‘replaceResultValue’ requests. |
Table 3.38 Status codes for the ‘createResultValue’ operation.
|
Status Code |
Explanation of the Cause of the Code |
|
‘CodeMajor=Success’ ‘Severity=Status’ ‘CodeMinor=fullsuccess’ |
The creation request has been fully and successfully implemented by the target system and the object has been created with the supplied SourcedId. |