Skip to end of metadata
  • Created by Former user, last modified by Former user on Oct 25, 2012
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Current »

SIF Registration

The SIF Registration pane in the Global Agent Settings dialog box specifies values to use when registering the Agent with zone integration servers. This pane is divided into three tabs: Registration, Messaging Mode, and SIF Version. Some of these options can be overridden on a zone-by-zone basis while others are global and appear only in the Global Agent Settings dialog.

Registration Options

From the Registration tab you can specify the Agent ID (i.e. the SIF_SourceId to use when exchanging messages with the server) and the Maximum Buffer Size.

Figure 9. SIF Registration settings

In most cases, the Agent ID should not be changed. ZIS administrators will need to know this ID when adding the agent to the server's zones. Because no two agents can have the same ID, however, you can change this value if necessary. A change to the Agent ID does not take effect until the agent is restarted.

The Maximum Buffer Size defines the size of SIF Messages the Agent can accept, and is also used to determine the size of individual data packets returned to the agent when it queries zones in the Synchronization Wizard. It defaults to 256K, which is usually sufficient for the largest of objects but is not so great that it impacts performance on the server. You should adjust this value only if you receive errors from the ZIS that a message exceeds the Maximum Buffer Size.

Messaging Mode Options

From the Messaging Mode tab, you can choose whether the Agent uses Push or Pull mode to retrieve its messages from the server. When Pull mode is selected, you can choose the frequency at which the agent checks for new messages (by default, every minute).

Figure 10. Messaging Mode settings

Refer to Part II for an explanation of messaging modes.

SIF Version

From the SIF Version tab, you can specify which version of SIF the agent will use when registering with the server, and which versions of SIF the server supports.

Figure 11. SIF Version settings

The Default SIF Version is the value the Agent will use when registering with the zone integration server. In general it should match the version of SIF used by the student information system. This setting is global and cannot be specified on a zone-by-zone basis. If changed, the Agent must be restarted for the change to take effect.

The Zone Integration Server version lets you choose the minimum version of SIF that is supported by the server. The Agent will use this value to ensure it does not try and support more versions of the specification than are allowed by the server, which would result in errors. Unless you have a reason to support the antiquated SIF 1.0r1 specification, choose "All Versions" for maximum compatibility.
This setting can be changed on a zone-by-zone basis.

SIF Messaging

The SIF Messaging pane of the Global Agent Settings dialog box provides options to fine-tune how the Agent handles Request & Response messages and whether or not it requests SIF_ZoneStatus from the server. These options are adjusted only to help diagnose problems that may arise during the initial testing of a SIF deployment.

Figure 12. SIF Messaging settings

The Request & Response group of radio buttons determines how the Agent will respond to SIF_Request messages.

When "Return as many objects as possible per packet" is selected (the default), the Agent bundles up its SIF_Response results into individual packets equal to the size specified by the requesting agent. Depending on the packet size, tens, hundreds, or perhaps thousands of objects are returned in each packet. This is the way SIF is designed to work and results in the best performance.

The alternative, "Return one object per packet (slower)" instructs the agent to return each individual object in a single SIF_Response packet. The result is much slower performance This option can degrade performance by as much as 30x. It is not recommended for use in production environments. with the benefit that you can inspect individual objects in the zone integration server's console and/or log. It can also make identifying XML Validation errors easier because the administrator does not have to sift through large packets searching for the object that caused validation to fail.

Transports

The Transports pane of the Global Agent Settings dialog box lets you choose whether to use HTTP or secure HTTPS as the transport protocol for communicating with zone integration servers. When HTTPS is selected, you can set up the digital certificates and related options from this pane.
These options are global and cannot be changed on a zone-by-zone basis.

Figure 13. HTTP Transport settings

The combo-box at the top of the pane controls whether the Agent will establish an HTTP or HTTPS socket to listen for inbound messages from the server. This only applies to agents that use the Push messaging mode, but even when operating in Pull mode this setting must be consistent with the transport protocol used to connect to zones.  Because HTTPS connectivity is more difficult to set up and diagnose, we recommend first deploying your agent with HTTP (which is not a secure protocol). After basic SIF functionality has been verified to work as expected, migrate to the secure HTTPS protocol if desired. Some organizations choose to use HTTP within their own network and HTTPS if connecting over the public internet, while others always use HTTPS.

HTTP Options

The Port setting is the TCP/IP port the agent will establish to listen for inbound messages over HTTP when connected in Push mode. Do not confuse this port with the port on the zone integration server – it is a local port number on the computer where the agent is running. The port is rarely changed. If another application is using the default port, you can change it; otherwise leave this setting at its default value. (If you do change the port number, restart the agent for the changes to take effect.)
HTTPS Options
The HTTPS tab includes options that apply to HTTPS connections:

Figure 14. HTTPS Transport settings

Refer to Part IV. Configuration for more information about configuring HTTPS.

  • The Port setting is the TCP/IP port the agent will establish to listen for inbound messages over HTTPS when connected in Push mode. Do not confuse this port with the port on the zone integration server – it is a local port number on the computer where the Agent is running. The port is rarely changed. If another application is using the default port, you can change it; otherwise leave this setting at its default value. (If you do change the port number, restart the Agent for the changes to take effect.)
  • The Keystore setting is the path to the "keystore file", and the Keystore Password is the password to open that file. (Click the lock icon to change the password.) 
  • The Truststore setting is the path to the "truststore file", and the Truststore Password is the password to open that file. (Click the lock icon to change the password.) 
  • The Require Client Authentication checkbox determines if the Agent will require zone integration servers to authenticate themselves when sending messages to the Agent (i.e. when registered in Push mode). Authentication means the Agent trusts the server's certificate, and the server is communicating from the IP address specified in the "CN" section of its digital certificate. If either of these conditions is not met, no communication takes place. 
  • The Certificate Manager button opens the Certificate Manager dialog box, from which you can manage digital certificates.

Logging

The Logging pane of the Global Agent Settings dialog controls how much information the Agent writes to its log files and provides options for log file cleanup. In addition, if you're using SIF 1.5 or later and have a zone integration server or other application that can make use of SIF_LogEntry objects, you can enable reporting of those objects here.  Refer to Logging on page for more information about log files and server logs.  The pane is divided into four tabs: Scope, Output, Server Log, and Message Tracing.

Scope Tab

Options under the Scope Tab control how much information is written to the log files.

Figure 15. Logging > Scope settings

The checkboxes in the Scope group determine the types of log messages that are included in the log files:

  • Errors. Error messages are included in the logs.
  • Warnings. Warning messages are included in the logs.
  • Info. Informative messages are included in the logs.
  • Diagnostics. Debugging messages are included in the logs.

We recommend marking all checkboxes for the first few months of a SIF deployment. After you have experience with the agent, and day-to-day operations have been running smoothly for a while, consider fine-tuning these options to cut down on the size of log files. Of course, if you have the disk space there is no harm in logging as much information as possible---it will make things easier when problems do arise.
The SIF Message Tracking combo-box defines the amount of SIF Messaging that is included in the log files:

  • Level 0 -- None. No information about SIF Messages is included in the log files.
  • Level 1 – Minimal. As with Level 0, no information about individual SIF Messages is included in the log files. However, the receipt of certain kinds of messages, such as registration and provisioning messages, will be logged.
  • Level 2 – Moderate. Only minimal information, such as the date and time a message was received, its type and its SIF_MsgId identifier, is contributed to the log files. The content of the message is not logged.
  • Level 3 – Moderate with Pull Details. The same as Level 2, but each time the agent requests messages from the server in Pull mode, this action is logged (even if no messages were returned from the server). Note selecting this option can result in log files quickly filling up with Pull details. It should only be selected if you're having trouble getting Pull mode to work.
  • Level 4 – Detailed. The entire content of each SIF_Message received or sent to the server is echoed to the log files.
  • Level 5 – Very Detailed. Same as Level 4, but also includes details about the networking transport as well as various low-level diagnostic information.
  • Level 6 – All. All possible log information is contributed to log files.

Choosing Level 3 and below includes varying degrees of message header and context information, but does not copy the content of messages to the log files. Choosing Level 4 and above will include all SIF Message content, both received from and sent to the server. Depending on the amount of traffic at your site, this can result in very large files. Consider starting out with Level 6 and reducing it after the system has been running for a while.
Level 6 should be used when working with technical support to resolve a problem.
The checkboxes in the Low-Level Diagnostic Options group are advanced options intended to assist in diagnosing some types of problems:

  • "Log database transactions". Each time the Agent reads or writes to its database, the SQL statement is written to the log file.
  • "Log object and field mappings". Each time the Agent translates SIF Data Objects to application data and vice-versa, the result of the operation is written to the log file. Useful when verifying that the <mappings> section of the configuration file is set up properly.
  • "Log Event Reporting". Each time a SIF_Event is reported by the Agent, it also logs the specific field or fields that were reported by the application a having changed.
  • "Log Event Reporting Diagnostics". Same as above, with additional detail.

Output Tab

The options under the Output Tab control how log information is written to disk and cleaned up.

Figure 16. Logging > Output settings

Choose the Log to System Console option if you want to echo all log information to the Java console. Normally the console is not visible on the Windows platform unless you launch the agent as a standalone program using the "java --jar" command. This option is useful during debugging, when it's helpful to view log information as it occurs rather than having to open individual log files in a text viewer.  Choose the Log to Files option to write log messages to the log files.   The Roll Log Files combo-boxes lets you control when old log files are "rolled" to keep their size down. When a log file is rolled, it is archived under a new name, and the main log file is cleared.

Server Log Tab

The options under the Server Log Tab control whether SIF_LogEntry objects, available in SIF 1.5 and later, are reported to the server.

Figure 17. Logging > Server Log settings

SIF_LogEntry is a way for agents to post information to the log files on the server (whereas the other logging options discussed here apply to the agent's local logs). It is a SIF Data Object just like any other, but can only be reported to zones in the form of an Add Event. There are times when you might want to turn this feature off. If the zone integration server does not support this object, and/or there are no other agents in the zone that subscribe to it, it makes little sense to report SIF_LogEntry objects.
NOTE: Regardless of the Server Log options you choose, the agent will not attempt to send SIF_LogEntry events when connected to zones in SIF 1.1 and earlier. Instead, it will include in the local log files the information that would have been sent. This is because SIF_LogEntry is only available in SIF 1.5 and later and would result in XML Validation errors from the server if used in earlier versions.

Message Tracing Tab

The options under the Message Tracing Tab control tracking of messages related to synchronization and archiving prior traces.

Figure 18. Logging > Message Tracing settings

  • No labels