SIF Association

This blog is run by the staff of the SIF (Schools/Systems Interoperability Framework) Association for the use of it's members and the general educational community.

It is specifically designed for those who are interested in understanding what SIF is about, where the standard is going and how Schools, Districts and State Educational Authorities will benefit.



Friday, November 18, 2011

Migrating to a minor SIF release: Programming Conventions


In general the SIF standard issues a new minor release every 9-12 months, and that trend looks like it will be continuing.  These releases traditionally extend the SIF Data Model by adding new objects, new elements and new code list values to the previous version, although with SIF v2.5, an entirely new Web Service infrastructure stack was also introduced.  The following requirements apply to every new SIF 2.x minor release. 

·         1. Support Incremental Migration
It must be possible for a Zone Administrator to incrementally upgrade the Zone to a new minor release one component (ZIS, Agent / Application) at a time without:

o   Losing existing functionality or “breaking” anything
o   Encountering significant interoperability problems during the upgrade

The ordering of the component upgrades may be fixed by the release documentation (ex: ZIS upgraded first, then Object Providers, then ...)

·           2. Limit  “backwards compatibility” logic requirements
The early developers of a SIF agent or application conforming to the new release will have their initial deployments occur in Zones where majority of the pre-existing SIF agents and applications are only supporting the older versions of the standard.

It must be possible for the new agent / application pair to integrate into such a Zone relatively easily, without requiring the developers to incorporate “significant” internal logic to translate between the new and old versions of the specification.

The first of these requirements lowers the cost of migration for end users, while the second does the same for agent and application developers.

In order to meet these goals, it is necessary for legacy components to conform to the following long established “robust in the face of change” programming techniques

1. Accept and Ignore unexpected elements

In many approaches to XML versioning, the only truly “backward compatible” change is one in which the existing schema is somehow restricted (as when a formerly optional element becomes mandatory).  This type of change ensures that any new message will validate using the old schema since effectively the optional element in question just “happens to be present” (because it is now mandatory) in any message sent by an application conforming to the new release.

On the other hand, consider the problem when a new optional element is added to an object in the new release.  It may be included in either an Event or Response message sent out by a newly installed application. While the legacy recipient can examine the “Version” attribute on the message, it can’t select a corresponding XML schema to use in validation when it was written in conformance with an older version of SIF.  If XML validation is turned on, the incoming message will not validate using any schema the recipient understands.

The problem here is that one of the most natural ways a standard develops is by adding new and previously undefined elements, and the SIF standard is no exception.  Assuming applications supporting these new elements must be integrated into a Zone with older components (which initially is ALWAYS true), how can this be done without either updating all affected applications simultaneously (a non-starter) or breaking existing functionality (unacceptable)?

The answer is rather obvious. Agent developers can use an XML parsing approach that simply ignores any element which is unexpected or not defined in their schema, even if this generated an XML verification fault when it arrived.

In fact, in many cases (where an XML framework like WCF supports this approach) the new element will never be detected in the first place.  But where it has been, it can be safely ignored, because since it was unexpected, it can’t affect the way in which the component will process the rest of the message.

2. Accept and Log unexpected values in an Enumerated List

This type of data inconsistency can occur even when the new version of the SIF specification merely extends the set of possible values in a previously existing list (ex: a new Discipline code). It is more problematic than the previous example because here the unexpected value cannot simply be ignored, since it makes it impossible for the legacy application to process an element on which it was relying.

This situation can be viewed as either a bug in the new application or a failure of the migration strategy for the new release, because ideally no legacy application should suddenly start receiving code values for any SIF-defined element it supports, which were undefined in the standard at the time the application was written.

In actual fact it may be neither.

Normative dependencies on external code sets from other standards such as ISO Country Names mean there are times where SIF needs to modify or add to such sets even when issuing a minor release.  Another problem is that the code sets SIF contains do not always fully encompass the set of values required by the site, and additional code values need to be introduced at installation time.

Even SIF-defined enumerated code lists evolve and have to be updated in the XML schema, and there are times where an equivalent backwards mapping for each new element into the previous value set is impossible.  Backward compatibility becomes even more difficult when Events are involved, because the same identical message is placed in the queue of all subscribers, some of whom may have been written to conform to an earlier version of the specification, and the rest to the current one.

So a legacy application may receive an enumerated code value it does not understand, because it was not defined in the version of the standard the application conforms to.  In this case, the recommended action for the Agent is to:

1.      1. Accept the message

       2. Insert a “Code Not Understood” (or equivalent) value in the XML element which is passed back to the application. 


3.       3. Post a LogEntry Event containing the sender, the element and the unintelligible value.

Reasoning:
Acceptance of the message is critical.  In most cases (incoming Response or Event) there is no way to report a problem back to the sender anyway.  Rejecting the message at the ZIS level is not correct, since that implies there was something wrong with the message header, which is not the case here.

Since it can’t be rejected, the rest of the message should not be thrown away.  However by inserting a previously defined and “recognized” error value for the element, the application can still process the remainder of the data.

The problem should also be brought to the attention of the Zone Administrator.  That is achieved by posting the LogEntry Event, ideally only once per new and unknown value (to avoid the danger of flooding the system with identical error messages).

With the adoption of these two programming practices it is possible to write a SIF Agent / Application which is both backwards AND forwards compatible across SIF minor releases.

Thursday, August 18, 2011

Enumerations are not compatible with the SIF * versioning implementation

Enumeration extensions are difficult to deal with in any versioning scheme.  Compare the difficulties in adding a new element to an object with adding a new allowed value to the end of an enumerated code list. 

·         If a legacy application receives a message with a new element (and XML verification is turned off) everything works.  All previous elements the application depends upon are there, and the new element can be safely ignored, in accordance with the long established Best Practice for all SIF applications to just ignore any unknown elements in a received message.

·         If the legacy application receives a message with code list element set to one of the new enumerated values, it can’t simply ignore it, because now the value of that element cannot be interpreted.  The information is lost exactly as if the code list had been omitted. 

There are several ways this can be dealt with:

1.    Create a new code list element with the extended values and require applications conforming to the new release to fill in and send both.
This has the disadvantage that multiple elements in the message contain duplicate data.

2.    Have the new application determine the version of its partner, and “translate” new enumerated values into the older set if it detects the partner is of an older version.
It is never a good strategy to lay “backward compatibility” constraints on every new application.  In this case it wouldn’t work anyway, because a single SIF event gets routed to every subscriber, whether new or old version.

3.    Have the ZIS do the translation whenever a new application is sending an event with a new code to a legacy subscribing application.
This can work, as the ZIS is the intermediary for every message in the SIF Zone, and already knows the versions of all connected applications.  However it requires the ZIS to “break open the payload” of every message for this object type and search for this case, and make the conversion.

This violates the desired separation of the ZIS from the data model being supported in the Zone, and would likely  impact overall Zone performance.

4.    Make a careful examination of the list of the vendors of SIF-certified applications which from their CSQ matrices are known to subscribe to this object and utilize this enumerated element, and alert them to the coming change. 
The goal here is to minimize the impact of what can be a breaking change introduced by the new release. It is obviously most effective in those cases where there has been minimal adoption and use of the affected enumerated element.

The end result is that depending upon the actual element involved, a different migration strategy could prove to be more optimal, and so it has not been possible to standardize on one approach. Each case then has to be considered on its merits.

They (enumerations) do not work well at all with objects that use foreign key definitions that allow a single field reference many different parent objects based on the value of the value of its sibling field.

Example: LibraryPatronStatus. You cannot add to an enumeration as it will BREAK backward compatibility. The Association needs to address this especially since they are adding more SIF objects that use a foreign key that is in two parts. One field to declare the parent and the other field to declare the foreign key value. The parent field is defined as a list.

Regarding the specific case mentioned (LibraryPatronStatus), there are two associated attributes:

·         SIF_RefId (SIF-wide unique identification of a student or teacher)
·         SIF_RefObject (The “type” of patron mapped to a SIF supported object – either StudentPersonal or StaffPersonal)

The problem comes up if the type alternatives were extended ... say to “ParentPersonal” (where a future version of the SIF standard allowed Parents to take out books).  How would a legacy application respond to a Library Patron of an unknown RefObject type? 

In this particular case, the migration plan might simply rely on the legacy application ignoring the entire LibraryPatronStatus object, because it could not understand (and then interpret) the parent class.  So for this application, there would be no Parent Patrons of the school library.

This is in accordance with current Best Practices for SIF applications, and it seems the ony reasonable solution here.  Other situations might require other migration plan alternatives.

What should be done is to clearly and concisely document the migration considerations for all “breaking” data model changes introduced in each release version, and this suggestion provides another justification for doing that.  Current plans are to provide such “migration plan” collateral for all future releases.

Tuesday, August 16, 2011

What’s up with Learning Resource and Associated Objects?

As more and more of you peruse the SIF Implementation Specification certain items are sure to strike you as odd.  Some come from the early days of our evolution, which everyone has simply accepted as the way it is.  Some more we have wanted to change for years but needed a major version in which to do the deed.   Others are simple inconsistencies that did not get caught during review.  Occasionally you will find one that stems from our versioning (or some other) policy.  Yet some are quite intentional, adopted for that special case where the norm simply did not fit the goals of the group.

The bizarre type-qualified Associated Objects of the Learning Resource object fall into this last group.  Normally the type of the object pointed to by RefId is included in its name (i.e. StudentPersonalRefId).  However, the Associated Objects in Learning Resource allow you to include a RefId for any object you like, as long as you also provide the type.  Why was this done?  Simply put, we wanted to be inclusive.  When you think about a learning resource it may need to point to anything from a book to a table saw, so we let you point to any object in the data model.  While there are some objects that should never be used here, they seems to be the exception rather than the rule.  You might even include people!  If a particular member of the staff is a critical component to the Learning Resource, go ahead, include a reference to a StaffPersonal object, why not, we will let you.

Of course the result of this linkage is a machine readable object, that more than likely needs to be presented nicely to a teacher or curriculum director.  Fortunately that is a feat that can be reasonably accomplished in a general way for the textual data of any single object.  While a vendor can still provide stunning visuals or deeper understanding for the objects they choose.

Enjoy the flexibility.

Monday, August 8, 2011

Where is the 2.4 and 2.5 Test Harness for an agent and ZIS?

Up and coming.  However, now is a good time to share some further details, so that those working on software of their own know what to expect.
Agent testing of the SIF Implementation Specification 2.4 (along with the Universal State Data Profile) is ready to be tried. We are excited to be in the midst of deploying it to our new staging server.  Once we have confirmed basic functionality, we intend to hold a beta for the entire membership.
The only reason we have been able to move forward on this agent testing is we have decided to not test Zone Services for the time being.  Since this is the most critical change in testing a 2.4 ZIS, we will not be scrutinizing them for 2.4 in the foreseeable future.  Although, a much more significant change which has already been adopted, is driving ZIS testing forward.
The SIF Implementation Specification 2.5 brings Web Services into an environment already racing to adopt Zone Services and Profiles.  Combined, these necessitate a more modular, flexible and extensible Test Harness.  One has been designed based on leveraging current assets; this design is undergoing late stage reviews while supporting code is being written and servers provisioned.
We indeed live in exciting times.

A Dialog on Deletion

Why does the SIF_Event/SIF_Action="Delete" require object payload?

The primary reason is consistency. By always contain an object instance with the RefId, we can always use one XPath (per ObjectName) to retrieve the RefId of the object we are working with.

Isn't all that is required is the object's primary key to indicate a delete?

Yes, that is the only part of the object required.  However, we need not include a lot of extra data when deleting or even changing an object.  While, an object contained in an add event or unfiltered response follows the data model schemas, a change event should only contain the information that has changed and a delete event only requires the RefId containing root.  For instance the following message has been validated (at : http://compliance.sifinfo.org/validate/).

<SIF_Message xmlns="http://www.sifinfo.org/infrastructure/2.x" Version="2.0r1">
  <SIF_Event>
    <SIF_Header>
      <SIF_MsgId>00000131AA65EE3A000A849450E61D66</SIF_MsgId>
      <SIF_Timestamp>2011-08-08T10:17:12</SIF_Timestamp>
      <SIF_Security>
        <SIF_SecureChannel>
          <SIF_AuthenticationLevel>0</SIF_AuthenticationLevel>
          <SIF_EncryptionLevel>0</SIF_EncryptionLevel>
        </SIF_SecureChannel>
      </SIF_Security>
      <SIF_SourceId>SIF_Empty_Query_Agent</SIF_SourceId>
      <SIF_Contexts>
        <SIF_Context>SIF_Default</SIF_Context>
      </SIF_Contexts>
    </SIF_Header>
    <SIF_ObjectData>
      <SIF_EventObject ObjectName="StudentPersonal" Action="Delete">
        <StudentPersonal xmlns="http://www.sifinfo.org/infrastructure/2.x" RefId="731A0F05E5C899B1E861322F5E6422B3" />
      </SIF_EventObject>
    </SIF_ObjectData>
  </SIF_Event>
</SIF_Message>

So if we were to use a special convention to specify the RefId when deleting an object, we would not save much in the way of network resources.  On the other hand, consistency brings simplicity in processing, which in turn saves resources there.


What should an agent do with the payload if received?

Retrieve the RefId and ignore the rest of the object to be deleted.  Of course you may be interested in related objects impacted by the delete, however those decisions should be based on the copy of the object in your database and not the one received.

Monday, June 27, 2011

Documentation is for Everyone

Whenever someone is new to the Test Harness, I point out two important documents to read and understand.  The first is the FAQ the second is the HTTPS documentation.

FAQ:  http://compliance.sifinfo.org/sifcompliance/docs/faq.html
HTTPS:  http://compliance.sifinfo.org/sifcompliance/docs/HTTPS.jsp

Last week one of our members contacted me in the final stages of certifying one of their products.  Given only one class of tests remained, I figured we were way beyond anything the FAQ may cover.  Unfortunately, I was both right and wrong.  While the FAQ did not cover all the details involved in this situation, it proved to provide better background information than myself.  So if you will excuse me, I have some rereading to do.

John W. Lovell

Saturday, June 25, 2011

The limits of XML validation ... and how to extend them

Each XML element in the schema (XSD) for an XML document can be defined to be either mandatory or optional, depending upon the associated value of its “minoccurs” facet. If set to a zero (default) the element does not have to appear in the XML for the document to be valid. If set to a one, it must appear at least once or the XML document will be invalid. The problem is that this simplistic “all or nothing” metric results in almost all elements in a given document being declared as optional.
As a result, “valid” XML documents may be constructed which are missing key data elements necessary for providing an acceptable level of application interoperability.
What’s in a Name?
Consider “Middle Name”. Some students don’t have one, which means it must be an optional element of a Student object. Yet during testing, it is important to validate that an application can include a middle name in the “Create Event” for a Student, if the student does in fact have a middle name. Until now, there was no effective way to ensure that.
One obvious solution is to change the XML schema used during testing, to make Middle Name mandatory. So in the test cases at least, every student just happens to have a middle name, and if the application does not include it, it is a validation error.
Validation in the 4th Dimension
This rather straightforward solution comes up short in a few important cases. When many schools create a new section of an existing course, they may do so before assigning a room or a teacher to that section. This means the Create Event for a Section object cannot be required to contain the teacher or room even in a test situation, because that would violate the defined way the “Create Section” process evolves over time. Yet before any section can become “active” the Section object provider must issue one or more Change Events which contain these elements. But how can this time-based process requirement be verified?
The whole is greater than the sum of its parts
This issue was particularly challenging for the US Data Profile team, whose charter is to “define a higher level of SIF certification testing and to collaborate on a identifying the key set of K-12 objects and elements utilized by multiple states”. They had identified a set of currently optional SIF elements which needed to be provided by any application being certified to the US Data Profile. These included both middle name and the teacher of a section.
Their solution to ensuring whether a SIF application truly provides all “supported elements” rests on the following two techniques:
1. Every test case will include the supported element
2. The supported element will be made mandatory in the schema of the object response message
The first technique handles supported elements like “middle name”. The second allows supported elements to be provided in either the Create Event or in a later Change Event. The elements remain optional in these schemas and no validation error results if the element is missing from one or more of these Events. But at some point during the testing, a Request of the object will be issued and the Response must contain the element.
In this way, it can be verified that any application certified for the US Data Profile does in fact provide all Supported elements. This technique will be reused elsewhere in the SIF standard to tighten certification testing and increase the level of out of the box (OOB) interoperability between certified SIF applications.

Monday, May 9, 2011

SIF v2.5 Web Service Release is now publicly available!

The new SIF release which integrates SOAP / WSDL web service technologies into the existing SIF standard is now publicly available on the SIF v2.5 release website

So what does this mean for current and potential future SIF adopters?

Enhanced Functionality
For openers, by making the educational data, and particularly the student data within a SIF Zone available to web service applications created with industry standard tool kits,  it is now significantly easier to integrate SIF components into District and State level computing environments, and to find and train SIF developers to create and manage them.

Ease of Migration
This new web service functionality was specifically designed to strengthen rather than obsolete earlier investments in developing and deploying SIF solutions.  From the very beginning, the strategy for incorporating web service technology into the SIF infrastructure was to “embrace” rather than to “replace”.  

As a result, Web Services now comprise a second SIF reference infrastructure, equal and completely interoperable with the first, and SIF Web Service applications are both backwards and forwards compatible with all SIF applications developed to either infrastructure. Once a Zone Integration Server (ZIS)   (see Section 3.3.2 SIF Zone Architecture) has been upgraded to version 2.5, it will do the necessary bridging so that whenever a SIF web service is subsequently installed it will seamlessly interoperate with all previously deployed SIF applications (supporting either infrastructure stack).

To Web Services ... and Beyond!
The extensive features of the SIF Zone infrastructure:
  • Guaranteed message delivery
  • Content based routing
  • Publish and subscribe
  • Service auto discovery
  • Data security (encryption, authentication,m authorization)
are provided  to these new SIF web services as well.  This should significantly reduces the amount of logic (and programmer time) associated with ensuring this level of functionality in many other web service environments, and where needed, eases the integration between a SIF Zone and any Enterprise Service Bus (ESB) middleware.

A “SIF Web Service Developer’s Toolkit” is also included with this release.  It comes complete with a set of WSDL files and SOAP Binding XML Schema that combined with the separate SIF Web Service volume of the v2.5 specification, will greatly  facilitate the construction of new SIF Web Services as well as the conversion of existing SIF applications.

SIF v2.5 -  it's a very major minor release indeed!


Saturday, April 16, 2011

WSDL 2.0 vs. WSDL 1.1

In selecting the set of normative dependencies for the SIF v2.5 web services infrastructure, WSDL was the obvious choice for defining the interface (the set of operations) supported by the SIF Zone.  The issue was then which version of WSDL to adopt.

WSDL 2.0

The arguments for the adoption of WSDL v2.0 were primarily based on its areas of enhanced functionality.  Of these, the ones of possible importance to SIF were:
  • Support for additional message patterns (ex:  “Out – Multi In” could correspond to Register for Events, Receive 0-n Events)
  • Better and more powerful fault handling notation, allowing clearer and easier reuse of WSDL segments within the WSDL file.
  • Improved SOAP v1.2 bindings which default many formerly explicit parameters to reduce the likelihood of interoperability problems.
  • Support for interface inheritance
All of these would bring increased clarity and structure to any v2.0 WSDLs SIF might publish. In addition, since WSDL 2.0 migration is difficult (when a service updates to WSDL 2.0, all client stubs must be upgraded at that time), then if a normative WSDL v2.0 dependency were to eventually be decided on for SIF,  it would make great sense to do so at the beginning.

 WSDL 1.1

The arguments against the adoption of WSDL v2.0 included the following (of which the first was considered the decider).
  • WSDL 2.0 is  not supported by most Java and .NET based developer toolkits (Apache being a notable exception)
  • WSDL 2.0 had gained little industry traction in the 3 years since the specification was formally approved.  What little WSDL 2.0 adoption there is, is currently centered around REST and not SOAP.
  • All comparable industry standards in the Education space utilize WSDL v1.1
 Decision
The Zone WSDLs for the SIF v2.5 release are provided in WSDL 1.1 only, and that is the only version the ZIS is required to support.


SOAP vs. REST

  There were 2 clear choices facing us regarding the selection of the transport layer to be used for the new SIF Web Service infrastructure appearing in the SIF v2.5 release:  SOAP or REST.  After some deliberation, the choice was made to go with SOAP.  The thinking behind that decision is discussed below,.

REST

REST is growing in popularity in those architectures where the client and service relationship is “casual”.  An example of this would be a public web site accessed across the internet by a browser, which may not access the site again.  Probably the major advantages of REST web services are:
  • Lightweight - not a lot of extra XML on the wire
  • Human Readable Results (no intermediate layer)
  • Easy to construct - minimal toolkit / conventions required
REST is also targeted primarily at supporting simple CRUD service interfaces, whereas most existing toolsets (ex: Apache CXF) use a SOAP-based IDE to expose pieces of application logic (as opposed to data) as web services, and automatically generate services and server stubs from a supplied WSDL file.

SOAP
SOAP and the WS-* technologies that leverage it are currently the leading choice for architects constructing a  B2B transport within the enterprise, especially for mission critical applications.  These generally have specific support requirements in the areas of security, reliable messaging and stateful (transactional) business process execution. 

Decision Points
It is this B2B paradigm for server connection which most closely parallels the environment of the existing SIF Zone.  In both the Zone and within an enterprise, services register centrally and there is standards-based administrative control of service message authentication and access authorization 

While the SIF Infrastructure Service WSDL wrapping the ZIS is currently a CRUD service, this is not likely to be the case for long, as the current SIF Services roadmap calls for web service equivalents of previously defined Zone Services such as Assessment, Student Locator and Student Record Exchange.  SOAP is a much better candidate transport for supporting this extension.

Interestingly, of the comparable educational industry standards (IMS, PESC, LETSI, ADL/SCORM) all currently have SOAP as part of their web service frameworks and none have REST, although several of them are investigating its use.

Finally, this decision is not irrevocable.  Should there be an unanticipated surge in REST adoption within the K-12 organization, it can conceivably be added as a 3rd reference infrastructure using the same ZIS-based transport bridge architecture used to integrate SOAP and the original HTTPS transport.



Tuesday, March 22, 2011

SIF and Web Services Part 1 - Background

With the anticipated release of SIF v2.5 in early 2011, the long sought after capability to write a SIF application as a pure web service, using a standard web service tool kit, will become a reality. 

The International SIF Association

The SIF Association is now truly international!  This year the Association has legally modified its non-profit organizational structure to help address the global interoperable needs in education – they are more similar than you think.  There is now an overarching international Association Board of Directors made up of representatives from leaders from the AU, UK and US Local Management Boards directing the local SIF community activities.  There also now is an International Technical Board supporting the global development and usage of the technical tools developed by all communities.  This new structure allows for global governance while still allowing for local control to address the unique needs within each community.  There are now Specifications developed in each community, certification programs supporting quality control for developers and purchasers and localized functional groups addressing locally identified needed functionality to better enable the identification, management, movement and usage of educational data.  For more information on the Association’s international activities visit: http://www.sifassociation.org/us/upload/presentations/5F3D1A_SIFAnnualMeeting2011_International.pdf

Monday, March 14, 2011

SIF Universal State Data Profile


There has been an increasing and immediate need to define those data that are universally collected and utilized within state departments of education. The SIF Association is uniquely poised to bring together states, districts and vendors in a collaborative effort to define a Universal State Data Profile (USDP).