1 Preamble

1.1 Abstract

1.1.1 What is SIF?

The Schools Interoperability Framework (SIF) is not a product, but a technical blueprint for enabling diverse applications to interact and share data related to entities in the pK-12 instructional and administrative environment. SIF is designed to:

• Facilitate data sharing and reporting between applications without incurring expensive customer development costs;
• Enhance product functionality efficiently; and
• Provide best-of-breed solutions to customers easily and seamlessly.

The SIF Implementation Specification defines:

• an XML-based messaging framework that allows diverse software applications to interoperate and share and report data related to entities in the pK-12 instructional and administrative environment;
• an HTTP(S)-based transport for conveying these SIF messages;
• an abstract, platform-independent definition of a message queue for reliable delivery of asynchronous SIF messages and related synchronous administrative functions—the Zone Integration Server (ZIS); and
• an abstract, platform-independent definition of the interface between a software application and the ZIS—the SIF Agent.

These are known collectively as the SIF Infrastructure. The SIF Implementation Specification also defines the SIF Data Model:

• an XML-based data model that models entities in the pK-12 environment as SIF Data Objects to be shared between applications.

A SIF Zone is a distributed system that consists of a ZIS and one or more software applications with a SIF Agent (a SIF-enabled application) sharing/reporting one or more SIF data objects over a network. A SIF Implementation consists of one or more SIF Zones deployed and configured to meet customer data sharing and reporting needs.

The SIF Implementation Specification defines architecture requirements and communication protocols for software components and the interfaces between them; it makes no assumption of specific hardware or software products needed to develop SIF-enabled applications and Zone Integration Server implementations, other than their ability to support technologies leveraged as the foundation for SIF, most prominently XML and HTTP(S).

1.1.2 Schools Interoperability Framework Association

The Schools Interoperability Framework Association (SIF Association) is an industry initiative to enable interoperability and data sharing between software applications in the pK-12 instructional and administrative environment, and the forum for companies and educators to participate in the development of SIF specifications in the SIF Association's working groups and task forces. The SIF Association is designed to:

• Join industry leaders in creating the next-generation framework for education technology; and
• Leverage co-marketing opportunities with partners and distributors.

1.2 Disclaimer

The information, software, products, and services included in the SIF Implementation Specification may include inaccuracies or typographical errors. Changes are periodically added to the information herein. The SIF Association may make improvements and/or changes in this document at any time without notification. Information contained in this document should not be relied upon for personal, medical, legal, or financial decisions. Appropriate professionals should be consulted for advice tailored to specific situations.

THE SIF ASSOCIATION, ITS PARTICIPANT(S), AND THIRD PARTY CONTENT PROVIDERS MAKE NO REPRESENTATIONS ABOUT THE SUITABILITY, RELIABILITY, TIMELINESS, AND ACCURACY OF THE INFORMATION, SOFTWARE, PRODUCTS, SERVICES, AND RELATED GRAPHICS CONTAINED IN THIS DOCUMENT FOR ANY PURPOSE. ALL SUCH INFORMATION, SOFTWARE, PRODUCTS, SERVICES, AND RELATED GRAPHICS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. THE SIF ASSOCIATION AND/OR ITS PARTICIPANT(S) HEREBY DISCLAIM ALL WARRANTIES AND CONDITIONS WITH REGARD TO THIS INFORMATION, SOFTWARE, PRODUCTS, SERVICES, AND RELATED GRAPHICS, INCLUDING ALL IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT.

IN NO EVENT SHALL THE SIF ASSOCIATION, ITS PARTICIPANT(S), OR THIRD PARTY CONTENT PROVIDERS BE LIABLE FOR ANY DIRECT, INDIRECT, PUNITIVE, INCIDENTAL, SPECIAL, CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF USE, DATA, OR PROFITS, ARISING OUT OF OR IN ANY WAY CONNECTED WITH THE USE OR PERFORMANCE OF THIS DOCUMENT, WITH THE DELAY OR INABILITY TO USE THE DOCUMENT, THE PROVISION OF OR FAILURE TO PROVIDE SERVICES, OR FOR ANY INFORMATION, SOFTWARE, PRODUCTS, SERVICES AND RELATED GRAPHICS OBTAINED THROUGH THIS DOCUMENT OR OTHERWISE ARISING OUT OF THE USE OF THIS DOCUMENT, WHETHER BASED ON CONTRACT, TORT, STRICT LIABILITY, OR OTHERWISE, EVEN IF THE SIF ASSOCIATION, ITS PARTICIPANT(S), OR THIRD PARTY CONTENT PROVIDERS HAVE BEEN ADVISED OF THE POSSIBILITY OF DAMAGES. BECAUSE SOME STATES/JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU. IF YOU ARE DISSATISFIED WITH ANY PORTION OF THIS DOCUMENT OR WITH ANY OF THESE TERMS OF USE, YOUR SOLE AND EXCLUSIVE REMEDY IS TO DISCONTINUE USING THIS DOCUMENT.

This specification is released with the following provisos to developers and educators.

1.3 Certification and Compliance Claims

2 Introduction

2.1 Specification Organization

2.2 Document Conventions

2.2.1 Definitions

The first time a term or concept is defined, it may be emphasized.

2.2.2 Structure and Values

SIF message and object names, XML element tags, attribute names and values, and other codes or values are typically presented as in this sentence.

2.2.3 Examples

2.2.4 References

2.2.5 Terminology

2.2.6 XML Diagrams

Quick overviews of XML structures, including messages, objects, common elements and types, are provided in XML diagrams. The following diagram illustrates the conventions typically encountered in SIF.

XML elements are represented by rectangles with the name of the element in the upper portion and the type, if any, in the lower portion. Attributes are represented in the same fashion, but have an @ icon rather than a SIF icon. Elements and attributes that are optional have a circled ? (0 or 1 occurrence) to the left of the rectangle. Optional and mandatory repeatable elements are indicated by a circled * (0 or more occurrences) and + (1 or more occurrences), respectively. Element attributes are grouped together in a rectangular block and connected to the element with a line that turns at right angles. Ordered sequences of XML elements are bracketed by lines that turn at right angles. When a choice of XML elements is indicated, the elements are bracketed by angled lines. A choice of elements can occur within an element, or may be an unnamed choice of elements.

XML types are represented using the same conventions as for XML elements, though the type portion of the rectangle typically indicates a base type, if any.

The type name of any element, attribute or type may be prefixed with a ↓, indicating the type is restricted in some fashion by one or more XML Schema facets (e.g. enumeration). When the type is a union of types, a list of types is presented, each type separated by |; if the list of union types is long, the list may be ellipted with | ...

In an actual XML diagram, element, type and attribute rectangles are usually linked to their corresponding definitions/descriptions in accompanying tables.

2.3 Version Numbers

The SIF Implementation Specification uses the following version numbering scheme:

major version.minor versionrrevision number

Major versions typically introduce additions/changes to the SIF infrastructure and/or data model changes that impact a significant percentage of SIF-enabled applications (e.g. making previously optional elements mandatory, removal of deprecated objects, elements or values). The first release of a major version has a minor version of 0 (2.0); major version numbers start at 1 and are incremented as major versions are released (1.0, 2.0, 3.0, ...).

Minor releases typically introduce new data objects, or optional additions to data objects, to the marketplace, and may include minor infrastructure additions/changes that do not impact existing SIF-enabled applications and that ZIS vendors have agreed to implement. The first minor version released subsequent to and within a major release has a minor version of 1 and is incremented as new minor versions are released (2.1, 2.2, ...). If a significant number of minor release features is introduced in a specification, the SIF Association may decide to increment the minor version number by more than 1 (e.g. 1.1 to 1.5), though a number like 1.5 is not an indication of being halfway to a major release, as minor version numbers may be incremented significantly past 10 (2.10, 2.11, ...) as data objects and other minor version features are released.

Corrections resulting from identified errata, as well as textual changes, may be incorporated into a revision release. These typically include minor corrections to messages or data objects, corrections of typographical errors, or corrected/expanded documentation. If major errors in any release are identified, a revision release may incorporate changes more typical of a major or minor release. First major and minor releases have a revision number of 0, which is omitted from the version number (2.0, not 2.0r0); subsequent revision numbers start at 1 and are incremented as new revisions are released (2.0r1, 2.0r2, ...).

2.4 Highlighted Additions/Changes Since Version 2.2

2.4.1 Data Model

3 Architecture

3.1 Assumptions

The following assumptions are made of non-technical readers of this specification, especially end users undertaking SIF implementations:

3.1.1 Notes on Related Technologies

3.2 Concepts

This section presents the ideas behind the implementation of SIF, including the application and data models on which it is based. It serves as a precursor to further descriptions in following sections.

3.2.1 Data Model

3.2.2 Zone Architecture

Although there are many variations of SIF topographies, the common feature is that a number of applications wish to share data. All SIF implementations, regardless of their complexity, consist of one or more applications with their associated agents communicating via a Zone Integration Server (ZIS).

One typical use of SIF is to connect products from various vendors together within a single school. These applications could include a student information application, a food service program, and a library automation application. Each of these applications has a vendor-provided interface program called an Agent.

Since the same school shares these applications, it makes sense to group them together into a logical entity. This entity is referred to as a Zone and is managed by a Zone Integration Server (ZIS).

There are no predefined sizes for zones, so a zone can be as large or small as required in order to meet the needs of the customer.

An application relies on its agent to exchange data using a predefined data model. Agents then communicate with other agents using the ZIS as a routing resource. The ZIS also provides access control so the customer can control which applications have access to which SIF data.

3.2.2.1 Contexts

The Zone is the primary means of partitioning data, applications, and policies. Zones are typically organized around geographic boundaries (e.g. school, district, region, state) or functional boundaries (e.g. horizontal integration, student locator services, data warehousing and reporting services). A SIF Context offers the ability to further partition the data within a Zone, to offer different perspectives of the data based on customer needs and application abilities. For example, while a student information system typically serves as the source for student-related data in the default context of a zone that integrates applications in a school or district, a data warehouse might better be suited to provide a historical or longitudinal perspective of that exact same student data in a different context, a context more suited to the reporting and data warehousing needs of an implementation. Contexts enable customers and system integrators to work with data in new ways while retaining the zone topologies commonly in use in implementations.

In addition to offering different perspectives on a zone's data, contexts allow two or more agents to register as a provider of the same object type within a zone. This may lead to future solutions built around contexts; for example, to better define how systems that publish similar objects cooperate in the same zone (e.g. student information systems and special education packages). Contexts also make it easier to apply a different set of business rules to different audiences. Unlike zones, which can be named and assembled in a variety of ways at the discretion of system integrators, contexts are to be treated as a part of the specification. The SIF Association sanctions contexts and provides documentation that defines each context's purpose and any associated message choreographies and business rules for it. Contexts defined by the SIF Association have context names that begin with SIF_ and the default context for a zone is named SIF_Default. It is RECOMMENDED that all ZIS implementations support the SIF Association-defined contexts as they are introduced; support for user-defined contexts is strictly implementation dependent, and agents are discouraged from relying on ad hoc or user-defined contexts.

3.2.3 Infrastructure and Messaging

Agents share data in a Zone via two models, the Publish/Subscribe model and the Request/Response model. Agents publish data changes of interest to subscribers by sending a SIF_Event message to the ZIS. Agents can also request or query data from other agents in a Zone by sending a SIF_Request message to an Agent, eventually being sent one or more SIF_Response messages in return. This exchange of messages over a SIF-defined transport layer, SIF HTTPS or SIF HTTP, is the primary feature that defines the SIF Infrastructure. Every message exchanged over this infrastructure is wrapped inside a SIF_Message and contains a SIF_Header element that specifies the source of the message and optional security, destination and context information. In addition to the messages exchanged between Agents via the ZIS, the SIF Infrastructure defines a number of messages that are exchanged between Agent and ZIS, and between ZIS and Push-mode Agent—these serve primarily to register various Agent settings at the ZIS and to support the exchange of messages between Agents.

3.2.4 Data Provision: A Request/Response Model

When an application (the Requester) wants to gather data from a specific data object, a SIF_Request message is sent to ZIS. The application may direct this request to a given Responder by specifying an Agent ID in the SIF_DestinationId element of SIF_Header. In most cases, however, the SIF_DestinationId element is omitted in which case the ZIS routes the request to the default responder, or Provider, for the data object of interest. Agents register as Providers with the ZIS using either the SIF_Provision or SIF_Provide message.

There is a single Provider per object per context per zone. There may be multiple Responders for a given object in a zone context.

In order to maintain control over what data is exchanged over the zone and who exchanges it, the ZIS must provide an access control system that limits who can provide, request, and respond to requests for which data objects. The access control system must maintain policies for each registered application.

If the requester knows or wants to control who the responder will be, it must place the responder's agent identifier in the SIF_DestinationId element of the header of the SIF_Request message. The ZIS will examine the SIF_Request message's header. If a SIF_DestinationId element is present, the ZIS must route the SIF_Request to the specified agent/application subject to the limitations imposed by the access control security policies for the zone. For instance, even though an application specifies that it wishes a specified application to respond, the zone security policy may prohibit the specified application from generating SIF_Response messages.

An application that wants to provide access to the data it contains via SIF may function as a responder. Such applications will support one or more SIF data objects. The application listens for SIF_Request messages for the objects that it supports. When it receives a SIF_Request for a supported object, the application will generate one or more SIF_Response messages containing the application's data, which will be routed by the ZIS to the requester. The responder must place the requester's agent identifier in the SIF_DestinationId element of the header for each SIF_Response message generated.

When an application receives a SIF_Request for a data object that it does not support, it must return a SIF_Response message with the SIF_Error element populated to indicate the nature of the error (invalid object), a SIF_PacketNumber of 1 and the SIF_MorePackets element set to indicate that no further packets will be sent in response to the SIF_Request.

3.2.5 Event Reporting: A Publish/Subscribe Model

Applications propagate data updates by publishing SIF_Event messages for the SIF data objects that are being added, changed, or deleted. In order for an application to receive these SIF_Events, subscriptions for the SIF data objects of interest must be entered at the ZIS. This subscription process is performed when an application sends a SIF_Provision message or one or more SIF_Subscribe messages to the ZIS. Once the subscriptions are entered, any SIF_Events for those objects received by the ZIS will be routed to the list of subscribers for those objects.

Once an application successfully sends a SIF_Event to the ZIS, the ZIS is responsible for delivering that SIF_Event to the subscribing parties without any further communication to the SIF_Event originator. The SIF_Event originator does not know how many applications, if any, receive the SIF_Event. No notifications are provided to the originator to indicate whether a SIF_Event was delivered to a subscriber or not.

The ZIS must maintain an access control system that limits who can publish and subscribe to events for which data objects.

Before an application can utilize the services of the ZIS, the application must register itself by sending a SIF_Register message to the ZIS. Once registered, an application does not have to perform any additional registration with the ZIS in order to be a publisher of SIF_Event data. Any application that has registered itself with the ZIS may publish SIF_Events subject to the limitations imposed by the access control security policies for the zone. It is recommended that event publishers register their ability to publish events by using the SIF_Provision message.

Multiple applications may publish SIF_Event messages for a given data object.

The application that is registered as the Provider for a given data object must be able to subscribe to SIF_Events for that object but the application is not required to subscribe to SIF_Events in a given SIF implementation.

An application that has subscribed to a SIF_Event must attempt to process the SIF_Event according to the business rules of the application. If the SIF_Event contains insufficient information or information that is inconsistent with the application's business rules, the application may ignore the message.

If an application publishes a SIF_Event as a result of changing the data within the application and the ZIS rejects the SIF_Event message, it is recommended that the application rolls back or cancels the changes that were made, but the application does not have to roll back the changes. For example, an application may attempt to add a new student and publish a SIF_Event to reflect the addition. If the application does not have permission to publish SIF_Event messages for that type of object, the SIF_Event is rejected. The application does not have to remove the newly added student from its local database.

3.2.6 Communication: An Asynchronous Model

In order to ensure scalability and reliability, SIF requires that its request/response and publish/subscribe models be asynchronous in nature. Once a ZIS synchronously acknowledges receipt of a SIF_Event, SIF_Request or SIF_Response with the return of a successful SIF_Ack, an agent cannot be assured that these messages will immediately be delivered to subscribers, providers/responders or requesters, respectively, or that it will receive an immediate SIF_Response to any submitted SIF_Request.

The asynchronous communication model can be likened to communicating with someone via e-mail or through the postal office: an individual sends the message, but does not know when it will be received, much less when the receiver will respond.

By requiring asynchronous communications, a SIF implementation can exploit software designs that achieve high scalability and reliability. For example, even if an agent is not currently connected to a Zone, another application's agent can still send messages to that agent knowing that the ZIS will deliver those messages as soon as the agent is available.

In contrast to the asynchronous communication model, most agent-to-ZIS and ZIS-to-agent communication—over currently defined transport layers—is synchronous in nature. Any time an agent sends a SIF_Message to a ZIS, the agent waits for a SIF_Ack to be returned from the ZIS to acknowledge receipt of the message. Once acknowledged, the ZIS guarantees future delivery of SIF_Event, SIF_Request and SIF_Response messages, barring certain error conditions. For messages not directly related to the request/response and publish/subscribe models, the acknowledgement from the ZIS also indicates successful completion of operations related to registration, subscription, provision and system control operations. Relatedly, when a ZIS contacts an agent in Push mode, the ZIS waits for a SIF_Ack to be returned from the agent to acknowledge successful delivery of the message currently pending for the agent.

3.2.7 Security Model

The security model of SIF centers around three areas: encryption, authentication and access control. SIF provides application agents the ability to specify the encryption and authentication requirements for all other agents that eventually come into contact with their sensitive data. Various communication protocols over which SIF data may be transferred, including SIF HTTPS, provide built-in support for easing the implementation details of guaranteeing encryption and authentication requirements. In addition, access control at the ZIS allows a zone administrator complete control over which agents are allowed to communicate which data to other agents.

As SIF HTTPS is the default communication protocol that all agents and ZIS implementations must support, many of the encryption and authentication levels specified in this document are tailored to the encryption and authentication algorithms currently defined within SIF HTTPS. When a ZIS implementation supports other communication protocols, the ZIS must guarantee that these levels are accurately reflected and adhered to when communicating with agents that support these same protocols.

3.2.7.1 Encryption

Encryption provides the mechanism to ensure that only the sender and receiver of a message can view the message contents. In a totally secure model, all communications between agent and ZIS will be encrypted. The SIF HTTPS protocol, which must be supported by all agents and ZIS implementations, is a secure transport and provides encryption of the data being exchanged.

If additional communication protocols, or transports, are used, it is important to know if these transports are secure to avoid exposing sensitive data. SIF provides a method for an agent to specify to the ZIS how secure the channel between the ZIS and other agents must be when ultimately delivering the originating agent's sensitive data. ZIS implementations must guarantee the requested security levels when communicating with recipient agents, regardless of which transport is in use. If a ZIS is unable to ensure these security levels when communicating with a recipient agent, the ZIS must not transport the message across the insufficiently secure channel. It is recommended that the ZIS log the inability to deliver the message to the recipient agent due to security requirements.

The responsibility for guaranteeing the security of data that an originating agent transfers to the ZIS lies ultimately with the originating agent, or zone administrators. For example, if the originating agent requires a very secure channel for a given message, it should not intentionally or inadvertently communicate that message to the ZIS over an insecure or insufficiently secure channel, should the ZIS support such channels. At that point, the data has already been communicated insecurely. Zone administrators can prevent such occurrences by configuring the ZIS and agents within the zone such that a minimum security level is maintained, below which communication is impossible.

In many cases, the establishment of a secure channel and encryption can be delegated to the transport layer.

3.2.7.2 Authentication and Validation

The role of authentication is to provide a means to ensure that the author of a message is the actual author. Authentication guards against a situation where a foreign agent claims to be a legitimate zone participant and fakes a message to gain access or alter the SIF data.

Another important role of authentication is to provide the ability to detect that each message that passes through the Zone arrives at its destination unaltered by other intermediaries.

Authentication support is optional but highly recommended.

3.2.7.3 Access Control

SIF must be customizable for specific deployments. This particularly applies to customization for the security policies. For example, a SIF administrator can specify which applications can participate in the SIF deployment, which data objects each application can provide or request, and what events each application can produce and receive.

The access control requirements are discussed more fully under ZIS Requirements.

3.3 SIF Architecture

3.3.1 Architectural Components

A SIF Zone is a distributed networking system that consists of a Zone Integration Server (ZIS) and one or more integration Agents. The size of a zone is flexible and could consist of a single building, school, a small group of schools, a district, a region, a state, a nation, etc. SIF is a scalable solution for data exchange. A SIF Implementation consists of one or more SIF Zones deployed and configured to meet customer data sharing and reporting needs.

A Zone Integration Server is a program that provides integration services to all the agents registered with it so that they can provide data, subscribe to events, publish events, request data, and respond to requests. It is responsible for all access control and routing within the Zone.

Each application requires an agent, which typically is provided by the application vendor, to communicate with other applications via the ZIS and their respective agents. For example, a school may use a student information application, a food service application, and a library automation application. Each of these applications must have an agent that acts as a go-between between the application and the Zone Integration Server.

In SIF, an agent never communicates with another agent directly. Instead, each agent communicates with the ZIS as a trusted intermediary that brokers the exchange of data with other agents. Having the ZIS manage routing responsibilities allows complex communications to occur between agents that have no direct information about each other and that may or may not be available for communication at any given point in time.

The following diagram illustrates a typical single-zone SIF implementation for a school.

A zone is often defined according to physical boundaries; for example, a zone can consist of all the applications that are connected over a private network and managed by one organization, such as a school. Security, scalability, and manageability requirements can also influence the decision of how zones are designed and configured.

Zones are a flexible and powerfully creative tool for meeting the data exchange and reporting needs of users; zones can be as varied as the customers in the education marketplace. While a single school zone may meet the needs of a single school, SIF implementations can scale to meet the needs of specific end users through the use of multiple zones, sometimes managed by different ZIS implementations. Two examples of many multiple-zone implementation design patterns are included here for illustration.

In the first, the data exchange needs of a district are met through the use of four zones, one for the district, and three for schools within the district: elementary, middle and high school. Here a student information system provides its complete set of district-wide data to a district zone, while providing school-based views of and access to that data in the individual school zones. Library systems in this implementation are school-based, while the food services system, like the SIS, is district-based.

The second example illustrates an agent communicating in both a district and a state zone. This agent could be associated with many different types of applications, including a SIS or data warehouse, reporting date up to the state, or an application that supports StudentLocator, managing state-level student identifiers, and so on.

Multiply the district portion of this diagram by dozens or hundreds of districts, each with its own local zone or configuration of zones, and the distributed scalability of SIF using zones is readily apparent.

3.3.2 Naming Conventions for Agents and Zone Integration Servers

SIF requires that each agent and ZIS be identified with a distinct case-sensitive identifier that is unique within a zone. This identifier is carried inside the SIF_SourceId element of the SIF_Header included in each SIF message and is used, among other things, at the ZIS to reference access control permissions of each agent within the zone. It is recommended that agent and ZIS implementations have user-configurable identifiers in order for zone administrators to maintain unique identifiers within the zone.

The identifier should be descriptive of the role of the application in the zone. For example, the library automation agent for Ramsey Elementary might carry the identifier RamseyLib instead of the less descriptive CC41Agent. The Zone Integration Server for Ramsey might be known as RamseyZIS.

3.3.3 Object Identifiers

3.3.3.1 Persistence

When used as identifiers for objects that persist over time—take for instance the StudentPersonal object that represents a student in a Zone—it is SIF's intent that object identifiers not change over time. The RefId attribute for John Doe in first grade should have the same value when John Doe is in second grade, in middle school or in high school. This persistence of object identifiers enables longitudinal tracking of data within SIF, especially where there exist no locally unique identifiers associated with objects. Implementations SHOULD avoid reassignment of object identifiers within a zone and as the primary home for individual objects may move from one zone to zone over time (e.g. a student moving from a middle-school to a high-school zone).

3.3.4 Agent/Application Requirements

Each application that wants to be a SIF application, or SIF-enabled application, must have an agent written for it. An agent is an extension to the application that communicates with the ZIS. An agent can be an integral part of an application itself, or may be a separate, specialized client of or interface to an application.

All applications that are part of a SIF zone must be able to gracefully handle all SIF messages including those messages and data objects that the application does not support. It is RECOMMENDED that the application return an error SIF_Ack message to the ZIS for those messages that the agent does not support (error category Generic Message Handling, error code "Message not supported"). An agent MAY return an "Immediate" SIF_Ack to the ZIS and ignore unsupported messages.

3.3.4.1 Communicate with the ZIS

3.3.4.2 Transmit Application Changes to the ZIS

When an application makes changes to its data that correspond to a SIF object it supports, the application MUST be able to publish SIF_Events reflecting those data changes. If the application/agent makes changes to its data in processing a SIF_Event it has received, it MUST NOT publish an event that duplicates the changes as described in the processed SIF_Event. Should the application/agent, however, make additional changes beyond those in the SIF_Event being processed, the application SHOULD generate a new event describing the additional changes.

If an application does not support an optional field of an object or that element was not changed during the last edit, it MUST NOT send an empty element, (i.e., <BirthDate/> or <BirthDate></BirthDate> ); it MUST omit the element from the XML stream instead.

3.3.4.3 Respond to Requests

All agents MUST be prepared to handle SIF_Request messages for all objects gracefully. In the case where an agent receives a SIF_Request for an object that it does not support, in addition to acknowledging the receipt of the message to the ZIS it MUST send a SIF_Response message to the Requester with the SIF_Error element populated to indicate the nature of the error (invalid object), a SIF_PacketNumber of 1 and the SIF_MorePackets element set to indicate that no further packets will be sent in response to the SIF_Request.

If an application agent is a responder for any object, the agent must be prepared to process SIF_Request messages for that object. This involves the ability of the agent to traverse the application database and construct an XML response stream based upon the parameters of the query request. All responders MUST support SIF_Query and query conditions that reference root attributes of the object as well as any mandatory elements within the object, along with their mandatory attributes. Responders SHOULD support query conditions that reference optional elements and their attributes, when the application supports such queries. Responders MAY support SIF_ExtendedQuery and MUST register their support for SIF_ExtendedQuery using SIF_Provision and/or SIF_Provide.

When an agent is creating SIF_Response packets, it MUST attempt to ensure that each packet is no larger than the SIF_MaxBufferSize specified by the SIF_Request. If for any packet a single packet does fit within the supplied SIF_MaxBufferSize, the agent MUST, in addition to acknowledging receipt of the message to the ZIS, send a SIF_Response message to the Requester with the SIF_Error element populated to indicate the nature of the error, and the SIF_MorePackets element set to indicate that no further packets will be sent in response to the SIF_Request.

The SIF_Request message also contains SIF_Version elements that specify which SIF versions the responding agent should use when preparing the response packets. If a responding agent can support a single requested SIF version, it returns a response packet using that version. If more than one version is specified and the responding agent supports more than one of those versions it SHOULD respond with the highest version it supports. If the agent cannot support any requested SIF version, in addition to acknowledging receipt of the message to the ZIS, the agent MUST send a SIF_Response message to the Requester with the SIF_Error element populated to indicate the nature of the error, a SIF_PacketNumber of 1 and the SIF_MorePackets element set to indicate that no further packets will be sent in response to the SIF_Request.

If any other error occurs while creating SIF_Response packets for a given request, in addition to acknowledging receipt of the message to the ZIS, the agent MUST send a SIF_Response message to the Requester with the SIF_Error element populated to indicate the nature of the error, with SIF_MorePackets set to indicate that no further packets will be sent in response to the SIF_Request.

Agents supporting SIF_Requests MUST be able to return all of the object fields that the responding application supports or a subset of the fields as specified by the query request. For example, an Agent may request that only a student's graduation year be returned and not the entire StudentPersonal object. If the responder does not support a requested element, it MUST NOT exclude the object from the response stream. Any requested element that is unsupported is omitted from the response stream; when processing SIF_Query requests, parent elements of requested elements, including the object itself, are included in the response stream.

If an application does not support an optional element of an object, it MUST NOT return an empty element. The element MUST instead be omitted from the XML stream.

3.3.4.4 Changes Required to the Vendor's Application

Depending upon the type of architecture, the core application may need to be altered to ensure that the agent is able to forward changes to objects of interest to SIF. For example, an application that edits student data may need to be modified to capture the adds, changes, and deletes made to students and store them into a temporary repository until the agent can forward them to the ZIS. Other architectures provide the ability to trap these changes at a server level eliminating the need for any changes to the application itself.

To meet the SIF requirement of data robustness, it is highly RECOMMENDED that all changes to objects of interest to SIF be persisted using a database table, local message queue, or other highly reliable storage system. This specification allows for the ZIS and any or all agents to be offline at any given time. Without storing agent changes locally, these changes can be lost when the ZIS is temporarily unavailable; local storage allows these changes to be transmitted to the ZIS when it becomes available.

When an object is shared for the first time in SIF, it is the responsibility of the application making the object available to assign its object identifiers/primary keys, typically a RefId in the form of a GUID, before releasing that object to the zone in an Add event or in a SIF_Response. Some application databases are extended to include SIF object identifiers, others maintain mappings from SIF object identifiers to locally-defined keys.

If an application changes data that maps to a SIF object, it is RECOMMENDED that only the changed fields be sent to the zone. This will result in smaller message sizes and improved performance.

To avoid unintentional overwriting of data, unsupported fields or fields that have not been changed MUST NOT be sent to the zone using empty XML elements, (i.e. <Name Type="04"/> or <Name Type="04"></Name> ); the fields MUST be omitted from the XML stream instead.

3.3.4.5 Support Authentication and Digital Signatures

Supporting authentication is not a requirement but it is highly RECOMMENDED to ensure that your agent will be able to communicate with any ZIS. SIF does not mandate the use of authentication, but it is feasible that many SIF implementations will require this functionality. This is especially true for installations that may use the Internet to transport data.

Typically the authentication and verification mechanisms that are built into the network operating system or transport protocol can be leveraged. If these services are available, authentication and verification take place completely within the underlying security package.

The SIF HTTPS protocol supports authentication between an agent and a ZIS. If authentication is enabled and properly configured, a message receiver (agent or ZIS) can trust the SIF HTTPS implementation to verify that the message in its entirety comes from the claimed sender.

3.3.4.6 Agent Local Queue

An Agent can be developed with a local queuing mechanism so that it can automatically cache incoming messages in a local queue and can acknowledge receipt of each message to the ZIS with "Immediate" SIF_Ack messages (which causes the ZIS to remove received messages from the agent's queue). Agents with an Agent Local Queue do not need to send any "Intermediate" SIF_Acks to the ZIS. Use of an Agent Local Queue can be used to locally support selective processing of messages, similar to the functionality provided by Selective Message Blocking; its use also allows more flexibility and robustness during application/system failure when successfully acknowledging events, requests and/or responses before performing the corresponding SIF_Event, SIF_Request and/or SIF_Response handling.

Agent Local Queue is not a required feature of any Agent. Agent developers can choose not to develop the Agent Local Queue mechanism since this is not part of the compliance requirements for the specification at this time.

3.3.4.7 Wildcard Version Support

3.3.5 Zone Integration Server Requirements

The Zone Integration Server is the central integration point for all the agents in a zone. Depending on the message type, a ZIS either saves information in the messages that it receives or forwards the messages to other appropriate agents.

The ZIS implementer is free to internally manage registration and access permissions information in any form that the implementer supports. In order to provide an example of how an administration system may be structured, this document describes a database consisting of an Access Control List and Zone Status.

3.3.5.1 Access Control List

A ZIS MAY maintain access control on whether a zone administrator has granted an agent permissions to register.

A ZIS MAY exhibit behavior with regard to the ACL that could be perceived by an Agent as if virtual tables exists defining the following information:

An example of this virtual table, which defines which agents are allowed to register in the zone, might be as follows:

In addition, a ZIS MUST exhibit behavior with regard to the ACL that could be perceived by an Agent as maintaining per-context/per-object permissions for each message associated with SIF's Publish/Subscribe and Request/Response models. When an agent tries to inquire about a student's personal information, for example, the ZIS needs to check if the agent has the proper permission to request such information. Access control is needed to ensure that the information available in SIF only originates from and is accessible by authorized agents.

It is important to understand that this is a virtual table, defining the appearance of the functionality to the Agents, the actual implementation of this functionality is at the discretion of the implementers of a ZIS. An example follows:

In addition to access control permission violations, attempts to register any of this functionality with the ZIS may fail due to other reasons; e.g. unsupported transport mechanisms, there already being a provider for an object, etc. As a result, an Agent SHOULD be able to gracefully handle corresponding error conditions or report those errors to a zone administrator.

3.3.5.2 Zone Status

The ZIS MUST maintain the status of the zone for implementation purposes, as well as for communicating this status to other agents, as defined in SIF_ZoneStatus, when requested. This status includes but is not limited to:

• product information about the ZIS;
• supported transport protocols, authentication methods and SIF versions;
• supported contexts (see below for more information);
• the currently registered agents, along with applicable registration settings and the current state of each agent; and
• lists of currently registered providers, subscribers, publishers, responders, and requesters.

3.3.5.3 Zone Context Registry

Zone Integration Servers MUST maintain a registry of the contexts used in each zone in order to perform contextual message routing and to populate the SIF_ZoneStatus/SIF_Contexts element. This registry will always contain, at a minimum, the official list of contexts defined by the version of SIF that the ZIS supports. Beginning with SIF 2.0, that means that each zone will, at a minimum, support the SIF_Default context. A ZIS MAY support allowing additional contexts to be defined within the context registry at the discretion of the ZIS administrator. Access Control Lists within each context MUST also be able to be managed by the ZIS administrator. The set of permissions for each agent within each context MUST be able to be set differently than ACL permissions within a different context for the same agent.

An agent can obtain a list of all contexts currently defined in a zone by requesting the SIF_ZoneStatus object and enumerating the children of its SIF_Contexts element. An agent can determine its ACL permissions within the zone and each context by referring to the SIF_AgentACL object and enumerating the permissions and contexts defined within it.

3.3.5.4 Administration

A ZIS MUST provide an interface for Zone Administrators to configure zone settings, including access control permissions. Given the distributed nature of SIF, it is RECOMMENDED this be a Web-based interface. Some of the areas that require administration are:

Administration

Start and stop the ZIS and/or set the state of the ZIS to "asleep" or "awake."

Security Policies

A ZIS must provide an interface for administering access control permissions as described above.

Administering the minimum SIF_EncryptionLevel for the zone (if only one encryption level is supported, configuration options are unnecessary).

Administering the minimum SIF_AuthenticationLevel for the zone (if only one authentication level is supported, configuration options are unnecessary).

It may also include installing client and server certificate administration.

Zone Settings

If the ZIS supports more than one SIF version it must support configuration of which SIF versions are used in a zone.

If the ZIS supports more than one transport protocol, it must allow for configuration of which transports agents can use to communicate, including limiting communication to SIF HTTPS.

The ZIS must support configuration of the minimum acceptable SIF_MaxBufferSize for the zone.

If message validation is supported and configurable, configuration to enable or disable message validation in a Zone should be available.

Logging

Capture error and message logs to aid in tracking pending, successful and failed delivery of messages.

Reporting

Report zone status and statistics.

Testing

Provide a mechanism to "ping" Push-Mode agents.

3.3.5.5 Support Selective Message Blocking (SMB) to Resolve Deadlocks

3.3.5.5.1 Description

Selective Message Blocking is a feature that MUST be implemented by a ZIS to enable non-multitasking agents unable to persist portions of their message queue locally to request information from other Agents while processing a SIF_Event message, without causing communication "deadlock" between an agent and a ZIS.

This feature allows an agent to inform the ZIS with an "Intermediate" SIF_Ack message that the ZIS must temporarily stop delivering SIF_Event messages to the agent. The "Intermediate" SIF_Ack message must not be used by agents in response to messages other than SIF_Event. The ZIS, however, can deliver other agent-destined messages, SIF_Request and SIF_Response, to this agent. After it finishes processing the SIF_Event message this agent sends the "Final" SIF_Ack message to the ZIS, which will discard the blocked SIF_Event message and resume normal delivery of all messages, including SIF_Events. SMB is supported for both Push and Pull modes.

3.3.5.5.2 Requirements

• If, after attempting delivery of a SIF_Event message to an agent, the ZIS receives an Intermediate SIF_Ack (SIF_Status/SIF_Code=2) from the agent, the event is blocked and all SIF_Event messages destined for the agent, whether already in the queue or that arrive while blocked, are considered frozen. The ZIS will not deliver any SIF_Event messages that are frozen.
• If no SIF_Ack at all is received, or if a transport error occurs, this SIF_Event must be considered an undelivered message. The next message to be delivered to the agent will be this event.
• The ZIS must not deliver another SIF_Event message to the agent until a "Final" SIF_Ack is received (SIF_Status/SIF_Code=3), giving the ZIS permission to discard the original event and resume event delivery. The SIF_OriginalMsgId in the "Final" SIF_Ack MUST contain the SIF_MsgId of the blocked SIF_Event.
• If SIF_Events are frozen, the next message to be delivered is the oldest message that is not a SIF_Event message. Once SIF_Events are unfrozen, all remaining messages in this agent's queue, including SIF_Events, will be delivered in the order in which they have been received by the ZIS.
• If the ZIS receives a SIF_Wakeup or SIF_Register message then the block on any frozen SIF_Event messages will be removed and the originally blocked message will be the next message delivered to the Agent.

3.3.5.5.3 Example

3.3.6 Message Processing

To ensure interoperability, SIF defines a set of messages that are exchanged between agents and Zone Integration Servers. The SIF messages are used to perform various operations such as provision, subscription, event reporting, request and response, and ZIS administration.

3.3.6.1 Message Validation

SIF recommends that each message receiver validate any incoming message to ensure that it is a valid SIF message. A message receiver should discard any messages that do not conform to the definition of SIF_Message and return an error to the originator of the message.

This specification will evolve over time to include new messages and modifications to messages that have been defined. Each agent and ZIS should explicitly define which version(s) of the specification they support and validate each incoming message according to its version.

3.3.6.2 Message Identification

3.3.6.3 Message Security

Because of policy or legislation, providers of extremely sensitive data must never expose that data over an insecure channel. An insecure channel at delivery time is one whose levels of authentication (SIF_AuthenticationLevel) and data encryption (SIF_EncryptionLevel) fall below the values specified by the originating sender. Once the data is communicated to the ZIS, the originator of the message depends upon the ZIS to enforce the security levels requested and the ZIS must not deliver that message to recipient agents using an insecure channel. The originating agent requests the use of a secure channel at delivery time by incorporating a SIF_Security element in the header of the message. The SIF_Security element contains SIF_AuthenticationLevel and SIF_EncryptionLevel elements that define the minimum level of security a data transport channel must provide upon delivery. If a ZIS does not deliver a message due to insufficient security of the connection with a recipient agent, it is recommended that the ZIS log the inability to deliver the message due to security requirements.

The only SIF messages that currently originate with an agent and that are ultimately delivered to other agents are SIF_Request, SIF_Response and SIF_Event. An originating agent may add a SIF_Security element to all messages, but these three messages are the only ones where SIF_Security will be examined and processed by the ZIS. SIF_Security is used by an originating agent to specify the security requirements of the communication channel between the ZIS and any recipient agent at delivery time. The semantics of including the SIF_Security element on messages other than SIF_Request, SIF_Response and SIF_Event are reserved for future versions of the specification.

The specification provides several levels of authentication and encryption protection.

3.3.6.3.1 SIF_AuthenticationLevel

0

No authentication required and a valid certificate does not need to be presented.

1

A valid certificate must be presented.

2

A valid certificate from a trusted certificate authority must be presented.

3

A valid certificate from a trusted certificate authority must be presented and the CN field of the certificate's Subject entry must match the host sending the certificate.

The CN field is more commonly known as the "Common Name" field. SIF_AuthenticationLevel 3 requires that the CN contents match the host where the message was originated. For instance, a CN entry could be "sifinfo.org" or perhaps "207.95.37.30". If a ZIS at SifInfo.org (IP address 207.95.37.30) contacts an agent at MyAgent.sifinfo.org, the agent's SIF HTTPS transport layer can look at the CN entry in the certificate that was presented by the ZIS and compare it to the actual IP address of the ZIS. SIF_AuthenticationLevel 3 ensures that not only a valid and trusted certificate was presented but that the agent is actually communicating to the ZIS located at the IP address referenced in the certificate.

Because security is a cornerstone of the SIF specification, it is recommended that all ZIS and Agent implementations support client authentication as well as server authentication. When client authentication is being used, the connection first authenticates the server (the party that is being contacted) and if the authentication was successful, the server will request that the client present its certificate for authentication. In this manner, both the ZIS and the agent confirm that they are communicating with the proper parties.

Since client authentication is not universally available in all SIF HTTPS implementations, client authentication is only recommended. The need for client authentication is reduced somewhat by using asynchronous message delivery (Push mode) since the ZIS and the agent are both server type applications and will authenticate each other. The need for client authentication is greater for those agents polling for messages (Pull mode) because the ZIS never has to initiate contact with the agent.

3.3.6.3.2 SIF_EncryptionLevel

0

No encryption required

1

Symmetric key length of at least 40 bits is to be used

2

Symmetric key length of at least 56 bits is to be used

3

Symmetric key length of at least 80 bits is to be used

4

Symmetric key length of at least 128 bits is to be used

If a SIF_Request, SIF_Response or SIF_Event is received by the ZIS that does not contain a SIF_Security element, the ZIS assigns the lowest level (0) to both the SIF_AuthenticationLevel and SIF_EncryptionLevel requirements for the message, unless a Zone administrator has configured higher minimum encryption and authentication levels for the Zone. This means that the ZIS may distribute this message to any agent that has registered with the ZIS subject to the access control security provisions in place for the zone.

The lack of a SIF_Security element does not mean that the message will be transported in an insecure manner. Recipient agents communicating with the ZIS over secure channels will receive the message in a secure manner, consistent with the connection. Omitting the SIF_Security element simply allows for those agents that communicate over insecure channels to receive the message, should a zone allow for insecure channels. A zone administrator can prevent messages without SIF_Security elements being communicated over insecure channels by configuring the ZIS and agents in the zone such that a minimum security level is maintained, below which communication is impossible.

For ZIS and agent implementations that support communication protocols or transport implementations where the security of a channel cannot be determined at delivery time, it is recommended that the zone administrator configure the ZIS and agents in the zone such that a minimum security level is maintained, below which insecure connections cannot be established.

3.3.6.3.3 Notes on SIF_AuthenticationLevel

If authentication based on certificates is being used, care needs to be given to determine if Level 2 (anonymous certificates) will provide the necessary level of protection. With Level 2 authentication, it is possible to use a web browser to make secure connections to the ZIS using the certificates that are built into the browser. This level of authentication is what is used by almost all Internet transactions (stock trading, shopping, financial, etc.). Level 2 does expose the user to a risk of a "man-in-the-middle" attack that can't occur using Level 3 authentication.

Level 3 mandates that a certificate issued by a trusted authority, (i.e. school district), be installed in the web browser before the browser will be able to connect to the ZIS. This may place unnecessary burdens on the client especially if it is likely that authorized users may wish to connect to the ZIS using a variety of browsers.

3.3.6.3.4 Notes on SIF_EncryptionLevel

3.3.6.4 Message Robustness

It is important for SIF to guarantee message delivery no matter what happens during delivery of a message, including an unexpected network breakdown or system crash. This requires that each agent and ZIS save each message in permanent storage. At delivery time it is also possible, however, for a ZIS to be prohibited from delivering a message due to security requirements requested by originating agents for individual messages. If this occurs, it is recommended that ZIS implementations discard the affected message so that delivery of other messages may proceed. If the ZIS does discard the message, the ZIS MUST report a SIF_LogEntry event with the appropriate error category and code, containing a copy of the SIF_Header from the original message. In addition, it is recommended that the ZIS log the delivery failure to its own log.

When a message is delivered under normal circumstances by a ZIS, an agent will return an "Immediate" SIF_Ack or a SIF_Ack with any applicable error condition, signaling the ZIS that it may delete the message from permanent storage. In the case of events, agents may also return an "Intermediate" SIF_Ack to invoke Selective Message Blocking (SMB). In that case, the ZIS will not delete the current SIF_Event from permanent storage until the agent sends a "Final" SIF_Ack to the ZIS.

When a message is sent to the ZIS under normal circumstances by an agent, the ZIS returns a successful SIF_Ack or a SIF_Ack with any applicable error condition to indicate to the agent that it has in fact received the message and that the agent may delete the message from any permanent storage.

If a ZIS or agent encounters a transport error in sending a message, it is recommended that the sender retry sending the message. Transport errors where retrying the message is warranted include, but are not limited to, a connection close without a SIF_Ack returned, a transport error or a SIF_Ack with an error category of 10 indicating a connection cannot currently be established, etc. A ZIS in particular must retry delivery of messages from the agent queue until a SIF_Ack that removes the message from the agent's queue is received, subject to certain undeliverable error conditions (e.g. security requirements cannot be negotiated, maximum buffer size too small, etc.). Facing such error conditions, other potentially unresolvable transport errors, or if a SIF_Ack is returned with any other type of error category, the sender may decide not to retry or—when queued, to delete—a message to avoid a potential deadlock condition. Agents returning SIF_Ack messages with error conditions should be aware that such acknowledgements will remove the currently pending message from their delivery queue.

3.3.6.5 Message Cycle

All SIF messages follow the same model. The sender posts a message and receives a SIF_Ack back as a response. The posting of the message by the sender and the receipt of the SIF_Ack from the receiver constitutes one complete cycle. Agents and ZISes can function as senders or receivers, depending on the type of message. The message process is identical, regardless of the type of message being sent.

If for any reason a sender inadvertently resends a message with a given SIF_MsgId and the receiver detects this, the receiver may return a SIF_Status code indicating that it already has the message. This SIF_Status code is considered a success; the receiver simply discards the duplicate message and continues handling of the original message.

3.3.6.6 Message Delivery

There are two models for delivering messages to an agent, "Push" and "Pull." An agent specifies which mode it wants to use when it registers with the ZIS.

"Push" refers to the action by a ZIS to actively deliver messages to an agent without the agent having to initiate contact with the ZIS. When the ZIS receives a message for an agent and the agent is not in "Sleep" mode; the ZIS will initiate contact with the agent and send the message to the agent.

"Pull" refers to the action by an agent to explicitly request a single message from the ZIS. When an agent is ready to receive a message, it sends a "Pull" request to the ZIS, to obtain a message that the ZIS has saved in the queue for the agent. After receiving the pull request, the ZIS will examine the agent's queue and either returns a message or a status code indicating that no messages are available for the agent.

Both modes serve useful purposes. The key requirement is that both an agent and its ZIS must communicate using the SAME mode to avoid potential conflicts.

At delivery time, be it in push or pull mode, a ZIS may encounter messages that it is prohibited from delivering, e.g. due to security requirements requested by originating agents for individual messages, etc. If this occurs, it is recommended that ZIS implementations discard the affected message(s) so that delivery of other messages may proceed. If the ZIS does discard a message, the ZIS MUST report a SIF_LogEntry event with the appropriate error category and code, containing a copy of the SIF_Header from the original message. SIF_LogEntry/SIF_Desc must contain the SourceId of the agent that has failed to receive the message. In addition, it is recommended that the ZIS log the delivery failure to its own log.

3.3.6.6.1 The "Push" Model

When an agent has registered using the "Push" mode, the agent assumes that the ZIS will open a transport connection and send the next available message to the agent. An agent can reply to the sent message with an "Immediate" or optionally—in the case of SIF_Events—an "Intermediate" SIF_Ack, invoking Selective Message Blocking (SMB); it can also reply using a SIF_Ack with any applicable error condition. "Immediate" or error SIF_Acks remove the current message from the agent's queue, freeing any remaining or future messages to be delivered to the agent. A "Final" SIF_Ack sent to the ZIS will terminate SMB, removing the frozen event from the agent's queue, freeing any remaining or future messages to be delivered to the agent.

3.3.6.6.2 The "Pull" Model

When an agent has registered using the "Pull" mode, the agent requests a message from the ZIS by sending a SIF_GetMessage message to the ZIS.

An agent can only issue a SIF_GetMessage to request a message if the agent has previously sent a successful SIF_Register message specifying Pull mode. If the ZIS receives a SIF_GetMessage request and the agent hasn't registered using the Pull mode, the ZIS must return a SIF_Ack containing an error category of Registration and an error code indicating that the agent has registered using Push mode.

After receiving a SIF_GetMessage request from an agent, the ZIS will return the next message available for delivery to the agent, subject to Selective Message Blocking. The criteria used to select the message are identical to that used if the ZIS were to Push a message to an agent.

If a message is available for the agent, the ZIS will return a SIF_Ack message with a SIF_Status/SIF_Code of 0 and SIF_Status/SIF_Data containing the message from the queue:

When a pull-mode agent supports multiple SIF specification versions, the version of the SIF_Ack message returned by the ZIS must match the version of any SIF_Message contained in SIF_Status/SIF_Data. For example, if an agent supports versions 1.1 and 1.5 (or 1.*) and the next message in the agent's queue has a SIF_Message/@Version value of 1.5, the Version attribute of the SIF_Ack message returned by the ZIS must be 1.5, even if the pull-mode agent sent its SIF_GetMessage in a 1.1 SIF_Message. For an agent that supports both 1.1 or later versions and pre-1.1 version(s) (e.g. 1.0r2), when the next message in the agent's queue is from a pre-1.1 agent, the ZIS must return the message in a SIF_Ack message as defined by the pre-1.1 specification.

A pull-mode agent removes the returned message from its queue in one of three ways. In each case the value for the SIF_OriginalMsgId element in any SIF_Ack(s) created by the agent originates from the SIF_MsgId of the SIF_Message returned as SIF_Data by the ZIS. Typically a pull-mode agent removes the message from its queue by sending an "Immediate" SIF_Ack to the ZIS; an agent may also send a SIF_Ack with any applicable error condition to the ZIS. The ZIS then removes the message from the agent's queue and returns a successful SIF_Ack. If the message is a SIF_Event and the agent wishes to invoke SMB, it can instead notify the ZIS that it is processing the event by sending an "Intermediate" SIF_Ack (which the ZIS acknowledges with a successful SIF_Ack) and later sending a "Final" SIF_Ack when the SIF_Event processing is complete. When the ZIS receives the "Final" SIF_Ack, it removes the SIF_Event from the agent's queue and returns a successful SIF_Ack.

If there are no messages in the agent's queue that can be delivered, the ZIS will return a SIF_Ack message with a SIF_Status/SIF_Code of 9 to indicate that there are no messages available for the agent:

3.3.6.6.3 "Multiple Version" Zones

It is possible for a zone to contain agents written to different versions of the SIF Implementation Specification if a ZIS supports multiple versions in a zone and has at least one version in common with all registered agents. It is possible that two agents in the same zone—both successfully registered—have no version in common, and this affects message delivery by the ZIS in the following manner.

When the next message to be delivered to a given agent has a SIF_Message/@Version attribute that the agent is known not to support, the ZIS cannot successfully deliver that message to the agent without conversion. Should a ZIS implementation choose to convert messages on the fly as a "value-add" feature, it is free to do so; this specification does not prescribe how to convert messages, and support for such conversion is implementation-dependent. However, if the ZIS does not or cannot convert the message such that it can be delivered, it should discard the pending message so that delivery of other messages may proceed. If the ZIS does discard the message, the ZIS MUST report a SIF_LogEntry event with the appropriate error category and code, containing a copy of the SIF_Header from the original message. SIF_LogEntry/SIF_Desc must contain the SourceId of the agent that has failed to receive the message. In addition, it is recommended that the ZIS log the delivery failure to its own log.

3.3.7 Infrastructure Transport Layer

The Infrastructure messages are used by SIF to encapsulate and transfer the data objects. They form a messaging application program interface (API) which is expressed in XML.

It is a design objective to express the entire Infrastructure API in XML and not to have dependencies upon any underlying transport layer to provide functionality other than the transportation of the XML from client to server and back. This ensures that the Infrastructure messages can be carried over a variety of communication transports.

The infrastructure depends upon the transport layer to provide a reliable connection to move messages back and forth from client and server. The transport layer is also responsible for providing data security by means of data encryption and authentication of the client and server. Some transport layers even provide data compression, which is an important factor when processing a large volume of XML messages.

By delegating the authentication, compression, and encryption to the transport layer, it makes the user interface to the transport simpler. A client that wishes to send an infrastructure message assembles the message in XML and then hands it off to the transport layer for delivery. The transport layer takes the XML message and transfers it to the server where it is taken from the transport layer and processed.

In moving from the client to the server, the transport may have compressed, encrypted, and authenticated the connections but all of this is transparent to the users of the Infrastructure API. To the user, it is XML in and XML out.

Different types of transports are or will become available providing various features and benefits. An Agent or ZIS MAY employ multiple transport protocols but they MUST support SIF HTTPS.

Please note that throughout this specification transport layer errors are sometimes illustrated as SIF_Ack messages with SIF_Error/SIF_Category of Transport and applicable error codes. Under many transport error conditions, these SIF_Ack messages could not be returned or sent by the remote host. Depending on the SIF infrastructure transport layer implementation these messages may be generated by the implementation (e.g. when a connection to a server cannot be established), or may occur as transport layer errors or exceptions in the underlying network operating system or transport protocol. Both should be treated equivalently.

3.3.7.1 SIF HTTPS Transport

In order to ensure that Agents and Zone Integration Servers can communicate with each other regardless of vendor or platform, all Agent and ZIS implementations MUST support the SIF HTTPS transport layer protocol.

3.3.7.1.1 HTTPS Request/Response Model

A client is the party (Agent or ZIS) who initiates a connection to a remote machine. The remote end (ZIS or Push-Mode Agent) is known as the server.

A client using the SIF HTTPS protocol opens a connection to the server and sends a HTTP 1.1 POST request with the SIF Infrastructure XML message as the POST payload. The server responds with an HTTP response with the Infrastructure XML acknowledgement message as the response payload. Clients MUST encode the XML message using UTF-8; servers MUST be able to process UTF-8-encoded XML and SHOULD expect all incoming SIF XML messages to be encoded using UTF-8.

The default behavior for HTTP 1.1 is to use persistent or "keep-alive" connections. When operating in this mode, the client may send additional POST requests and receive the HTTP responses using the same connection. Clients SHOULD use persistent connections for performance reasons but MUST be able to use non-persistent connections if the server does not wish to use persistent connections.

3.3.7.1.2 HTTP Request Headers

Implementations of SIF HTTPS MUST be able to specify the value for the path (/MyPath in the example) as the Agent or ZIS may require a specific value for routing purposes.

3.3.7.1.3 HTTP Response Headers

The following HTTP response and common headers defined in [RFC 2616] must be present in all SIF HTTPS responses messages sent by a server:

Although the SIF HTTPS protocol uses the 200-OK response notice to communicate all responses, Agent or ZIS implementations could be built using existing web server infrastructures. As such, SIF HTTPS implementations should expect the possible receipt of other HTTP 1.1 response notices.

3.3.7.1.4 100 (Continue)

3.3.7.1.5 3XX, 4XX, 5XX Notices

A server should only return 200-OK response notices but may return other notices. Servers built using existing web server technology are more likely to return other types of response notices. If a client receives any 3xx, 4xx, or 5xx response notices, it must treat these responses as if a transport error has occurred.

3.3.7.2 SIF HTTP Transport

The SIF HTTP protocol is identical to the SIF HTTPS transport without a secure socket layer to provide data encryption and authentication.

An Agent or ZIS MAY implement the SIF HTTP transport but MUST implement the SIF HTTPS protocol.

Because of the sensitive data being exchanged in SIF, it is RECOMMENDED that only SIF HTTPS be used.

3.3.7.3 SIF HTTP(S) Transport Compression

The content encoding of any HTTP entity body, either in a request or a response, is indicated using the Content-Encoding header, which is considered a modifier to the Content-Type header. A client may compress or apply an encoding to the body of an HTTP request and indicate it has done so with an appropriate Content-Encoding value. It is recommended that a server that cannot or will not accept a particular encoding return a 415 (Unsupported Media Type) status code.

With these HTTP-defined headers, SIF Agents and Zone Integration Servers have the ability to compress or negotiate compression of SIF HTTP(S) request and response entity bodies using any version of SIF where the transport protocol is SIF HTTPS or SIF HTTP. However, to increase interoperability of Agents and Zone Integration Servers that wish to compress requests or receive compressed responses beyond the level of trial and error in an environment where server status codes are not guaranteed, the following mechanisms were developed in SIF Implementation Specification Version 2.1.

3.3.7.4 SIF_Protocol/SIF_Property Accept-Encoding

In both SIF_Register and SIF_ZoneStatus the following SIF_Property is defined when used in conjunction with a SIF_Protocol/@Type value of HTTPS or HTTP:

This property indicates that an HTTP(S) server can accept corresponding content encodings with an appropriate Content-Encoding header value.

The recommended compression algorithm for use in SIF is gzip. It is NOT RECOMMENDED that the identity (uncompressed) encoding ever be explicitly excluded in the Accept-Encoding SIF_Property.

3.3.7.5 HTTP Client Requirements

3.3.7.6 HTTP Server Requirements

A server (ZIS or Push-Mode Agent) that receives an HTTP request with an Accept-Encoding header MUST process the request per HTTP 1.1's Accept-Encoding specification. It is RECOMMENDED that servers return a 406 (Not Acceptable) status when a requested encoding cannot be negotiated.

A server that receives an HTTP request with a Content-Encoding header specified MUST process the request per HTTP 1.1's Content-Encoding specification. It is RECOMMENDED that servers unable to process a particular content encoding return a 415 (Unsupported Media Type) status code.

3.3.7.7 Push-Mode Agent Requirements

A Push-Mode Agent that wishes to receive compressed/encoded requests from the ZIS MUST register its preference with the ZIS in the SIF_Register/SIF_Protocol property entitled Accept-Encoding in SIF_Name, providing an Accept-Encoding value in SIF_Value per HTTP 1.1 (the recommended compression algorithm for SIF is gzip). The Agent MUST be prepared to handle an error SIF_Ack from the ZIS when registering Accept-Encoding (SIF_Error/SIF_Category of 5 [Registration], SIF_Error/SIF_Code value of 10) if the ZIS cannot support at least one specified encoding and SHOULD re-attempt registration without Accept-Encoding.

Upon successful registration of an Accept-Encoding value, the Agent SHOULD expect to receive requests from the ZIS encoded accordingly, but it MAY received identity-encoded (unencoded) requests unless identity was explicitly excluded in the registered Accept-Encoding value.

3.3.7.8 Zone Integration Server Requirements

A Zone Integration Server that receives a SIF_Register/SIF_Protocol/SIF_Property named Accept-Encoding in SIF_Name must fail the attempt to register if the ZIS does not support at least one of the specified encodings (SIF_Error/SIF_Category of 5 [Registration], SIF_Error/SIF_Code value of 10). While this property is typically registered by Push-Mode Agents, Pull-Mode Agents may also specify this property when registering. A ZIS SHOULD compress requests when contacting a Push-Mode Agent if the Agent has previously registered that preference, but it MAY send uncompressed requests if the Push-Mode Agent did not explicitly exclude the identity encoding in its registered Accept-Encoding value.

Zone Integration Servers that support handling of compressed/encoded requests SHOULD return an Accept-Encoding header SIF_Value in the SIF_ZoneStatus/SIF_SupportedProtocols/SIF_Protocol/SIF_Property named Accept-Encoding in SIF_Name.

4 Messaging

This section documents the messaging and message handling protocols defined in SIF. A messaging protocol consists of sending a SIF_Message to initiate an operation, receiving back a SIF_Ack; a message handling protocol consists of processing an incoming SIF_Message and responding with a SIF_Ack and possibly sending follow-up SIF_Messages. This section is independent of transport layer details, aside from encryption and authentication level impacts associated with individual messages. Unless otherwise noted, all protocols assume successful communication over the appropriate transport layer; agent and ZIS implementations should also be prepared to handle transport layer errors and exceptions, directly or wrapped in a SIF_Ack/SIF_Error by underlying code.

4.1 Agent Protocols

4.1.1 Agent Messaging Protocols

This section documents how Agents should send individual messages, and the resulting post-conditions upon success or failure, along with any necessary steps to take. These correspond to each of the operations an Agent can initiate.

4.1.1.1 SIF_Register

An Agent must register with the ZIS to participate in a Zone. To do so, it sends a SIF_Register message. An Agent may at any time re-register by sending another SIF_Register message. The ZIS updates the Agent's registered settings accordingly.

4.1.1.2 SIF_Unregister

An Agent removes itself from a Zone by sending a SIF_Unregister message to the ZIS. Successful completion of this operation removes all settings associated with the Agent, including the objects it is currently providing and subscribed to in the zone; the Agent's message queue is also deleted. Note that a successful SIF_Unregister message may, depending on the ZIS implementation, remove access control settings that have been manually configured by a Zone administrator and that may need to be re-configured for a subsequent successful SIF_Register.

4.1.1.3 SIF_Provide

4.1.1.4 SIF_Unprovide

4.1.1.5 SIF_Subscribe

4.1.1.6 SIF_Unsubscribe

4.1.1.7 SIF_Provision

The SIF_Provision message provides an Agent the ability to register the objects it provides and to which it subscribes in a single operation, replacing whatever settings the ZIS has on record for the Agent. In effect it is an alternative to SIF_Provide, SIF_Unprovide, SIF_Subscribe and SIF_Unsubscribe, though an Agent may choose to use this message or those, or a combination of these messages.

This message also allows the Agent to fully describe the operations it will perform in a Zone beyond those that can be communicated with SIF_Provide and SIF_Subscribe, including the types of events it will publish, the requests to which it will respond with or without being the Provider for requested objects, and the objects for which it sends requests.

The Agent must have the appropriate access control settings to successfully register any of the corresponding information included in SIF_Provision. Note that the list of access control settings can be determined by examining the SIF_AgentACL object returned in the SIF_Register or SIF_GetAgentACL message protocols.

Note that SIF_Provision will also fail if the Agent is attempting to provide an object that is already provided by another Agent in the applicable Zone Context. The list of Providers in a Zone can be found in SIF_ZoneStatus.

As of version 2.0 of this specification, SIF_Provision is the preferred method for provisioning an Agent. Support for SIF_Subscribe, SIF_Unsubscribe, SIF_Provide and SIF_Unprovide may be removed in a future major release of this specification.

4.1.1.8 SIF_Event

When an application adds, changes or deletes data represented in one or more Zone Contexts, its Agent SHOULD publish the corresponding Add, Change or Delete SIF_Event to the Zone. Upon successful delivery of a SIF_Event to the ZIS, the ZIS places the event in the queue for any Agents subscribed to events for the object, including your Agent if it is a subscriber.

4.1.1.9 SIF_Request

An Agent can request data from another Agent at any time by sending a SIF_Request message. Agents use one of two query mechanisms in requests. SIF's default query mechanism, SIF_Query, is used to request objects of a given type, matching optional query conditions, optionally returning a subset of object elements. SIF_ExtendedQuery is used to select elements from one or more objects, joined together, if necessary, on RefId-based conditions. Before delivering a request with a SIF_ExtendedQuery to a Responder, the ZIS checks that the Responder supports SIF_ExtendedQuery for all referenced objects.

4.1.1.10 SIF_Ping

4.1.1.11 SIF_Sleep

4.1.1.12 SIF_Wakeup

4.1.1.13 SIF_GetZoneStatus

4.1.1.14 SIF_GetAgentACL

4.1.1.15 SIF_CancelRequests

Agents can request that a ZIS cancel SIF_Requests, pending or in process, by sending a list of SIF_RequestMsgIds in a SIF_CancelRequests message. If an Agent abandons or restarts a data collection using SIF_Requests, whether or not the response stream has started, it is RECOMMENDED that the Agent send one or more SIF_CancelRequests messages to the ZIS. Such data collections can place a heavy load on responding Agents, where often all data of a specific object type is requested, and cancelling requests may spare Zone resources. Cancelling of responses can also reduce the number of response packets the receiving/cancelling agent needs to process and discard.

If the cancelling Agent wishes to receive a "final" SIF_Response from the ZIS for each cancelled message, it can specify Standard in SIF_CancelRequests/SIF_NotificationType. If the cancelling Agent does not desire or require "final" SIF_Responses, the Agent can specify None in SIF_NotificationType.

4.1.1.16 SIF_GetMessage (Pull-Mode only)

4.1.1.17 SIF_Ack (Push-Mode)

Push-Mode Agents end Selective Message Blocking (SMB) by sending a final SIF_Ack to the ZIS.

4.1.1.18 SIF_Ack (Pull-Mode)

Pull-mode Agents acknowledge messages received in response to SIF_GetMessage and remove them from their queue by sending a SIF_Ack message to the ZIS. SIF_Ack is also sent by Pull-Mode Agents to invoke and end Selective Message Blocking (SMB).

4.1.2 Agent Message Handling Protocols

This section documents how Agents should respond to incoming messages, and the resulting post-conditions upon success or failure, along with any necessary steps to take.

Note that in handling any SIF_Message, an Agent may return a SIF_Ack with SIF_Status/SIF_Code 8 (receiver is sleeping) or 7 (already have this SIF_MsgId from you) if a duplicate message is detected. These responses are typically omitted from the handling protocols below.

4.1.2.1 SIF_Message

Upon receipt of a generic message from the ZIS, in most cases it may be safely assumed that the message XML is well-formed, and perhaps even valid, but the Agent should take the following steps to determine whether the XML is well-formed, optionally validate the message, and check that the message is of a valid type before handing the message off to the respective message handling protocol below.

4.1.2.2 SIF_Event

A ZIS places a SIF_Event in your Agent's queue when an event occurs in a Zone Context with regard to an object for which your agent has subscribed to receive events. A SIF_Event is delivered when it is the next message pending delivery in the queue.

An event may apply to one or more contexts; these are listed in SIF_Header/SIF_Contexts. If SIF_Contexts is not present, the context for the event is SIF_Default. The type of event is specified in SIF_EventObject/@Action, the corresponding data object is in SIF_EventObject. A Change or Delete event may contain a partial object, but it must include the necessary attribute(s) and element(s) to uniquely identify the object being changed or deleted. These keys/identifiers are typically communicated in the root attributes of an object.

4.1.2.3 SIF_Request

A ZIS places a SIF_Request in your Agent's queue when an Agent sends a request directly to your Agent, or when an Agent sends a request without a SIF_DestinationId and your agent is registered as the Provider for the object requested in SIF_Query, or in the case of SIF_ExtendedQuery when your agent is registered as the Provider of the object specified by the Requester in SIF_ExtendedQuery/SIF_DestinationProvider or SIF_ExtendedQuery/SIF_From/@ObjectName. The ZIS will not send your Agent a SIF_ExtendedQuery unless your Agent has registered its support for that query type using SIF_Provide or SIF_Provision. A SIF_Request is delivered when it is the next message pending delivery in your Agent's queue.

Any error that occurs while generating SIF_Responses during SIF_Request handling MUST be sent to the Requester with SIF_MorePackets set to No, at which point the response stream ends.

4.1.2.4 SIF_Response

A ZIS places a SIF_Response in your Agent's queue when a responder sends a response packet to your Agent per a SIF_Request previously sent by your Agent. It is delivered when it is the next message available for delivery to your Agent.

4.1.2.5 SIF_Ping (Push-Mode only)

The ZIS is pinging your Agent to see if it is reachable, "awake" and/or processing messages.

4.1.2.6 SIF_Sleep (Push-Mode only)

The ZIS has changed its state to "asleep" and is either not processing incoming messages or all incoming messages will be acknowledged with a SIF_Ack/SIF_Status/SIF_Code value of 8 (receiver is sleeping); delivery of queued messages to your Agent is halted. Your Agent SHOULD avoid sending messages to the ZIS until receipt of a SIF_Wakeup message, or be prepared to handle transport errors or the aforementioned acknowledgement.

4.1.2.7 SIF_Wakeup (Push-Mode only)

The ZIS has changed its state to "awake" and is processing incoming messages and delivering queued messages again.

4.1.2.8 SIF_CancelRequests (Push-Mode only) (optional)

4.2 ZIS Protocols

4.2.1 ZIS Messaging Protocols

This section documents how Zone Integration Servers send individual messages, and the resulting post-conditions upon success or failure, along with any necessary steps to take. These correspond to each of the actions a Zone Integration Server can initiate.

4.2.1.1 SIF_Message Delivery (SIF_Event, SIF_Request, SIF_Response to a Push-mode Agent)

A ZIS contacts a Push-Mode Agent to deliver SIF_Event, SIF_Request and SIF_Response messages queued for the Agent. This delivery protocol starts with a check on whether there are messages pending, as the protocol can loop as messages are delivered.

4.2.1.2 SIF_Ping (to a Push-mode Agent)

4.2.1.3 SIF_Sleep (to a Push-mode Agent)

4.2.1.4 SIF_Wakeup (to a Push-mode Agent)

4.2.1.5 SIF_CancelRequests (to a Push-mode Agent)

4.2.2 ZIS Message Handling Protocols

This section documents how Zone Integration Servers should respond to incoming messages, and the resulting post-conditions upon success or failure, along with any necessary steps to take.

Note that in handling any SIF_Message, the ZIS can return a SIF_Ack with SIF_Status/SIF_Code 8 (receiver is sleeping) or 7 (already have this SIF_MsgId from you) if a duplicate message is detected. These responses are omitted from the handling protocols below.

4.2.2.1 SIF_Message

When a message is received, the ZIS should first validate the XML message. If the message is not SIF_Register, the ZIS should determine whether the sender is registered in the zone. If errors are found, a SIF_Ack with a SIF_Error element should be returned to the caller and no further processing should occur. If no errors are found, message processing proceeds according to message type. Subsequent message processing sections are assured of receiving well-formed and/or valid XML, and all non-SIF_Register message processing sections are assured that the agent is indeed registered with the zone.

4.2.2.2 SIF_Register

Before an agent can participate in a zone, it must register itself in order to provide the data that the ZIS needs to interact with the agent. This process is handled using a SIF_Register message.

An agent may also send the SIF_Register message when already registered. In this case, the ZIS should re-register the agent in the same manner as defined for initial registration. Any existing provision and subscription entries, as well as any pending messages, maintained by the ZIS for the agent should remain intact. Upon successful re-registration, any new or updated registration settings for the agent, including push mode protocol information, take effect after the ZIS has returned a successful SIF_Ack for the SIF_Register message.

4.2.2.3 SIF_Unregister

When an agent is going be removed from a Zone, the agent must send a SIF_Unregister message. When a ZIS receives this message from an agent, it performs those steps—ignoring SIF_Ack preparation and delivery—outlined for the SIF_Unprovide and SIF_Unsubscribe messages for any agent provisions or subscriptions, respectively. The ZIS then discards any messages pending for the agent. The ZIS will also remove any registration information and remove the agent from its list of registered agents.

It is recommended that the ZIS not remove access control data from its database as a replacement agent may be installed. Keeping the access permissions is optional, however.

4.2.2.4 SIF_Provide

An agent makes an object available to be requested by a process called Provision that is represented by the SIF_Provide message.

The SIF_Provide message can contain provision requests for multiple objects. The ZIS must treat all of the objects as a set; if there is an error with one of the objects then there should be no change to the Providers database.

4.2.2.5 SIF_Unprovide

If an agent wishes to withdraw an object previously provided, the SIF_Unprovide message is used.

The SIF_Unprovide message can contain multiple objects. The ZIS must treat all of the objects as a set; if there is an error with one of the objects then there should be no change to the Providers database.

4.2.2.6 SIF_Subscribe

An agent requests to receive SIF_Events for an object by a process called Subscription that is represented by the SIF_Subscribe message.

The SIF_Subscribe message can contain subscription requests for multiple objects. The ZIS must treat all of the objects as a set, if there is an error with one of the objects then there should be no change to the Subscribers database.

4.2.2.7 SIF_Unsubscribe

If an agent wishes to cancel one or more subscriptions, the SIF_Unsubscribe message is used. Events already queued for delivery prior to unsubscription will be delivered.

The SIF_Unsubscribe message can contain subscription requests for multiple objects. The ZIS must treat all of the objects as a set, if there is an error with one of the objects then there should be no change to the Subscribers database.

4.2.2.8 SIF_Provision

An Agent is registering its support for various messages with regard to various objects. Settings supplied replace any previously recorded settings for the Agent.

4.2.2.9 SIF_Event

When an application has made a change in an object that is part of the Zone and for which the application has declared the ability to generate SIF_Events, the agent will send a SIF_Event message to its Zone Integration Server so the framework may distribute it.

4.2.2.10 SIF_Request

When an agent needs information from a Zone context it sends a SIF_Request message to the ZIS. If the SIF_Request's header does not contain a SIF_DestinationId element, the ZIS will route the message to the Provider of the object referenced in the SIF_Request. If the header contains a SIF_DestinationId, the ZIS will route the message to the application referenced in the SIF_DestinationId if the security policies of the zone permit such routing. The ZIS will return a SIF_Ack message to the requesting agent to indicate whether or not it was able to process the SIF_Request message.

After the ZIS returns a success SIF_Ack to the requester, the ZIS will route the SIF_Request to the responder and the requesting agent may expect to receive one or more SIF_Response messages sent by the responder. However, the responder may not be currently on-line or it may not be able to immediately satisfy the SIF_Request. Therefore, requesting agents must not depend upon a timely response to their SIF_Request.

If the ZIS returns an error SIF_Ack, the requesting agent will not receive any SIF_Response messages from a responder.

4.2.2.11 SIF_Response

When receiving a SIF_Response packet from an agent responding to a SIF_Request, the ZIS MUST perform the validation protocol below.

4.2.2.11.1 Implementation Notes

The ZIS must maintain a reliable list of all open SIF_Requests in order to satisfy the Quality of Service validations that are applied to SIF_Responses above. It is envisioned that once a SIF_Response has been completed, either by receiving the last packet or by failing one of the validations applied below, knowledge of the initiating SIF_Request will no longer need to be maintained by the ZIS. If the responding agent attempts to send any more SIF_Responses for a failed SIF_Request, it will automatically fail at Step 2 and get the error response specified in Step 3. Notification of the failed SIF_Response would have already been sent to the requesting agent.

There remain three cases where a requesting agent will not receive a complete SIF_Response for a request.

1. The responding agent never replies with a SIF_Response.
2. The responding agent starts replying, but never finishes the SIF_Response by sending a SIF_Response with the SIF_MorePackets element set to "No".
3. The responding agent attempts a reply with a SIF_Response but the ZIS is unable to parse the message enough to read the SIF_RequestMsgId. If this case occurs, and the responding agent sends a subsequent SIF_Response that is parseable, it is likely that the requesting agent will be notified of the problem because subsequent SIF_Response packets will not pass the SIF_PacketNumber validation.

Management of the SIF_Request cache that is maintained by the ZIS is left up to the ZIS implementation. The ZIS is required to maintain the SIF_Requests for a reasonable amount of time. If the ZIS eventually removes SIF_Requests that have been cached for a long period of time, that option must be able to be configured by the ZIS administrator.

When an open request cache entry is removed by the administrator or a timeout of the record, the ZIS should publish a SIF_LogEntry and a SIF_Response/SIF_Error indicating the reason it was removed.

4.2.2.12 SIF_Ping

An Agent is pinging your ZIS to see if it is reachable, "awake" and/or processing messages.

4.2.2.13 SIF_Sleep

The Agent wants its state changed to "asleep." Upon successful state change, your ZIS SHOULD avoid sending messages to a Push-Mode Agent until receipt of a SIF_Wakeup message or that Agent re-registers, or be prepared to handle transport errors or the aforementioned acknowledgement. Whether the Agent is registered in Push or Pull mode, this state is communicated to other Agents in SIF_ZoneStatus and MUST be persisted accordingly. In addition to sending a SIF_Wakeup or SIF_Register, a Pull-Mode Agent can also change its state to "awake" by sending a SIF_GetMessage.

4.2.2.14 SIF_Wakeup

An Agent wants its state changed to "awake," notifying the ZIS and other Agents of the state change. A ZIS MUST persist this state in order to communicate it to other Agents via SIF_ZoneStatus. When a Push-Mode Agent changes its state to "awake," the ZIS may also resume delivery of queued messages to the Agent.

4.2.2.15 SIF_GetZoneStatus

An Agent is requesting the status of the zone.

4.2.2.16 SIF_GetAgentACL

An Agent is requesting its access control permissions.

4.2.2.17 SIF_CancelRequests

If an Agent abandons or restarts a data collection using SIF_Requests, whether or not the response stream has started, it is RECOMMENDED that it send one or more SIF_CancelRequests messages to the ZIS. Upon receipt of the SIF_CancelRequests message, the ZIS deletes corresponding SIF_Request messages from Agent queues and deletes its own state/tracking information regarding each request. Doing the latter ensures that if a Responder is still processing a request, the ZIS effectively ends the response stream upon receipt of the next SIF_Response packet by returning a SIF_Error with a SIF_Category of 8 (Request and Response Error) and a SIF_Code of 10 (invalid SIF_RequestMsgId specified in SIF_Response). No changes to responding Agent behaviors are required as all agents in the SIF 2.x lifecycle have the capability to handle this error state.

When cancelling SIF_Requests, the ZIS also has the ability to send a SIF_CancelRequests message to Push-Mode Agents. Pull-Mode Responders cannot receive these messages, but any pending response handling is cancelled per the ZIS behavior above. When dealing with Push-Mode Agents, ZIS implementations must bear in mind that support for this message is optional for Push-Mode Agents.

When a cancelling Agent specifies a NotificationType of Standard, it is the responsibility of the ZIS to end the response stream to the requesting Agent by sending a SIF_Response packet with a SIF_MorePackets of No on the Responder's behalf.

4.2.2.18 SIF_GetMessage

A Pull-Mode Agent is requesting the next message in its queue.

4.2.2.19 SIF_Ack (from a Push-Mode Agent)

A Push-Mode Agent is sending a final SIF_Ack to end Selective Message Blocking (SMB).

4.2.2.20 SIF_Ack (from a Pull-Mode Agent)

A Pull-Mode Agent is acknowledging a message it has retrieved using SIF_GetMessage. This typically leads to the message in question being removed from the Agent's queue. The Agent may also invoke Selective Message Blocking when acknowledging an event, blocking delivery of subsequent SIF_Events until Selective Message Blocking is ended by the Agent.

5 Infrastructure

This section presents the XML structure for Infrastructure common elements, messages and objects in a tabular format for readers less versed in parsing formal XML schema definitions.

The Char(acteristics) column for all of the tables in this section use the following codes:

5.1 Common Elements