5 Infrastructure

Contains one of the SIF message types.

The xmlns attribute specifies the XML namespace for SIF messages. For this version of the specification, the value of this attribute MUST be http://www.sifinfo.org/infrastructure/2.x. This XML namespace value will remain the same until the next major release of SIF (3.0).

Note that one SIF_Message may be contained within another when a ZIS delivers a Pull-Mode Agent's next message in a SIF_Ack response to a SIF_GetMessage from the Pull-Mode Agent. If the default namespace specified for the child SIF_Message is the same as the default namespace of the parent SIF_Message, the xmlns attribute for the child message MAY be omitted.

The version of the SIF Implementation Specification that defines this message's XML structure. For this version of the specification, the value of this attribute is 2.0. This attribute can be used by ZIS and agent implementations to choose schema files to validate the message's XML.

Header information associated with a message.

SIF_MsgId is a globally unique message identifier from the Agent or ZIS that sends out the message.

Timestamp of when the message was sent.

This element allows an originating agent to specify security requirements that the ZIS must ensure upon delivery of the message to recipient agents. SIF_Security is only examined and processed by a ZIS on SIF_Request, SIF_Response and SIF_Event messages. In this version of the specification, SIF_Security is ignored on all other messages; its use on other messages is reserved for future versions of this specification.

The originating agent uses this element to specify security requirements for the channel between the ZIS and any recipient agents at delivery time. The ZIS must ensure these requirements are met for this message when delivered to other agents.

The minimum level of authentication required by the message originator to be considered a secure channel upon message delivery to other agents.

The minimum level of encryption required by the message originator to be considered a secure channel upon message delivery to other agents.

The SIF_SourceId is the ID of the originator of the message. Each source needs to have a zone unique case-sensitive identifier.

This element represents the ID of the recipient of the message and may be present as follows:

SIF_Response messages MUST have this element set to the SIF_SourceId of the originator of the SIF_Request message. The ZIS will use this information to route the SIF_Response to the requesting agent.

SIF_Request messages MAY have this element set to the ID of a specific agent if the requesting agent wishes to direct the SIF_Request to a specific responder. If present, the ZIS will route the SIF_Request to the agent referenced in the element subject to the access control policies in effect for the zone.

This element SHOULD NOT be used in any other SIF Infrastructure messages. If the element is present, it will be ignored by the ZIS.

Contains each SIF Context that applies to the message. If omitted, the applicable context is SIF_Default. SIF_Context is repeatable for SIF_Events, not repeatable for SIF_Request or SIF_Response.

The minimum level of encryption required by the message originator to be considered a secure channel upon message delivery to other agents.

The minimum level of authentication required by the message originator to be considered a secure channel upon message delivery to other agents.

A list of SIF contexts that applies to a message or operation. Typically where used as an optional element, the omission of this element implies the SIF_Default context applies.

The name of a SIF Context that applies to a message or operation.

Contains protocol information for contacting a ZIS or Agent.

The type of protocol to use (HTTPS, HTTP or an implementation-defined protocol).

Whether the protocol provides a secure channel.

This element is required if the protocol is HTTPS or HTTP. It contains the https or http URL for contacting the agent.

If the protocol isn't HTTPS or HTTP then the SIF_Protocol element may contain zero or more SIF_Property elements. Each property element contains a SIF_Name/SIF_Value pair that describes a protocol setting for proper communication.

Property name.

Property value.

This element is used to signal a successful response.

An optional textual description/equivalent of SIF_Code.

Optional element to hold data related to a successful operation. This data is currently limited to a SIF_Message returned by the ZIS in response to a Pull-Mode Agent's SIF_GetMessage, SIF_AgentACL returned by the ZIS in response to SIF_Register and SIF_GetAgentACL, and SIF_ZoneStatus returned by the ZIS in response to SIF_GetZoneStatus.

This element is used to signal an unsuccessful response.

See Error Codes.

A simple, easy to understand, description of the error. The primary consumer of this message is the application user. Example: "Unable to open database."

An optional error description that is more complete and technical in nature. It is to be used as a diagnostic message in trouble-shooting procedures. Example: "The 'Students' table is opened in exclusive mode by user 'ADM1' (dbm.cpp, line 300)."

This is the object that is being queried for.

The actual name of the object that is being queried for.

Individual elements/attributes being requested of matching object. See SIF_Element Syntax below. If specified, only the elements/attributes requested are returned in the SIF_Response (with any parent elements/attributes); otherwise, all elements supported by the provider's object are returned.

Note that this is a means to filter or select a subset of elements/attributes from a matching object; specifying elements/attributes here that do not occur in or are not supported in a matching object does not exclude that matching object from being returned. Include any existing parent elements/attributes of the elements/attributes that are requested but not present.

Either SIF_ConditionGroup or SIF_Example may optionally be specified to present conditions matching objects should satisfy.

SIF_ConditionGroup represents the conditions that the queried object(s) must meet. If conditions are specified, only those objects that meet the conditions are returned; otherwise, all objects of the specified name are returned.

The Boolean operator for joining conditions (SIF_Conditions elements) within this element. Note that None should be used if there is only one SIF_Conditions element.

This construct allows for nested conditions.

The boolean operator for joining conditions (SIF_Condition elements) within this element. Note that None should be used if there is only one SIF_Condition element.

This element represents an individual condition.

This is the element/attribute being queried. See below for syntax.

The comparison operator for the condition.

SIF_Value is the data that is used to compare with the value of the element or attribute.

An example SIF object that serves as a template for matching objects. There is an implied EQ operator for every element/attribute value present and an implied And group of all resulting conditions. Currently this is an experimental feature and limited to use with StudentLocator; wider use may be considered in future versions of this specification.

SIF's default query mechanism for SIF_Request, SIF_Query, has several limitations that limit its usefulness when creating reporting applications that process data from a SIF zone. SIF_Query is limited to matching only one object type per query, requiring applications to manually join together results as needed for reporting and general data processing. SIF_ExtendedQuery is designed to allow for joins on object identifiers/RefIds and to allow retrieval of data in a row/column fashion similar to SQL. Each returned column may contain hierarchical XML elements/objects. While envisioned as the primary mechanism for SIF-based ReportManifests, Providers and Responders in a Zone may support SIF_ExtendedQuery in addition to SIF_Query. Support for SIF_ExtendedQuery can be declared in and retrieved from the Zone is various Infrastructure messages and objects.

Note that matching rows are generated solely based on the SIF_From clause, with optional join criteria, optionally limited/filtered by the SIF_Where clause. If a repeatable element is requested as a column in SIF_Select, this does not generate multiple rows for each occurrence of matching elements; all elements are returned in the corresponding column within a single row.

If no SIF_DestinationId applies to the request and this element is supplied, the Requester specifies that the extended query be routed to the Provider on record for the given object name. If this element is omitted and no SIF_DestinationId applies to the request, the ZIS routes the request to the Provider on record for the object name in SIF_From.

Identifies which data elements/attribute are to be returned as columns in each matching row.

Specifies whether query results should return all rows (false) or just distinct ones (true). Rows are distinct if at least one column differs between them.

The maximum number of rows to return. If All, return all rows, otherwise return the top rows up to the maximum row count indicated.

Indicates the element/attribute to return as a column. Contents can be left empty to return the whole object specified in ObjectName, or * can be designated to return all attributes and immediate child elements of the object specified in ObjectName, or SIF_Element Syntax can be specified, relative to the object specified in ObjectName. Requested attributes are to be returned as the text value of the corresponding attribute, elements as a copy of the XML element itself including attributes if they exist.

Optional caption for the column.

The name of the object from which to retrieve element/attributes.

Join specification for the query if more than one object is being queried. If only one object is being queried, specify it without the SIF_Join clause. This clause generates the matching rows returned, optionally limited/filtered by the SIF_Where clause. Each object referenced in the SIF_Select, SIF_Where and SIF_OrderBy clauses must be included here.

The name of the object to query.

Additional objects to query, with join conditions specifying the relationships between objects.

Type of relational join.

Specifies the conditions for the join.

Specifies the left-side element/attribute on which to constrain the join. Currently only support for keys/RefIds/RefId references is required.

Name of the object that contains the element/attribute.

Specifies right left-side element/attribute on which to constrain the join. Currently only support for keys/RefIds/RefId references is required.

Name of the object that contains the element/attribute.

Optionally specifies conditions to limit/filter rows resulting from the SIF_From clause.

Conditions that matching rows must meet.

The Boolean operator for joining conditions (SIF_Conditions elements) within this element. Note that None should be used if there is only one SIF_Conditions element.

This construct allows for nested conditions.

The boolean operator for joining conditions (SIF_Condition elements) within this element. Note that None should be used if there is only one SIF_Condition element.

This element represents an individual condition.

This is the element/attribute being queried.

The name of the object containing the element/attribute.

The comparison operator for the condition.

SIF_Value is the data that is used to compare with the value of the element or attribute.

An optional list of elements/attributes by which to sort the resulting rows.

Indicates the element/attribute by which to sort.

The name of the object containing the element/attribute.

Whether to order the element/attribute in ascending or descending order.

This element provides a wrapper for data returned in response to a SIF_ExtendedQuery. Used in SIF_Response and SIF_ReportObject.

Provides the element/attribute and caption information for each column supplied in SIF_ExtendedQuery. The order must correspond to the order of the elements as requested in SIF_ExtendedQuery.

The element/attribute specified for the column in SIF_ExtendedQuery.

The object in which the element/attribute occurs.

The caption for the column, if specified in SIF_ExtendedQuery.

Optionally allows type of column value to be explicitly communicated.

A list of matching rows resulting from the supplied SIF_ExtendedQuery. Note that the complete list of rows may span multiple SIF_Response messages, per the SIF_MaxBufferSize supplied in SIF_Request. If there are no matching rows, this is an empty list.

An individual matching row resulting from the supplied SIF_ExtendedQuery.

Contains the value of each column specified in SIF_ExtendedQuery/SIF_Select. The order of the columns must correspond to the order of the elements as requested in SIF_ExtendedQuery. Note the number of columns may be expanded from the requested columns if * is indicated one or more times in the SIF_Select clause.

This message is used as an acknowledgement to an infrastructure message.

Header information associated with this message.

The SIF_SourceId of the infrastructure message for which the SIF_Ack serves as a response.

The SIF_MsgId of the infrastructure message for which the SIF_Ack message serves as a response.

This element is used to signal a successful response.

This element is used to signal an unsuccessful response.

SIF_Event is used to deliver event objects as defined in SIF.

Header information associated with this message.

Contains the actual object (partial or whole) that is being added, changed or deleted.

This is the name of the object being added, changed or deleted.

This is the action associated with the object that is being conveyed by this SIF_Event.

The SIF_Provide message is used for advertising the provision of data objects.

Header information associated with this message.

This is the object that is being provided.

The actual name of the object that is being provided.

Whether or not the Agent supports SIF_ExtendedQuery for this object.

The contexts in which the object is being provided; if omitted, the context is SIF_Default.

Once registered, this message allows an agent to announce to the ZIS the functionality the agent will provide. The ZIS compares the functionality to its access control list and either returns a failure or a success. Upon success, the ZIS performs an atomic update of its provide/subscribe database entries for the agent to match the objects listed in this message and atomically updates other stored settings for the agent. A ZIS must not allow an agent to perform operations that it did not successfully announce. Agents should be aware that if the access control list changes after a successful SIF_Provision, some operations may still be rejected with access control errors.

Header information associated with this message.

A list of objects an Agent wishes to provide.

The name of each object.

Whether or not SIF_ExtendedQuery is supported with regard to this object.

Applicable contexts for stated object support. If omitted, the context defaults to SIF_Default.

A list of objects to which an Agent wishes to subscribe.

The name of each object.

Applicable contexts for stated object support. If omitted, the context defaults to SIF_Default.

A list of objects for which an Agent wishes to publish Add events.

The name of each object.

Applicable contexts for stated object support. If omitted, the context defaults to SIF_Default.

A list of objects for which an Agent wishes to publish Change events.

The name of each object.

Applicable contexts for stated object support. If omitted, the context defaults to SIF_Default.

A list of objects for which an Agent wishes to publish Delete events.

The name of each object.

Applicable contexts for stated object support. If omitted, the context defaults to SIF_Default.

A list of objects an Agent wishes to request.

The name of each object.

Optionally specify whether or not SIF_ExtendedQuery may be sent in requests for this object.

Applicable contexts for stated object support. If omitted, the context defaults to SIF_Default.

A list of objects for which an Agent wishes to handle requests, whether or not it is the Provider for each object. Note that this list MUST include those objects specified in SIF_ProvideObjects.

The name of each object.

Whether or not SIF_ExtendedQuery is supported with regard to this object.

Applicable contexts for stated object support. If omitted, the context defaults to SIF_Default.

SIF_Register is the message for registering an agent with a ZIS.

Header information associated with this message.

This is the descriptive name of the agent that is registering (i.e. Ramsey Media Center).

Specifies which SIF Specification version(s) the agent supports. If the ZIS cannot communicate in this format, it should reject the request.

The format of SIF_Version values can be found in Version Numbers. In a SIF_Register message, an individual SIF_Version element may also contain the following wildcards:

* - Any SIF version

<major version>.* - Any minor version plus revisions within a major version (e.g., 1.*)

<major version>.<minor version><r>* - Any revision within a minor version (e.g., 1.1r*)

Note: As wildcarding was first introduced in version 1.1 of the specification, 1.* does not match pre-compliance versions 1.0, 1.0r1 or 1.0r2. 1.1 or later agents that register with 1.* and wish to also receive messages from pre-1.1 agents must include SIF_Version element(s) with the supported pre-1.1 versions.

Specifies the maximum size of a packet to be returned by the ZIS. The ZIS may return packets smaller than, or equal to, the maximum value.

Specifies the communication mode (Pull or Push) as chosen by the message sender.

If SIF_Mode is Push, SIF_Protocol contains protocol information for contacting the agent in Push mode. A Pull-mode agent does not need to send SIF_Protocol; if received, a ZIS ignores it.

The vendor of the SIF agent.

The agent version number. The format of this field is undefined, but it should match the format used in the agent's conformance statement, if the agent is SIF Certified.

Examples
2.0.1.11

Contains information about the vendor of the product that the agent represents.

The name of the company of the product that this agent supports.

The name of the product that this agent supports.

The version of the product. This field is informative only.

HTTP URL referencing an icon for graphical representation of the application/agent. Should range from 16x16 pixels to 128x128 pixels and be of an image MIME type commonly supported by Web browsers (e.g. PNG, JPEG, GIF). Agents may optionally follow the more restrictive guidelines at [FAVICON].

SIF_Request is used to request information in SIF data objects from other SIF nodes.

Header information associated with this message.

Specifies which SIF Specification version should be used when returning the response data; wildcards are allowed. The responding agent SHOULD return data using the highest version it supports that falls within the specified versions.

Specifies the maximum size of a response packet to be returned to the requester. The responder may return packets smaller than, or equal to, the maximum value. To guarantee delivery of response packets, requesting agents must not specify a SIF_MaxBufferSize greater than its registered SIF_Register/SIF_MaxBufferSize.

Either SIF_Query or SIF_ExtendedQuery must be specified, which contain the criteria to be used to match response objects.

SIF_Response is used to respond to a SIF_Request message.

Header information associated with this message. The SIF_DestinationId needs to be the SIF_SourceId of the original SIF_Request message being processed.

This is the message ID of the SIF_Request message being processed. It provides a unique match between a SIF_Response and a previous SIF_Request. Since the ID of each message from an agent is unique, the receiver of a SIF_Response message will be able to relate the SIF_Response to a SIF_Request that it sent out previously.

This element represents the index of the SIF_Response message in the sequence of packets that make up a complete response. Its value must be in the range of 1 through n, with n equal to the total number of packets that make up a response.

The receiver of a SIF_Response message, with the help of the SIF_MorePackets and SIF_PacketNumber element in each incoming SIF_Response message, will be able to interpret and process each SIF_Response as part of a complete response to a previous SIF_Request.

This element provides an indication as to whether there are more packets besides this one to make up a complete response.

The necessity of this element stems from the requirement on an agent to break response data to fit into the SIF_MaxBufferSize provided in the SIF_Request. Agents may also break response data into multiple packets for the benefit of improving performance or for circumventing limitations of the underlying network infrastructure.

When this element's value is equal to No, it is an indication from the sender to the receiver that it has already sent out all the packets that make up a complete response for a SIF_Request as indicated by the SIF_RequestMsgId element.

The responder returns SIF_Error, SIF_ObjectData or SIF_ExtendedQueryResults.

This element allows the Responder to report an error condition that occurs while processing the SIF_Request.

If a SIF_Error element is present, the requesting agent must not expect to receive further SIF_Responses to the SIF_Request.

The SIF_ObjectData element contains the data objects matching the supplied criteria in the SIF_Request message if the SIF_Request contained SIF_Query. If the SIF_Request contained SIF_ExtendedQuery, include SIF_ExtendedQueryResults.

This element contains the elements requested by SIF_ExtendedQuery in SIF_Request.

This message is used to subscribe to event objects that are contained in this message.

Header information associated with this message.

The actual name of the object that is being subscribed to. All valid SIF_Events for this object will be routed to the subscriber.

The contexts to which the subscription applies; if omitted, the context is SIF_Default.

This message is designed to control the flow of data an agent and ZIS or vice-versa, and to synchronously retrieve data available from the ZIS.

Header information associated with this message.

This element holds the sub-message being sent.

This sub-message detects if an a Push-Mode Agent or ZIS is ready to receive and process messages.

This sub-message tells a receiver not to send any more messages to the sender.

This message tells a receiver that the sender is able to process messages.

This message tells the ZIS to return the first available message to the agent, subject to Selective Message Blocking.

This message tells the ZIS to return the current SIF_ZoneStatus in a SIF_Ack.

This message tells the ZIS to return the Agent's ACL permissions in a SIF_Ack.

This message performs the opposite function of SIF_Provide.

Header information associated with this message.

This is the object that is being removed from the provider list.

The actual name of the object that is being removed.

The contexts from which the object is being removed; if omitted, the context is SIF_Default.

This message is used to unregister an agent from a Zone.

Header information contained in the message.

This message is used to unsubscribe to SIF_Events.

Header information associated with this message.

The actual name of the object from which the agent should be unsubscribed. Events pertaining to this object published after successful unsubscription will no longer be queued for delivery to the agent. Events already queued for delivery to the agent prior to unsubscription will be delivered.

The applicable contexts; if omitted, the context is SIF_Default.

The SIF_ZoneStatus object is an object that is implicitly provided by all Zone Integration Servers to provide information about the ZIS. Zone Integration Servers MUST provide this object.

The identifier for this Zone. It is the same as the SIF_SourceId that the ZIS would place in any SIF_Header that it creates.

The descriptive name for the zone.

HTTP URL referencing an icon for graphical representation of the ZIS/Zone. Should range from 16x16 pixels to 128x128 pixels and be of an image MIME type commonly supported by Web browsers (e.g. PNG, JPEG, GIF). Agents may optionally follow the more restrictive guidelines at [FAVICON].

Contains information about the vendor that wrote this ZIS.

The name of the company that wrote the ZIS.

The product name assigned by the vendor to identify this ZIS.

The version of the vendor's product—not necessarily the SIF version.

Encompasses all the providers registered with this ZIS. This element is mandatory if there are providers registered with the ZIS.

The identifier of the SIF node that is providing objects. This is the agent or ZIS identifier that would appear in the SIF_SourceId field of any SIF_Header created by the SIF node.

The name of the object being provided by this SIF node.

Encompasses all the subscribers registered with this ZIS. This element is mandatory if there are subscribers registered with the ZIS.

The identifier of the SIF node that is subscribing to the object events. This is the agent or ZIS identifier that would appear in the SIF_SourceId field of any SIF_Header created by the SIF node.

The name of the object being subscribed to by this SIF node.

Encompasses all the Add SIF_Event publishers registered with this zone.

The identifier of the SIF node that can publish the SIF_Event. This is the agent identifier that would appear in the SIF_SourceId field of any SIF_Header created by the agent.

The name of the object being published by this agent.

Encompasses all the Change SIF_Event publishers registered with this zone.

The identifier of the SIF node that can publish the SIF_Event. This is the agent identifier that would appear in the SIF_SourceId field of any SIF_Header created by the agent.

The name of the object being published by this agent.

Encompasses all the Delete SIF_Event publishers registered with this zone.

The identifier of the SIF node that can publish the SIF_Event. This is the agent identifier that would appear in the SIF_SourceId field of any SIF_Header created by the agent.

The name of the object being published by this agent.

Encompasses all the responders registered with this zone.

The identifier of the SIF node that can respond. This is the agent identifier that would appear in the SIF_SourceId field of any SIF_Header created by the agent.

The name of the object for which the agent can respond to requests.

Encompasses all the requesters registered with this zone.

The identifier of the SIF node that can request an object. This is the agent identifier that would appear in the SIF_SourceId field of any SIF_Header created by the agent.

The name of the object being requested by this agent.

Encompasses all of the nodes registered with the ZIS. This element is mandatory if there are SIF nodes registered.

The type of the node registered with the ZIS. Note that ZIS is forward-looking and not used currently; all information about this Zone/ZIS is contained outside SIF_SIFNodes.

The descriptive name of the SIF node (i.e. Ramsey Food Services).

HTTP URL referencing an icon for graphical representation of the application/agent. Should range from 16x16 pixels to 128x128 pixels and be of an image MIME type commonly supported by Web browsers (e.g. PNG, JPEG, GIF). Agents may optionally follow the more restrictive guidelines at [FAVICON].

The vendor of the SIF agent.

The agent version number. The format of this field is undefined, but it should match the format used in the agent's conformance statement, if the agent is SIF Certified.

Examples
2.0.1.11

Contains information about the vendor of the product that the agent represents.

The name of the company of the product that this agent supports.

The name of the product that this agent supports.

The version of the product. This field is informative only.

The agent or ZIS identifier. This is the same value that the SIF node would place in any SIF_Header that it would create.

Specifies the communication mode (Pull or Push) as chosen by the message sender.

Describes the currently active protocol that the SIF node is using to communicate with the ZIS.

This is the version or versions of the SIF Specification that the SIF node uses. For agents, this information was communicated when the SIF node registered with the ZIS.

This is the level of authentication that the SIF node supports when it wants to communicate via a secure channel.

This is the level of encryption that the SIF node supports when it wants to communicate via a secure channel.

Specifies that the ZIS should never send packets larger than this value. Query responses from other providers are controlled by the SIF_MaxBufferSize attribute in the SIF_Request message.

This element shows whether the SIF node is ready to process messages.

Enumerates the various authentication protocols that the ZIS supports. If the ZIS supports an authentication protocol this element is mandatory.

Describes a particular authentication protocol supported.

Enumerates the various communication transport protocols that are supported by the ZIS.

Enumerates the versions of the SIF Implementation Specification that this ZIS can use when communicating with the agent.

Lists a specific SIF Implementation Specification version.

Should a ZIS vendor provide an administration interface for the zone via a URL, the ZIS can make the URL available in SIF_ZoneStatus. Agent administrators can use the URL to access zone administration features, should they have permission to do so.

This object provides an Agent its access control list (ACL) settings in the Zone.

Access control list by object for SIF_Provide and corresponding section in SIF_Provision.

The name of each object.

List of contexts in which rights for the given action/object apply.

Access control list by object for SIF_Subscribe and corresponding section in SIF_Provision.

The name of each object.

List of contexts in which rights for the given action/object apply.

Access control list by object for corresponding section in SIF_Provision, whether the Agent has the right to publish Add events.

The name of each object.

List of contexts in which rights for the given action/object apply.

Access control list by object for corresponding section in SIF_Provision, whether the Agent has the right to publish Change events.

The name of each object.

List of contexts in which rights for the given action/object apply.

Access control list by object for corresponding section in SIF_Provision, whether the Agent has the right to publish Delete events.

The name of each object.

List of contexts in which rights for the given action/object apply.

Access control list by object for SIF_Request and corresponding section in SIF_Provision.

The name of each object.

List of contexts in which rights for the given action/object apply.

Access control list by object for corresponding section in SIF_Provision, whether the Agent has the right to respond to requests for an object regardless of being the Provider of that object.

The name of each object.

List of contexts in which rights for the given action/object apply.