1

[This local archive copy is from the official and canonical URL, http://www.schoolsinterop.org/docs/sifdraft.zip; please refer to the canonical source document if possible.]

Schools Interoperability Framework

^{Specification Document}

Working Draft

September 2, 1998

Revision History

Version	Date	Changed By	Description
1.0	09/02/98	Dianne Kennedy, Manish Sharma	Initial Creation

1 INTRODUCTION *

1.1 Background *

1.2 The Schools Interoperability Framework *

1.3 Scope and deliverables of the Schools Interoperability Framework *

1.4 Membership *

1.5 Relationships with other standards in education *

1.6 Objectives of the Schools Interoperability Framework *

1.7 Overview of the approach *

1.8 The XML Advantage *

1.9 Structure Charts *

1.10 Using Namespaces to solve versioning issues *

1.11 Overview of Remaining Sections *

2 OBJECTS, RELATIONSHIPS and QUERIES *

2.1 Student Object *

2.2 Contact Object *

2.3 Teacher Object *

2.4 School Object *

2.5 Relationships *

2.6 Queries *

2.6.1 Query spanning only one object *

2.6.2 Query spanning multiple objects *

3 MESSAGES and EVENTS *

3.1 Overall Schools Interoperability Framework message Structure *

3.2 K12Event Message *

3.3 Enrollment Change Message *

3.4 Student Update Message *

3.5 Partial Student Update Message *

3.6 Teacher Update Message *

3.7 Partial Teacher Update Message *

3.8 Contact Update Message *

3.9 Partial Contact Update Message *

3.10 School Update Message *

3.11 Partial School Update Message *

ID Change Message *

3.13 K12 Request Message *

3.14 K12 Response Message *

3.15 K12 Subscribe Message *

3.16 K12 Unsubscribe Message *

3.17 K12 Publish Message *

3.18 K12 Unpublish Message *

4 APPLICATION INTERACTION MODES *

4.1 Query/ Response *

4.2 Publish/Subscribe *

APPENDIX A: XML – TAG DOCUMENTATION *

Address *

AptNumber *

AptNumPrefix *

AptNumSuffix *

AptType *

AreaCode *

BirthDate *

ChangedStatus *

ChangeReason *

City *

Complex *

Contact *

ContactID *

ContactName *

ContactUpdate *

County *

Credentials *

Date *

DateHired *

Department *

DistrictNbr *

EffectiveDate *

ElectronicID *

EmployeeID *

EnrollStatusChg *

Error *

Event *

Ext *

FirstName *

Gender *

GradeLvl *

GradYear *

HomeRoom *

IDUpdate *

ImmigrationStatus *

K12Event *

K12Framework *

K12Publish *

K12Request *

K12Response *

K12Subscribe *

K12UnPublish *

K12UnSubscribe *

LastName *

MiddleName *

MsgHead *

MsgID *

NewContactID *

NewSchoolID *

NewStudentID *

NewTeacherID *

Number *

Object *

PartialContactUpdate *

PartialSchoolUpdate *

PartialStudentUpdate *

PartialTeacherUpdate *

PhoneNumber *

PublishHead *

Race *

RecordCount *

Relationship *

RequestHead *

RequestMsgID *

ResponseData *

ResponseHead *

School *

SchoolID *

SchoolName *

SchoolUpdate *

SchoolYear *

Source *

SSN *

State *

Status *

Street *

StreetName *

StreetNumber *

StreetPrefix *

StreetSuffix *

StreetType *

Student *

StudentID *

StudentName *

StudentUpdate *

SubscribeHead *

Teacher *

TeacherID *

TeacherName *

TeacherUpdate *

Time *

XMLQuery *

Zip *

APPENDIX B: XML – TAG REFERENCE *

APPENDIX C: XML DTD *

APPENDIX D: XML – Data Schema *

1 INTRODUCTION

1.1 Background

One of the most pressing problems in the education industry today is that of inter operability. The situation today is that the applications available for schools and districts are either closed systems allowing no programmatic access of data or allow access via proprietary interfaces and data formats.

In the case where these applications are closed systems, the problems is that school personnel spend endless time entering the same data over and over again into multiple applications. A typical example of this is a school that needs to store student demographics information in a student administration application as well as a library management application. If both these applications are closed systems, the only way to enter this information is for someone to manually type it into both systems. This type of redundant data entry is time consuming and error prone. If a student moves and his/her address changes, someone has to go into each one of these systems and manually update the student’s information.

In order to solve some of these redundant data entry problems, a number of vendors provide proprietary interfaces and data formats to allow programmatic exchange of data. This, however, is only a partial solution to the problem. Since every vendor’s interface and data format is different, deploying an interoperable system (made up of diverse applications) at a school or district is often a costly proposition caused by lengthy negotiations among vendors and custom software development. The system is also hard to maintain. Since the interface and data format is defined by one vendor and not by a standards committee, an arbitrary change made by that vendor can cause other applications to function improperly.

Over the past several months there have been a number of meetings with leading education software vendors on the topic of interoperability among the applications in the education industry. The main conclusion from all of these meetings was that the only way to achieve interoperability among these applications was for all the interested parties to come together and define standards that all the vendors would adopt. These standards would define a common data format, naming conventions and rules of interaction among applications and would allow end users to create solutions by mixing and matching different applications. Since these solutions would be created by plugging together modules from different vendors schools and district could create functionally rich solutions offering the degree of customization that they need.

1.2 The Schools Interoperability Framework

The Schools Interoperability Framework is such an effort driven by the leading vendors in the education market. It’s objective is to provide interoperability by defining a common format for the data that needs to be shared among applications (like student demographics, attendance information, grades etc.) and defining a protocol for these applications to interact with one another. The goal of this standard is to move the entire education industry from it’s current state of "application islands" to one where all applications plug and play together and allow open access to their data for creating reports at the district, state and federal levels using internet technologies.

There are a number of benefits to having this type of an industry wide standard. From the end users perspective having the choice of applications that conform to a industry wide standard means that they can put together functionally rich systems using a best of breed approach. Integration and data aggregation at the district and state level becomes easier giving a level of access to information that is not possible today.

1.3 Scope and deliverables of the Schools Interoperability Framework

The Schools Interoperability Framework is a specification that defines standards for the data that is exchanged among the applications in the education industry and the protocol for these applications to interact with one another. It is a broad industry wide initiative addressing the issue of multiple platforms and technologies found in schools and districts today and is not tied to a single vendor or technology. In addition to the standards document itself, other deliverables of the framework include an implementation guide, a sample implementation based on this guide, compliance criteria and certification procedures. In addition to this an SDK will be provide that has the API’s, programmer’s manual and sample code.

1.4 Membership

The scope of this standards initiative is industry wide and not restricted to a particular vendor or technology. As such, membership is open to all interested parties including school, district and state education personnel. For information about participating and/or being a part of the regular mailings, please send e- mail to mailto:info@schoolsinterop.org or visit the web site at http://www.schoolsinterop.org

1.5 Relationships with other standards in education

There has been a lot of good work done in the area of standardization for the education market. Two of the leading efforts are SPEEDE/ExPRESS (and it’s extensions) and EDUCOM IMS.

SPEEDE/EXPRESS is an EDI based standard for the education industry which specifies the transaction sets, data segments and data fields for common transactions that need to occur electronically between schools and districts. These include transactions for student loan requests, student transcript request etc. The Schools Interoperability Framework fully intends to use as much of the SPEEDE/ExPRESS specifications as possible without reinventing definitions of common attributes like codes for gender, ethnicity, grades etc. The following are some of the things that the Schools Interoperability Framework does differently from SPEEDE/ExPRESS.

SPEEDE/ExPRESS definitions are based on traditional EDI represented by fixed transactions sets. Traditional EDI definitions are old technology, they are difficult to modify and costly to implement.. The software needed for traditional EDI relies on expensive VANs (Value Added Network) for transporting the EDI messages from one vendor to another. The Schools Interoperability Framework on the other hand uses XML to represent the objects and messages that need to be exchanged. XML is a structured, flexible, extensible and popular way of exchanging data. It is also standard endorsed by the W3C. There is cheap and standard software available to process XML messages (like IE, Netscape Navigator, other freeware and shareware) and XML data can be transported over the internet and be displayed using thin browser clients.

The Schools Interoperability Framework defines finer grained transactions that related to the day to day operations in a school. For example, it defines the messages that will update all the systems in a school with student demographics information once a new student enrolls, messages to send attendance information to a food service system to prevent a student marked absent from eating lunch and messages to send a student enrollment status change message (like graduation) to a library system so that a student doesn’t check out a library book after graduation.

The Schools Interoperability Framework provides a reference implementation for the "plumbing" that is used by education applications to actually communicate with one another. It also provides compliance criteria so that an applications claiming compliance can be expected to provide a certain level of functionality.

As stated earlier the Schools Interoperability Framework will adopt the SPEEDE/ExPRESS definitions when applicable but representing them in XML rather than traditional EDI.

EDUCOM IMS is a standards effort that relates to metadata standards and online content management. The Schools Interoperability Framework will continue to investigate any synergy that may exist between these two efforts.

1.6 Objectives of the Schools Interoperability Framework

In this section we define the objectives that this standard must meet.

The standard must provide interoperability among the different applications. This is achieved in two ways, one by specifying a standard format for data that needs to be exchanged and two, by specifying the high level mechanisms for the interactions among these applications.
The standard must take into account the diverse range of platforms and technologies used in schools today. This means that the standard must not be defined in a way that it excludes certain platforms and technologies while favoring others. To meet this end, any implementation issues will not be part of the main specification instead will be provided as supplemental implementation guide(s).
The standard should allow for site specific customizations for sites requiring a high degree of customization.
The standard must look into co-operating with other established standards to ensure that any synergy is identified and work is not reinvented.
The standard will not make any assumptions about data ownership. These issues will be decided at the specific site by the ISV’s and districts involved. The technique to customize site specific data ownership issues will be specified in the implementation guide not in the standard specification. An example of site specific data ownership issues is the ownership of attendance data. One site may use a grade book application for attendance whilst another may use a Student information application. Both configurations must be allowed and the technique for configuring the data source for attendance records to be one versus the other is specified in the implementation guide.
This initiative is committed to be market driven. To this end a goal of this effort is to engage the schools and districts extensively to make sure that the most pressing issues are addressed with the right priority and to get validation on the current and future directions of the Framework.

1.7 Overview of the approach

In this section we take a high level look at the approach that has been followed to define the Schools Interoperability Framework. The ideas that form the basis of the framework were developed and refined over the course of several meetings with the representatives of the companies that form the core group. This document is a result of these meetings. The Schools Interoperability Framework will continue to hold these meetings regularly to ensure that the specification is progressing satisfactorily and new ideas are constantly being incorporated keeping in step with the latest innovations in technology and with the changing needs of the marketplace.

The specifications process began by identifying some of the common objects that are exchanged among applications and the relationships that exist among them. The initial objects defined were student, teacher and contact objects. Of all possible relationships among these objects, a subset was identified that would be supported in the Framework. This subset was identified based on the interactions that typically occur among applications. The remaining relationships were discarded. These relationships are used to determine the valid queries that the Framework supports.

After identifying these objects the next thing done was to identify the events that occur on a day to day basis in schools. Some of these included, student enrollment change event (like admission, graduation, transfer etc.) or student update event (like change in home address). Then, the data messages that get exchanged as a result of these events were identified. One of the considerations taken into account was that different applications may require different data fields on the same event. For example, on a student enroll event, Application A may require student address while application B may require student phone number. It was decided that both fields would be sent with this event and the individual applications would supply filters that would extract the field that was of interest to them. In addition to event data messages, other messages like queries, publish and subscribe messages were also defined.

After the objects, events and messages were identified, rigorous modeling techniques were applied to model the data and XML definitions for the objects and messages were created. The resulting XML DTD is the basis of the XML data specification for the Schools Interoperability Framework. The next task was to define the types of interactions that Framework compliant applications would support.

Two types of interactions that need to take place among applications were identified:

The Query/Response interaction: This is the type of interaction where a consumer makes a request for data from a producer and the producer then sends the data back in the form of a message.

Unsolicited Message: In this type of interaction a consumer subscribes to an event. When this event occurs (like a student enrolls) the producer sends the data defined by the corresponding message to the framework. The framework then applies the consumer supplied filter to this message and forwards the filtered data to the consumer. In this context, "framework" refers to the implementation of these specifications.

This is an overview of the approach used in defining the specification for the Schools Interoperability Framework. In subsequent meetings this process may be further refined but the basic idea will still be to define more object, relationships, events and messages thereby increasing the scope of this initiative. The remaining chapters of this specification describe this approach in detail and present the deliverables at the end of each stage. For a mapping of this data model and interactions into a working architecture and API using specific technologies, please refer to the attached Implementation Guide.

1.8 The XML Advantage

This document assumes familiarity with the basic concepts of XML and as such does not attempt to give a detailed explanation of what XML is. Two excellent references for XML are: The XML Handbook by Charles Goldfarb & Paul Prescod and Presenting XML by Richard Light. Before embarking upon this endeavor, a conscious decision was made to use XML as the means to define and exchange data. This was done for a number of reasons. XML is rapidly becoming a very popular technology for a wide variety of applications ranging from Database Publishing to Electronic Commerce. In fact a number of organizations are looking at XML for specifying the standards in their particular domain like EDUCOM IMS, HL7 for Healthcare and TCIF (Tele Communication Industry Form).

Here are some of the advantages that XML brings to the table.

Since XML is a meta language, it allows industry specific initiatives (such as this one) to define their own markup tags to define their own domain specific language. This is a big improvement over HTML where the valid markup tags are pre defined.
The XML syntax is very rich and the XML-Data specification provides many syntactical constructs that make is possible to define abstract data classes in a standard manner without having to resort to a particular programming language or style of IDL. This is done by defining XML schemas for particular classes of data
XML allows for a structured representation of the data and allows both humans and computers to easily deduce how the data is laid out, which fields make up records etc. In other words it tells us what data means. Once again this is different from HTML which only tells us how data looks once it is rendered in a browser.
Since XML data is smart data it means that this data can be sent to a client which can then operate upon it intelligently, like searching, sorting, comparing etc. without requiring round trips to the server. This is an tremendous improvement in terms of saving bandwidth and server resources.
XML is a W3C standard and as such is supported by products from a number of different companies. There is low cost and even free software available to parse and display XML streams.
XML leverages the internet and internet services for allowing applications to transfer data securely over the most popular public network in the world and allows the integration of applications on heterogeneous platforms.

1.9 Structure Charts

Structure charts show the hierarchy of an XML Model. These charts are used throughout this document to describe the data model. Frequency is indicated by symbols that precede the element name. If no symbol is present, one (1) instance of the element is required. If question mark symbol appears, the element is optional (0 or 1). If an asterisk appears, the element is optional and repeatable (0 or more). If a plus appears, the element is required and repeatable (1 or more).

Figure 1: Components of a structure chart

Structure Charts also communicate the sequence, or order, of elements within a model. Square connectors indicate elements that occur in a prescribed order. Angular connectors mean that only one of those listed may be chosen (exclusive or). The occurrence of a tilde (~) in a box means that the element has a attribute associated with it.

1.10 Using Namespaces to solve versioning issues

1.11 Overview of Remaining Sections

Section 2 describes the objects that are currently defined in the specification, the relationships that exist among them and how these relationships related to forming valid queries. Structure charts are used to describe the objects and examples are given.

Section 3 describes the events and messages that are exchanged among the applications. The events are related to the messages they generate. The entire K-12 message structure is described in this section along with examples.

Section 4 at a high level the two types of interactions that the applications need to support i.e. Query/response and Publish/Subscribe.

Appendix A has all the tag documentation along with examples, attribute descriptions and values. References to SPEEDE/ExPRESS are made for the cases where these values have been adopted from them.

Appendix B is a quick alphabetic Tag reference.

Appendix C is the XML DTD

Appendix D has the corresponding XML – Data schemas for the XML models.

2 OBJECTS, RELATIONSHIPS and QUERIES

This section describes the various objects that have been identified and the relationships between them. The reason for specifying the supported relationships is to allow only those queries for data that are based on these relationships and to disallow other ad hoc queries.

2.1 Student Object

This object contains all the information that pertains to an individual student like id, name, address etc. The next figure shows the XML structure chart for the student object with all the elements that make up a student.

Figure 2: Student Object structure chart

Based on this definition an XML representation of a student object is shown next.

</PhoneNumber>

<StudentName><LastName>Kennedy</LastName>

<MiddleName>Jean</MiddleName><FirstName>Helen</FirstName>

</StudentName>

<StreetName>Tarpon</StreetName><StreetType>Court</StreetType>
</Street>

<City>Homewood</City>
<County>Cook</County>

</Address>

</Student>

Note: For a full description of possible attribute values and descriptions of elements and attributes, please refer to Appendix A , XML – Tag Documentation.

2.2 Contact Object

The contact object is defined to contain contact information for a student or a teacher. The next figure shows a structure chart for the contact object.

Figure 3: Contact object structure chart. Street element is as defined in Figure 2 for the Student Object

Based on this structure chart an XML representation of a contact object will look like this.

<ContactName><LastName>Kennedy</LastName>

<MiddleName>Jean</MiddleName><FirstName>Helen</FirstName>

</ContactName>

</PhoneNumber>

<StreetName>Tarpon</StreetName><StreetType>Court</StreetType>
</Street>

<City>Homewood</City>
<County>Cook</County>

</Address>

</Contact>

2.3 Teacher Object

The teacher object is defined to contain information related to a teacher. It’s definition can be seen in the next figure.

Figure 4: Teacher object structure chart. Street is as defined in Figure 2

Here is an example of a teacher object based on this definition.

<Department>Science</Department>

</PhoneNumber>

<TeacherName><LastName>Kennedy</LastName>

<MiddleName>Jean</MiddleName><FirstName>Helen</FirstName>

</TeacherName>

<StreetName>Tarpon</StreetName><StreetType>Court</StreetType>
</Street>

<City>Homewood</City>
<County>Cook</County>

</Address>

</Teacher>

2.4 School Object

The school object represents the information pertaining to a school. Here is an example of a school object based on this definition.

Figure 5: School Object structure chart

<School id="k2345" code="HS">
<SchoolName>York High School</SchoolName>
<Address>

<StreetName>Tarpon</StreetName><StreetType>Court</StreetType>
</Street>

<City>Homewood</City>
<County>Cook</County>

</Address>

</PhoneNumber>

<StudentID href="#6712"/> . . .

<TeacherID href="#4532a"/> . . .

</School>

2.5 Relationships

This section defines the relationships among the objects defined above. The purpose of defining these relationships as part of the standard is to define the types of queries that framework complaint applications support. Since the framework does not support ad hoc queries, defining the relationships among objects separates out a subset of all possible queries that are valid. For example for the relationship "A Student has one or more teachers", the following queries are valid: "For a given student return the names of all teachers" or "Return all students whose teacher is Mrs. Smith" etc. The following relationships exist among the different objects.

A Student has one or more Contacts
A Student has one or more Teachers.
A Student has one or more Schools.
A Teacher has one or more Contacts.
A Teacher has one or more Schools.

Note that we have deliberately left out relationships like "A Teacher has one or more students" or "A Contact belongs to one or more Student". This is done because no immediate value is seen by adding these relationships. As the Framework proceeds new relationships may be defined as needed.

2.6 Queries

Having defined the relationships that exist among the different objects, this section now describes the types of queries that are valid. The following types of queries are valid.

2.6.1 Query spanning only one object

Given the class of object return a number of records where each record contains one or more fields that make up an object and where each object selected meets the specified criteria

The simplest type of query of this type is in which a unique object is identified based on the class and an Id and one or more fields are returned. An example of this type of query is "For a Student object, where student id = 999-99-9999, return the name, address and phone number". In this case only one record is returned because the criteria specified picks a unique object.

Another query of this type is "For a Teacher object, return the names of all teachers teaching in Redmond". In this case the selection criteria picks a number a teachers so a number of records are returned.

The key to remember in this type of query is that the data returned is always from the same object type so these queries are valid for all objects that the Framework defines.

2.6.2 Query spanning multiple objects

Given the class of one or more objects return a number of records where each record is made up fields from this object and/or it’s related object and where this object or the related objects meet the given criteria.

This is where the importance of defining relationships becomes apparent. If certain objects are not related (according to the Framework definition) then a query assuming this relationship is invalid.

An example of a valid query is "For a Student and Teacher object return the names of the students and names of the teachers where the student lives in WA state". In this case there is a relationship between a student and teacher so this query is valid.

Another example of a valid query is "For a Teacher and Contact object return the names of the teachers and names of the contacts where the contact relationship is spouse".

Yet another valid query is "For a Student, Teacher and Contact object return the names of students, teacher and contacts where the contacts are the teacher’s spouses".

This is an example of an invalid query. "For a Contact and School object return the names of the contacts belonging to WA state schools". The reason this is invalid is because there is no relationship between the Contact and School object.

Note: The exact mechanism needed to support this type of querying are still not clear. This section will be updated once the issues related to querying become clear. This will happen after the prototype has been implemented.

3 MESSAGES and EVENTS

In this section the real word events that are generated are identified and the messages that are exchanged among applications as a result of these events are defined. Consumers of data register with the framework to listen for these events. When they occur (they are typically generated by provider application) the data defined for these events is sent in the form of predefined messaged. The remainder of this section examines all these events and defines the XML messages that are exchanged. As before, detailed description of the elements that make up these events and messages are defined in Appendix A.

3.1 Overall Schools Interoperability Framework message Structure

Figure 5: The K12 Framework is made up of seven options; a event, a request, a response, a publish/unpublish and a subscribe/unsubscribe message. Note the exclusive OR connector. This means that the message can contain one and only one of the types describe below

3.2 K12Event Message

This is the message that is sent when an event is generated by a provider application. Note that the data associated with the event is also sent in the same message.

Figure 6: Each K12Event message may be either an enrollment status change, an update of student information (partial or complete), and update of teacher information (partial or complete) , an update of contact information (partial or complete) , or an update of school information ( partial or complete). It is important to note that each K12Event carries only one type of update information (although it may carry multiple records of the same type)

Every message that is exchanged is preceded by a header. This header is shown in the following figure.

Figure 7: The message header records a unique tracking ID, the date, the time, the source of the update, and the number of transactions or record count.

3.3 Enrollment Change Message

Trigger Event: Student Enrollment Status changes.

This message is sent when the status of a student changes. This includes student enrollment, student withdrawal, student graduation, student transfer event.

Figure 8: The enrollment status change is used to withdraw a student, enroll a student or transfer a student. This message consists of the student ID (which links this to a student record), the effective date, the reason for the change, the change of status, and the school year. SPEEDE /ExPRESS codes are used for the reason for change and the change status coding.

The next example shows what an XML representation of this message looks like.

</MsgHead>

</EnrollStatusChg>

</K12Event>

</K12Framework>

Note: Some of these examples are shown with indents to make the hierarchy clear but in reality there should be no leading white spaces in the middle of the XML stream.

3.4 Student Update Message

Trigger Event: An entire student object is updated.

The Student Update message is sent when the entire information about the student needs to be transferred to another application. This typically happens when a new student is added to the system. This message simply contains the entire student object as show in the next figure. A definition of the fields in a student object can be found in Section 2.

Figure 9: Student Update Message

Example:

</MsgHead>

</PhoneNumber>

<StudentName><LastName>Kennedy</LastName>

<FirstName>Helen</FirstName>

</StudentName>

<StreetName>Tarpon</StreetName>

<StreetType>Court</StreetType>
</Street>

<City>Homewood</City>
<County>Cook</County>

</Address>

</Student>

</StudentUpdate>

</K12Event>

</K12Framework>

3.5 Partial Student Update Message

Trigger Event: Some fields of a student object are updated.

Sometimes it is not necessary to send the entire student information. This happens when only some fields that make up a student object change. As example of this situation is when student’s address changes, this changed address should be the only field that is sent to other applications. The structure chart for this message is shown in the next figure.

Figure 10: Structure chart for a partial student update message. Note that all the fields except for student Id are optional. The Student ID field is used by the receiving application to identify with which student this updated information needs to be associated.

Here is an example of a partial student update message. In this message the student’s phone number and address are changed.

</MsgHead>

</PhoneNumber>

<StreetName>Northup</StreetName>

</Street>

<City>Woodenville</City>

</Address>

</PartialStudentUpdate>

</K12Event>

</K12Framework>

Note: For examples related to message described in the following section, please refer to Appendix A.

3.6 Teacher Update Message

Trigger Event: An entire Teacher object is updated

This message is sent when all the information associated with a teacher needs to be updated. As in the case of the student update message this message simply contains the entire teacher object.

Figure 11: Teacher update message
3.7 Partial Teacher Update Message

Trigger Event: Some fields of a Teacher object are updated.

As before, the partial teacher update message is sent by an application when one or more individual fields of the teacher object change.

Figure 12: Partial Teacher Update message. Note that all the fields except for TeacherId are optional.

3.8 Contact Update Message

Trigger Event: An entire Contact object is updated.

This message is typically sent when a new contact is added to the system.

Figure 13: Contact update message

3.9 Partial Contact Update Message

Trigger Event: Some of the fields of a Contact Object are updated.

This message is sent when one or more fields of a contact object need to be updated

Figure 14: Partial Contact Update message. As before all the fields except ContactID are defined to be optional.

3.10 School Update Message

Trigger Event: An entire School object is updated

This message is sent when the information for the entire school object is updated.

3.11 Partial School Update Message

Trigger Event: Some fields of a School object are updated.

This message is sent when some of the fields that make up a School Object are updated

Figure 15: Partial School Update Message

3.12

ID Change Message

Trigger Event: An ID changes for student, teacher, contact or school.

This message is sent when some ID is updated. The ID is used to uniquely identify an object.

Figure 16: Partial School Update Message

3.13 K12 Request Message

When an application needs data from another application it sends it a request specifying the data it is interested in (in other words it sends a query). This type of interaction is described in Section 4.1 in more detail. This section is about defining the message that needs to be formulated by the requesting application. This is still under discussion and once the details of this message have been worked out it will be included in this document. Some of the considerations that are being discussed in order to define this message are:

A provider application should not have trouble parsing this message. Most likely a provider application will parse this message, translate the XML tag names into it’s internal name, formulate an SQL like query and submit this query to it’s internal database. The definition of this message must make these actions easy to perform.
The Framework needs to route this message to the correct application or applications. The message definition must contain enough information to allow it to do so.

Figure 17: Each request bears a request ID for tracking purposes. A request also has a date, time, and source. The query is expected to be a text field containing an XML Query.

3.14 K12 Response Message

The response message is sent by the provider application after the request has been processed. It’s primary function is to return the data to the requesting application.

Figure 18: Each response bears the request ID as well as its own response ID for tracking purposes. A response may be a set of K12 elements, it may be a number (in response to a query such as "how many students . . ." or an error message may be returned if the query could not be executed for some reason.

3.15 K12 Subscribe Message

A consumer application uses this message to register with the framework the events (and the associated data) that have to be routed to it.

Figure 19: The K12 Subscribe Message contains a subscription heading and a number of events to which the application may sbuscribe.

Note: Please refer to Appendix A for a list of valid events to which a consumer may subscribe.

3.16 K12 Unsubscribe Message

Used by consumers to terminate subscriptions

Figure 20: The K12 UnSubscribe Message contains a subscription heading and a number of events to which the application may cancel subscriptions.

3.17 K12 Publish Message

Used by providers to tell the framework which data items are supplied by that particular provider. The framework uses this information to determine where to route request messages from consumer applications.

Figure 21: The K12 Publish Message contains a publish heading and a number of data objects which may be queried by other applications.
Note: Please refer to Appendix A for a list of allowable objects. The idea here is that a provider of data tells the framework which data (in terms of objects) it can provide to consumers. It is important to note that it is assumed here that all the data contained in one object is provided by a single application. This is not an unreasonable assumption because of the way the objects have been defined. If we ever come across an object whose data is not contained in a single application we will have to break that object into 2 or more sub-objects such that each sub-object is provided by one application.

3.18 K12 Unpublish Message

To tell the framework that this provider can no longer supply that particular data. To be used when an application terminates.

Figure 22: The K12 Publish Message contains a publish heading and a number of data objects which may no longer be queried by other applications.

4 APPLICATION INTERACTION MODES

This section examines the two modes of interaction that the standard defines. Applications use these two modes of interaction to exchange messages. These modes are:

4.1 Query/ Response

In this mode of interaction a consumer application sends a query message to a provider application. This query message contains the request for data by defining which type of data needs to be returned. The framework identifies the correct provider for this query, routes the query to it, receives the response data and returns it to the consumer applications. The types of allowable queries and the messages are defined in section 3.0

(Give some examples)

4.2 Publish/Subscribe

In the type of interaction, a consumer registers interest in an event with the Framework. When this event is sent to the framework by a provider application, the event (and the associated data) is routed to the consumer(s) that are registered to listen for this event. The supported events and the messages they generate are described in section 3.0 (give example)

APPENDIX A: XML – TAG DOCUMENTATION

This section contains detailed documentation of each tag and attribute arranged in alphabetical order. Examples of the use of each tag are given.

Address
<Address>

Description:

Identifies an address. See example below.

Required Attributes:

None

Example:

<StreetName>Tarpon</StreetName><StreetType>Court</StreetType>
</Street>

<City>Homewood</City>
<County>Cook</County>

</Address>

AptNumber
<AptNumber>

Description:

Identifies the apartment number portion of an address. See example below.

Required Attributes:

None

Example:

<StreetName>Tarpon</StreetName><StreetType>Court</StreetType>
</Street>

<City>Homewood</City>
<County>Cook</County>

</Address>

AptNumPrefix
<AptNumPrefix>

Description:

Identifies new See example below.

Required Attributes:

None

Example:

<StreetName>Tarpon</StreetName><StreetType>Court</StreetType>
</Street>

<City>Homewood</City>
<County>Cook</County>

</Address>

AptNumSuffix
<AptNumSuffix>

Description:

Identifies the apartment number suffix. See example below.

Required Attributes:

None

Example:

<StreetName>Tarpon</StreetName><StreetType>Court</StreetType>
</Street>

<City>Homewood</City>
<County>Cook</County>

</Address>

AptType
<AptType>

Description:

Identifies the apartment type. See example below.

Required Attributes:

None

Example:

<Street><AptType>Suite</AptType>
<AptNumber>201</AptNumber><AptNumSuffix>B</AptNumSuffix>
<StreetNumber>146</StreetNumber>

<StreetName>Tarpon</StreetName><StreetType>Court</StreetType>
</Street>

<City>Homewood</City>
<County>Cook</County>

</Address>

AreaCode
<AreaCode>

Description:

Identifies an area code within a telephone number. See example below.

Required Attributes:

None

Example:

</PhoneNumber>

BirthDate
<BirthDate>

Description:

Identifies a birth date in the D8 format (CCYYMMDD) See example below.

Required Attributes:

None

Example:

</Student>

ChangedStatus
<ChangedStatus code=x>

Description:

Identifies a change in enrollment status. See example below.

Required Attributes:

Attributes	Description	Possible Values	Default
code=x	Specifies the enrollment status	enrolled withdrawn	Required

Example:

</EnrollStatusChg>

ChangeReason
<ChangeReason code=x>

Description:

Identifies the reason for a change in student enrollment status. This is a SPEEDE/EXPRESS code. See example below.

Required Attributes:

Attributes

Description

Possible Values

Default

code=x

Specifies the reason why a student’s enrollment status had changed. The values are taken from SPEEDE/ExPRESS

B27 Student is eligible to continue or return or both

B28 Student is on suspension or dismissal

B29 Student is expelled (from PreK - grade 12)

B31 Not currently enrolled B38 Dropped

B39 Academic Probation

B40 Suspended

B51 Student on Suspension or Dismissal; Eligible to Apply for Re-entry

B52 According to established regulations or statutes

D03 Student has attended a nonpublic school or home education program in- or out-of-state this year

D04 Student was received from another attendance reporting unit in the same school

D05 Student was received from a school in the same district

D06 Student was received from another public school outside the district either in- or out-of-state

D07 Student was received from a nonpublic school either in or out of the district or has returned after having been enrolled in a home education program; The student must have been enrolled previously in a public school this year

D08 Student unexpectedly reentered the same school after withdrawing or being discharged

D09 Student was expected to attend a school but did not enter as expected for unknown reasons

D10 Student was promoted, retained, or transferred to another attendance-reporting unit in the same school

D11 Student was promoted, retained, or transferred to another school in the same district

D12 Student withdrew to attend another public school in the same district

D13 Student withdrew to attend another public school in- or out-of-state

D14 Student Over Compulsory Attendance Age Left School Voluntarily with No Intention of Returning

D15 Student Graduated from School with a Standard Diploma

D16 Student Graduated from School with a Special Diploma

D17 Student Left School with a Certificate of Completion

D18 Student Left School with a Special Certificate of Completion

D19 Student Left School with a State General Education Development (GED) High School Diploma

D20 Student Withdrew to Attend a Non-Public School or Home Education Program In- or Out-of-State.

D21 Student withdrew from school due to hardship

D22 Student has not entered any school in this or any other state this school year

D23 Previously attended out-of-state public school but is entering a public school in this state for the first time this school year

D24 Returned to Regular Education Program

EB1 Deceased

EB3 Withdrawn

EB4 Graduated

Required

Example:

</EnrollStatusChg>

City
<City>

Description:

Identifies the city portion of an address. See example below.

Required Attributes:

None

Example:

<StreetName>Tarpon</StreetName><StreetType>Court</StreetType>
</Street>

<City>Homewood</City>
<County>Cook</County>

</Address>

Complex
<Complex>

Description:

Identifies the apartment complex portion of an address. See example below.

Required Attributes:

None

Example:

<Street><Complex>Englewood Estates</Complex><AptType>Suite</AptType>
<AptNumber>201</AptNumber><AptNumSuffix>B</AptNumSuffix>
<StreetNumber>146</StreetNumber>

<StreetName>Tarpon</StreetName><StreetType>Court</StreetType>
</Street>

<City>Homewood</City>
<County>Cook</County>

</Address>

Contact
<Contact ID=x type=x>

Description:

Identifies the contact object. This is made up of the Contact Name, Phone Numbers, Address, Gender, SSN, Race, and Relationship See example below.

Required Attributes:

Attributes	Description	Possible Values	Default
ID=x	Specifies the unique id of the contact	String of text	Required
Type=x	Specifies the type of contact	Emergency Non-Emergency	Required

Example:

<ContactName><LastName>Kennedy</LastName>

<MiddleName>Jean</MiddleName><FirstName>Helen</FirstName>

</ContactName>

</PhoneNumber>

<StreetName>Tarpon</StreetName><StreetType>Court</StreetType>
</Street>

<City>Homewood</City>
<County>Cook</County>

</Address>

</Contact>

ContactID
<ContactID href=x>

Description:

Identifies a link to contact information. The href=x attribute links to the ID attribute on Contact. See example below.

Required Attributes:

Attributes	Description	Possible Values	Default
href=x	Specifies the link to a contact	A unique identifier	Required

Example:

</PartialStudentUpdate>

ContactName
<ContactName>

Description:

Identifies a contact name. Made up of last name, middle name and first name. See example below.

Required Attributes:

None

Example:

<ContactName><LastName>Kennedy</LastName>

<MiddleName>Jean</MiddleName><FirstName>Helen</FirstName>

</ContactName>

ContactUpdate
<ContactUpdate>

Description:

Identifies an event which provides complete updates or enters new updates to contact information databases. This event may consist of one or more <Contact> information objects. See example below.

Required Attributes:

None

Example:

</ContactUpdate>

County
<County>

Description:

Identifies the county portion of an address. See example below.

Required Attributes:

None.

Example:

<Street><AptType>Suite</AptType>
<AptNumber>201</AptNumber><AptNumSuffix>B</AptNumSuffix>
<StreetNumber>146</StreetNumber>

<StreetName>Tarpon</StreetName><StreetType>Court</StreetType>
</Street>

<City>Homewood</City>
<County>Cook</County>

</Address>

Credentials
<Credentials code=x>

Description:

Identifies a teacher credentials using a SPEEDE/EXPRESS code. See example below.

Required Attributes:

Attributes	Description	Possible Values	Default
code=x	Specifies the SPEEDE/EXPRESS credential code	2.1 = Postsecondary certificate or diploma (less than one year) 2.2 = Postsecondary certificate or diploma (one year or more but less than four years) 2.3 = Associate Degree (e.g., Associate in Arts, Associate in Science, Associate in Applied Science) 2.4 = Baccalaureate Degree 2.5 = Baccalaureate (Honours) Degree 2.6 = Postsecondary certificate or diploma (one year or more but less than two years) 2.7 = Postsecondary certificate or diploma (two years or more but less than four years 3.1 = First Professional Degree 3.2 = Post-Professional Degree 4.1 = Graduate 4.2 = Master's Degree 4.3 = Intermediate Graduate Degree 4.4 = Doctoral Degree 4.5 = Post Doctoral	Required

Example:

<Department>Science</Department> . . . </Teacher>

Date
<Date>

Description:

Identifies a date in the D8 format (CCYYMMDD). D8 is a date code specified by SPEEDE/ExPRESS. See example below.

Required Attributes:

None

Example:

DateHired
<DateHired >

Description:

Identifies the date a teacher was hired in D8 format (CCYYMMDD) See example below.

Required Attributes:

None

Example:

<Department>Science</Department> . . . </Teacher>

Department
<Department>

Description:

Identifies department to which a teacher reports. See example below.

Required Attributes:

None

Example:

<Department>Science</Department> . . . </Teacher>

DistrictNbr
<DistrictNbr>

Description:

Identifies the school district number. See example below.

Required Attributes:

None

Example:

<School id="k2345" code="HS">
<SchoolName>York High School</SchoolName>
<Address>

<StreetName>Tarpon</StreetName><StreetType>Court</StreetType>
</Street>

<City>Homewood</City>
<County>Cook</County>

</Address>

</PhoneNumber>

<StudentID href="#6712"/> . . .

<TeacherID href="#4532a"/> . . .

</School>

EffectiveDate
<EffectiveDate >

Description:

Identifies the date on which a change in student enrollment takes effect. See example below.

Required Attributes:

None

Example:

</EnrollStatusChg>

ElectronicID
<ElectronicID type=x>

Description:

Identifies the optional electonic identifier associated with the student object. See example below.

Required Attributes:

Attributes	Description	Possible Values	Default
type=x	Specifies the type of electronic identifier	"barcode", "magstripe", "pin"	Required

Example:

EmployeeID
<EmployeeID>

Description:

Identifies the teacher employee ID. See example below.

Required Attributes:

None

Example:

<Department>Science</Department> . . . </Teacher>

EnrollStatusChg
<EnrollStatusChg>

Description:

Identifies a change in enrollment event. See example below.

Required Attributes:

None

Example:

</EnrollStatusChg>

Error
<Error code=x>

Description:

Identifies an error condition that is returned within a K12 response. See example below.

Required Attributes:

Attributes	Description	Possible Values	Default
code=x	Specifies the error message code	1 = Insufficient Priv. 2 = Data not available (no data of this sort vs. null) 3 = Incorrect Query Syntax 4 = Resubmit Query	Required

Example:

<Time zone="PS">10:20:15</Time><Source>http://admin.student.com:80/</Source>

</ResponseHead>

</K12Response>

Event
<Event type=x>

Description:

The K12 subscribe transaction has a subscription header that identifies the transaction, gives the date and time as well as the source. The subscribe transaction then contains one or more objects that it wishes to receive. See example below.

Required Attributes:

Attributes	Description	Possible Values	Default
type=x	Specifies the event type	studentupdate, partialstudentupdate, teacherupdate, partialteacherupdate, contactupdate, partialcontactupdate, schoolupdate, partialschoolupdate	Required

Example:

<Time zone="PS">10:20:15</Time><Source>http://admin.student.com:80/</Source>

</SubscribeHead>

</K12Subscribe>

Ext
<Extension>

Description:

Identifies the extension within a phone number. See example below.

Required Attributes:

None

Example:

</PhoneNumber>

FirstName
<FirstName>

Description:

Identifies the first name portion of a name. See example below.

Required Attributes:

None

Example:

<StudentName><LastName>Kennedy</LastName>

<MiddleName>Jean</MiddleName><FirstName>Helen</FirstName>

</StudentName>

Gender
<Gender code="x">

Description:

Identifies gender. See example below.

Required Attributes:

Attributes	Description	Possible Values	Default
code=x	Specifies the SPEEDE/EXPRESS gender Code	"M"(Male), "F" (Female), "U" (Unknown)	Required

Example:

</Student>

GradeLvl
<GradeLvl>

Description:

Identifies the student’s grade level See example below.

Required Attributes:

None

Example:

</Student>

GradYear
<GradYear type=x>

Description:

Identifies the graduation year (projected or original). See example below.

Required Attributes:

Attributes	Description	Possible Values	Default
type=x	Specifies the graduation year type	"original", "projected"	Required

Example:

</Student>

HomeRoom
<HomeRoom>

Description:

Identifies the student’s home room. See example below.

Required Attributes:

None

Example:

</Student>

IDUpdate
<IDUpdate>

Description:

This message is sent when any object ID is updated. The IDUpdate will consist of a *ID and a New*ID to indicate the existing ID and the new ID. See example below.

Required Attributes:

None.

Example:

</IDUpdate>

ImmigrationStatus
<ImmigrationStatus code=x>

Description:

Identifies a student’s immigration status by SPEEDE/EXPRESS code. See example below.

Required Attributes:

Attributes	Description	Possible Values	Default
code=x	Specifies the immigration status SPEEDE/EXPRESS code	1 U.S. Citizen 2 Non-Resident Alien 3 Resident Alien 4 Illegal Alien 5 Alien 6 U.S. Citizen - Non-Resident 7 U.S. Citizen - Resident 8 Citizen 9 Non-citizen with Student Authorization A Non-permanent Resident Alien B Permanent Visa C Temporary Visa	Required

Example:

</Student>

K12Event
<K12Event>

Description:

Identifies a K-12 Message. This may consist of an enrollment status change, a student update or partial student update, a contact update or partial contact update, a teacher update or partial teacher update or a school update or partial school update. Each message has a message header which identifies the message. A K12 Message can contain one or more like contents. For example a single message could send 12 student updates. But it could not mix student updates with teacher updates.

See example below.

Required Attributes:

None

Example:

<MsgID>#40250</MsgID><Date>10-20-1997</Date><Time zone="PS">10:20:15</Time><Source>http://admin.student.com:80/</Source>

</MsgHead>

</K12Event>

K12Framework
<K12Framework>

Description:

Identifies the beginning of a K-12 Framework transction. May contain a K12 Message, a query, a response, or be used to subscribe or publish various data types. See example below.

Required Attributes:

None

Example:

</K12Framework>

K12Publish
<K12Publish>

Description:

This transaction is sent by an application that publishes or broadcasts one of the K12 message types.. The K12 publish transaction has a publish header that identifies the data objects it holds, gives the date and time as well as the source. The publish transaction may contain one or more data objects that it publishes and to which other applications may query. See example below.

Required Attributes:

None

Example:

<Time zone="PS">10:20:15</Time><Source>http://admin.student.com:80/</Source>

</PublishHead>

</K12Publish>

K12Request
<K12Request>

Description:

Identifies query between one application and another. The K12Request is used to ask for information that is not broadcast by subscription. The K12 Request has a request head and the query itself. See example below.

Required Attributes:

None

Example:

<Time zone="PS">10:20:15</Time><Source>http://admin.student.com:80/</Source>

</RequestHead>

<XMLQuery> This is the query </XMLQuery>

</K12Request>

K12Response
<K12Response>

Description:

Identifies the response to a K12 request. The response contains a response header followed by either an error, a numeric answer to the query, or response data. See example below.

Required Attributes:

None

Example:

<Time zone="PS">10:20:15</Time><Source>http://admin.student.com:80/</Source>

</ResponseHead>

</K12Response>

K12Subscribe
<K12Subscribe>

Description:

This transaction is sent by an application that wishes to subscribe to one of the K12 message types. The K12 subscribe transaction has a subscription header that identifies the transaction, gives the date and time as well as the source. The subscribe transaction then contains one or more events that it wishes to receive. See example below.

Required Attributes:

None

Example:

<Time zone="PS">10:20:15</Time><Source>http://admin.student.com:80/</Source>

</SubscribeHead>

</K12Subscribe>

K12UnPublish
<K12UnPublish>

Description:

This transaction is sent by an application that publishes or broadcasts one of the K12 message types.. The K12 unpublish transaction has a publish header that identifies the data objects it holds, gives the date and time as well as the source. The unpublish transaction may contain one or more data objects that it no longer publishes. See example below.

Required Attributes:

None

Example:

<Time zone="PS">10:20:15</Time><Source>http://admin.student.com:80/</Source>

</PublishHead>

</K12UnPublish>

K12UnSubscribe
<K12UnSubscribe>

Description:

This transaction is sent by an application that wishes to unsubscribe to one of the K12 message types. The K12 subscribe transaction has a subscription header that identifies the transaction, gives the date and time as well as the source. The subscribe transaction then contains one or more events for which it no longer need notification. See example below.

Required Attributes:

None

Example:

<Time zone="PS">10:20:15</Time><Source>http://admin.student.com:80/</Source>

</SubscribeHead>

</K12UnSubscribe>

LastName
<LastName>

Description:

Identifies a last name within a full name See example below.

Required Attributes:

None

Example:

<StudentName><LastName>Kennedy</LastName>

<MiddleName>Jean</MiddleName><FirstName>Helen</FirstName>

</StudentName>

MiddleName
<Middle>

Description:

Identifies a middle name within a full name. See example below.

Required Attributes:

None

Example:

<StudentName><LastName>Kennedy</LastName>

<MiddleName>Jean</MiddleName><FirstName>Helen</FirstName>

</StudentName>

MsgHead
<MsgHead>

Description:

Identifies the heading of a K12 Message. See example below.

Required Attributes:

None

Example:

<Time zone="PS">10:20:15</Time><Source>http://admin.student.com:80/</Source>

</MsgHead>

<EnrollStatusChg> . . . <