4 Messaging

Prepare a SIF_Message/SIF_Provision message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent ID in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply.

Include SIF_ProvideObjects and for each object your Agent would like to provide, place a SIF_Object element with an ObjectName and optionally one or more SIF_Context names (which default to SIF_Default if omitted). Your Agent can also state its support for SIF_ExtendedQuery in SIF_ExtendedQuerySupport, which defaults to false.

Include SIF_SubscribeObjects and for each object to which your Agent would like to subscribe, place a SIF_Object element with an ObjectName and optionally one or more SIF_Context names (which default to SIF_Default if omitted).

Include SIF_PublishAddObjects, SIF_PublishChangeObjects and SIF_PublishDeleteObjects elements and include a SIF_Object element with an ObjectName in the respective sections for each event type your agent publishes with regard to that oject. Optionally specify for each object one or more SIF_Context names (which default to SIF_Default if omitted).

Include SIF_RequestObjects and for each object your Agent requests, place a SIF_Object element with an ObjectName and optionally one or more SIF_Context names (which default to SIF_Default if omitted). Your Agent can also state its support for SIF_ExtendedQuery in SIF_ExtendedQuerySupport, which defaults to false.

Include SIF_RespondObjects and for each object for which your Agent processes requests (including those listed in SIF_ProvideObjects), include a SIF_Object element with an ObjectName and optionally one or more SIF_Context names (which default to SIF_Default if omitted). Your Agent can also state its support for SIF_ExtendedQuery in SIF_ExtendedQuerySupport, which defaults to false.

Prepare a SIF_Message/SIF_Event message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent ID in SIF_SourceId and the current time in SIF_Timestamp. If your Agent would like to indicate minimum encryption and/or authentication requirements for Agents receiving this SIF_Event; supply SIF_Security with the appropriate settings; use an equally secure channel when communicating with the ZIS, if desired. If this event specifically applies to one or more contexts, place them in SIF_Contexts; if omitted, the context is SIF_Default.

Specify the name of the object that is being added, changed or deleted in SIF_EventObject/@ObjectName. Place the type of event in SIF_EventObject/@Action and place the object in SIF_EventObject. For an Add event, this MUST be the complete object with all mandatory elements present. If the agent wishes to indicate that a particular optional element is supported but has no value, the element MAY be included as empty, with xsi:nil set to true if necessary.

For a Change event, all unchanged elements, whether mandatory or optional SHOULD be omitted from the object. Optional elements that have been deleted MAY be included as empty, with xsi:nil set to true if necessary. For each list of repeatable elements in the object that has changed, include the whole list if the list type indicated is List. If the list type is ActionList, the agent MAY include only those elements in the list that have been added, changed or deleted. If an element has been deleted from an ActionList, the element MUST be included with at least its key attribute(s) and/or element(s) specified, and include a SIF_Action attribute value of Delete on the deleted child element in the list. Omitting an element in an ActionList indicates that it has been unchanged in the event.

For a Delete event, only elements/attributes that identify the object sufficiently for deletion SHOULD be included. This set of identifying elements/attributes are typically communicated by the mandatory root attributes of an object, which MUST be included.

Prepare a SIF_Message/SIF_Request message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent ID in SIF_SourceId and the current time in SIF_Timestamp. If your Agent would like to indicate minimum encryption and/or authentication requirements for Agents receiving this SIF_Request, supply SIF_Security with the appropriate settings; use an equally secure channel when communicating with the ZIS, if desired. If this request is associated with a context, specify a single SIF_Context in SIF_Contexts; if omitted, the context is SIF_Default. If your Agent would like to explicitly route this request to a given Agent, specify the Agent's ID in SIF_DestinationId. Specify the SIF versions the responder may choose from when returning data in SIF_Version. Each version specified MUST be registered at the ZIS as supported by your Agent. Specify the maximum buffer size the Responder must respect when sending SIF_Response packets; this MUST be less than or equal to the SIF_MaxBufferSize with which your Agent registered with the ZIS.

If using SIF_ExtendedQuery, go to step 3; otherwise go to step 2.

If your Agent did not invoke or end SMB for a SIF_Event, the referenced message has been removed from your Agent's queue, unless your agent indicated a transport error or that it was sleeping (in which case the message has been acknowledged but remains in your Agent's queue).

If your Agent invoked SMB by sending an intermediate SIF_Ack, delivery of events is blocked until your Agent removes the SIF_Event from its queue by sending a final SIF_Ack. Your Agent will continue to receive SIF_Responses and SIF_Requests.

If your Agent ended SMB by sending a final SIF_Ack, the ZIS has removed the blocked event from your Agent's queue and resumes delivery of events to your Agent.

Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent ID in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Place 2 (intermediate SIF_Ack) in SIF_Status/SIF_Code.

If your Agent is a Push-Mode Agent, return the SIF_Ack to the ZIS and commence sending the necessary requests as described in the SIF_Request protocol above to complete processing of the event per your Agent's business rules. When complete or if an error occurs, end SMB as described in the SIF_Ack (Push-Mode) protocol above.

If your Agent is a Pull-Mode Agent, send the SIF_Ack to the ZIS per SIF_Ack (Pull-Mode) above and commence sending the necessary requests as described in the SIF_Request protocol above to complete processing of the event per your Agent's business rules. When complete or if an error occurs, end SMB as described in the SIF_Ack (Pull-Mode) protocol above.

If an error occurs, it is RECOMMENDED that your Agent publish a SIF_LogEntry Add event.

If your Agent is a Pull-Mode Agent, process the event per your Agent's business rules. When complete or if an error occurs, acknowledge the message and remove it from your Agent's queue per SIF_Ack (Pull-Mode) above.

If your Agent is a Push-Mode Agent, it has one of two options: process the event, then acknowledge it; or acknowledge the event, then process it. The advantage of first processing the event is the ability to return a descriptive error, if necessary, to the ZIS when acknowledging the message. The disadvantage of first processing is that if the processing is long running, the connection from the ZIS to your Agent may time out, which will lead to the event being redelivered to your Agent in another delivery attempt, to possibly run into another time-out. To avoid the latter, it is RECOMMENDED that your Push-Mode Agent first acknowledge the event, then process it, unless event processing is known to always occur within a reasonable amount of time. Agents that first acknowledge then process SHOULD persist the event locally until processing is complete, as the event is removed from your Agent's queue upon successful acknowledgement, otherwise the event will be lost in the case of an application or system error that affects your Agent's ability to complete processing of the event.

Choose an option and process the event according to your Agent's business rules. When acknowledging: Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent ID in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Place 1 (immediate SIF_Ack) in SIF_Status/SIF_Data in the case of successful procssing, and return the SIF_Ack to the ZIS. If an error has occurred, include a SIF_Error element with an appropriate SIF_Category and SIF_Code and describe the error as needed in SIF_Desc and optionally SIF_ExtendedDesc. Note that indicating a transport error will not remove the message from your Agent's queue, only acknowledge it. The same action can be accomplished indicating 8 (receiver is sleeping) in SIF_Status/SIF_Code.

If an error occurs regardless of the option chosen, it is RECOMMENDED that your Agent publish a SIF_LogEntry Add event.

Prepare a SIF_Response message with a copy of SIF_Contexts, SIF_DestinationId set to SIF_SourceId and SIF_RequestMsgId set to SIF_MsgId from the SIF_Request message.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate General Message Handling and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the requested context is not supported.

Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No.

Send the SIF_Response to the original requester and acknowledge the error to the ZIS.

Prepare a SIF_Response message with a copy of SIF_Contexts, SIF_DestinationId set to SIF_SourceId and SIF_RequestMsgId set to SIF_MsgId from the SIF_Request message.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Request and Response and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the requested SIF_Versions are not supported.

Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No.

Send the SIF_Response to the original requester and acknowledge the error to the ZIS.

Using the SIF version selected in Step 1, prepare a SIF_Response message with SIF_DestinationId set to SIF_SourceId and SIF_RequestMsgId set to SIF_MsgId from the SIF_Request message.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Request and Response and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the SIF_MaxBufferSize cannot be honored.

Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No.

Send the SIF_Response to the original requester and acknowledge the error to the ZIS.

Prepare a SIF_Response message using the version chosen in Step 1 with SIF_DestinationId set to SIF_SourceId and SIF_RequestMsgId set to SIF_MsgId from the SIF_Request message.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Request and Response and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the object is not supported.

Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No.

Send the SIF_Response to the original requester and acknowledge the error to the ZIS.

Prepare a SIF_Response message with SIF_DestinationId set to SIF_SourceId and SIF_RequestMsgId set to SIF_MsgId from the SIF_Request message.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Request and Response and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the query is not supported.

Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No.

Send the SIF_Response to the original requester and acknowledge the error to the ZIS.

Prepare a SIF_Response message with SIF_DestinationId set to SIF_SourceId and SIF_RequestMsgId set to SIF_MsgId from the SIF_Request message.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Request and Response and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the query is not supported.

Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No.

Send the SIF_Response to the original requester and acknowledge the error to the ZIS.

Note that Push-Mode Agents should acknowledge receipt of the SIF_Request as response generation is typically a long-running operation that will typically lead to HTTP time-outs. As the request will be removed from the Agent's queue, it is RECOMMENDED that the Push-Mode Agent persist the request and its SIF_PacketNumber while generating responses, in case of an application or system failure that prevents it from completing the request processing; upon restarting, the Agent can end the response stream with a SIF_Error, SIF_PacketNumber set to the last successfully transmitted SIF_PacketNumber + 1 and SIF_MorePackets set to No.

If a Push-Mode Agent elects to successfully acknowledge the request before processing, it can do so. Otherwise it should acknowledge receipt of the request upon completion of response generation.

Pull-Mode Agents can choose to acknowledge receipt of the request here or at the end of response generation.

Initialize packet counter to 1.

The Responder's handling of your Agent's SIF_Request has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. this is the last packet your Agent will receive associated with that request.

If your Agent is a Pull-Mode Agent, acknowledge the message per SIF_Ack (Pull-Mode) above.

If your Agent is a Push-Mode Agent: Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent ID in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Place 1 (immediate SIF_Ack) in SIF_Status/SIF_Data, and return the SIF_Ack to the ZIS.

If your Agent is a Pull-Mode Agent, process the response per your Agent's business rules. When complete or if an error occurs, acknowledge the message and remove it from your Agent's queue per SIF_Ack (Pull-Mode) above.

If your Agent is a Push-Mode Agent, it has one of two options: process the response, then acknowledge it; or acknowledge the response, then process it. The advantage of first processing the response is the ability to return a descriptive error, if necessary, to the ZIS when acknowledging the message. The disadvantage of first processing is that if the processing is long running, the connection from the ZIS to your Agent may time out, which will lead to the response being redelivered to your Agent in another delivery attempt, to possibly run into another time-out. To avoid the latter, it is RECOMMENDED that your Push-Mode Agent first acknowledge the response, then process it, unless response processing is known to always occur within a reasonable amount of time. Agents that first acknowledge then process SHOULD persist the response locally until processing is complete, as the response is removed from your Agent's queue upon successful acknowledgement, otherwise the response will be lost in the case of an application or system error that affects your Agent's ability to complete processing of the response.

Choose an option and process the response according to your Agent's business rules. When acknowledging: Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent ID in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Place 1 (immediate SIF_Ack) in SIF_Status/SIF_Data in the case of successful procssing, and return the SIF_Ack to the ZIS. If an error has occurred, include a SIF_Error element with an appropriate SIF_Category and SIF_Code and describe the error as needed in SIF_Desc and optionally SIF_ExtendedDesc. Note that indicating a transport error will not remove the message from your Agent's queue, only acknowledge it. The same action can be accomplished indicating 8 (receiver is sleeping) in SIF_Status/SIF_Code.

If an error occurs regardless of the option chosen, it is RECOMMENDED that your Agent publish a SIF_LogEntry Add event.