The Blackboard SIF agent is installed with Blackboard Learn. Configuring the SIF Agent to receive information from the ZIS is accomplished by activating the Agent in the service-config.properties file and editing the Agent properties in the bb-config.properties file.

Edit the service-config.properties File

  1. Open /blackboard_home/config/service-config.properties
  2. To activate the SIF Agent, uncomment the following lines:

    ############################ SIF Service ################################

    blackboard.service.name.sifservice=blackboard.platform.sif.SIFAgentService

    blackboard.service.impl.sifservice=blackboard.platform.sif.SIFAgentService

    blackboard.service.sifservice.param.config=config/bb-sif-agent-config.xml

    blackboard.service.sifservice.initlevel=17

    Uncommenting these lines of code will cause the application to attempt to communicate with a ZIS server using the parameters defined in the bb-config.properties file.

Configure SIF Agent settings in the bb-config.properties file

  1. Open /blackboard_home/config/bb-config.properties.
  2. Edit the file using the properties in the following table.
    SIF Agent Settings
    Property Description
    bbconfig.sif.pull.frequency Determines how often the SIF Agent will retrieve updates from the ZIS. This value is expressed in seconds.
    bbconfig.sif.zone Identifies the zone to which the SIF Agent subscribes.
    bbconfig.sif.host Identifies the ZIS server.
    bbconfig.sif.port The port used to listen for communication from the ZIS.
    bbconfig.sif.protocol This must be set to HTTP for an unencrypted connection or HTTPS to use SSL to encrypt communication between the ZIS and the SIF Agent.
    bbconfig.sif.keystore The keystore is a certificate used to identify the SIF agent. refers to the keystore file that our agent uses to identify itself (in the handshake process of the HTTPS protocol type connection, the ZIS will read this keystore from the agent and the agent will also read the ZIS's self-identifying keystore).
    bbconfig.sif.keystore.password Password for the keystore.
    bbconfig.sif.truststore The truststore is a certificate used to identify trusted sources. refers to the keystore file that says who our agent trusts; this keystore file is created from importing the ZIS's self-identifying certificate, so that in the handshake process our agent can match the ZIS's keystore with who we say we trust in our truststore file.
    bbconfig.sif.truststore.password Password for the truststore.
    bbconfig.sif.authlevel The SIF Authentication levels we set for bbconfig.sif.authlevel means the following to the ZIS receiving the connection message:

    0 - This agent is not sending a certificate to identify itself
    1 - This agent has a valid certificate to send to identify itself
    2 - This agent has a valid certificate to send to identify itself AND it got it from a source the ZIS trusts (trusted certificate authority)

    For level 0, the SIF Agent is not authenticating itself to the ZIS. In this instance, use the HTTP protocol to connect and do not set a keystore or a truststore. For levels 1 and 2, the HTTPS protocol must be used to connect and the keystore and truststore parameters set.

    When creating the keystore files, the ZIS must be configured to trust the agent's certificate. This is done by importing the agent's certificate into the ZIS's "Trusted Agent Certificates" section.

    If the ZIS trusts the SIF Agent certificate, the agent will successfully connect to the ZIS on level 2 authentication because the self-identifying keystore is one that the ZIS trusts. If the ZIS does not trust the agent's certificate, then connection at level 2 would fail. However, level 1 authentication level will still allow the agent to successfully connect to the ZIS if the ZIS were to not trust our agent's certificate. This is because at level 1, the agent only needs a valid certificate to identify itself-the certificate does not have to be one that the ZIS trusts.

    Example:

    #####################################################################

    #################### SIF configuration settings #####################

    #####################################################################

    bbconfig.sif.pull.frequency=30000

    bbconfig.sif.zone=Bb-SIF-Test

    bbconfig.sif.host=ZIS_SERVER.BLACKBOARD.EDU

    bbconfig.sif.port=7443

    bbconfig.sif.protocol=https

    bbconfig.sif.keystore=/blackboard_home/config/certs/SIFagent.ks

    bbconfig.sif.keystore.password=changeit

    bbconfig.sif.truststore=/blackboard_home/config/certs/Trusted.ks

    bbconfig.sif.truststore.password=changeit

    bbconfig.sif.authlevel=2

  3. Run the PushConfigUpdates command to apply the changes.

    The PushConfigUpdates command has been enhanced to improve system management. PushConfigUpdates automatically updates the admin data in the database by reading the value in the config.xml. It automatically pushes the changes of the database hostname and port, instance name, and externally visible Web server hostname to the database. To learn more, see PushConfigUpdates (in English only).

    UNIX:

    /blackboard_home/tool/admin/PushConfigUpdates.sh

    Windows:

    C:\blackboard_home\tool\admin\PushConfigUpdates

    The values in bb-config.properties are written to /blackboard_home/config/bb-sif-agent-config.xml.

  4. Check the log/blackboard_home/logs/tomcat/sif-log.txt to verify the connection.

    2009-08-12 17:29:35,833 DEBUG [ADK.Agent$Bb-SIF-Test] Polling for next message...2009-08-12 17:29:35,986 DEBUG [ADK.Agent$Bb-SIF-Test] Send SIF_SystemControl2009-08-12 17:29:35,987 DEBUG [ADK.Agent$Bb-SIF-Test]   MsgId: 7CDD8B1AA327B2F646030FDE3B72DC5F2009-08-12 17:29:35,989 DEBUG [ADK.Agent$Bb-SIF-Test] Sending message (646 bytes)2009-08-12 17:29:36,095 DEBUG [ADK.Agent$Bb-SIF-Test] Expecting reply (489 bytes)2009-08-12 17:29:36,095 DEBUG [ADK.Agent$Bb-SIF-Test] Received reply (489 chars)2009-08-12 17:29:36,100 DEBUG [ADK.Agent$Bb-SIF-Test] Receive SIF_Ack (Status = 9; Errors = 0)2009-08-12 17:29:36,100 DEBUG [ADK.Agent$Bb-SIF-Test]   MsgId: 7166CC00636B004C4A81061B23E137A72009-08-12 17:29:36,100 DEBUG [ADK.Agent$Bb-SIF-Test]   OrgId: 7CDD8B1AA227B2F646030FDE3B72DC5F2009-08-12 17:29:36,100 DEBUG [ADK.Agent$Bb-SIF-Test] No messages waiting in agent queue

Sample bb-sif-agent-config.xml file

The following example defines the sif-agent-config.xml file. Please remember not to make any changes directly to this file. Instead, edit the parameters in the bb-config.properties file and run PushConfigUpdates to make changes.

<!-- SIF Configuration File --> <agent-listing> <!--top level container. Multiple agents can be registered--!>   <agent-entry class="blackboard.platform.sif.agent.StudentPersonalProvider" version="70">
<!--declaration of agent implementation class. Full class name must be provided  Version is just meta-data--!>

    <connection class="blackboard.platform.sif.connect.SIFPullConnection" > <!--declaration of connection implementation class. SIFPullConnection and SIFPushConnection available--!>      <property name="frequency" value ="30000" /> <!-- properties are custom per connection type.  For "PULL" you specify the frequency the agent wakes up to do a pull--!>    </connection>    <zis> <!--zis represents data detailing location and means to interact with the server. --!>      <zone name="Bb-SIF-Test" /> <!--SIF Zone to be used--!>      <host name="10.10.107.77" port="7443"/> <!--ZIS server host and port to attach to. --!>      <transport protocol="https"> <!--Actual protocol to be used.  Can be either "http" or "https" if not recognized "http" will be used. --!>        <property name="keystore" value ="C:/myURL.com/testing/sif-test-app/cert/Agent.ks" />        <property name="keystorepassword" value ="mypassword" />        <property name="truststore" value ="C:/myURL.com/testing/sif-test-app/cert/Trusted.ks" />        <property name="truststorepassword" value ="changeit" />                <!--The above properties represent location of certificate stores and their corresponding passwords.  --!>        <property name="clientauth" value ="true" /> <!-- Controls whether the ZIS server should require SSL certificate exchange during an operation--!>        <property name="authlevel" value ="2" />        </transport>    </zis>  </agent-entry> </agent-listing>