Customizing the engine and setting its defaults

Overview

This tutorial will guide you through the process of developing and deploying an initialization task branch to customize the InCert engine.

Requirements

In order to complete this tutorial, you will need the following:

• A valid code-signing certificate
• signtool.exe
• An xml or text editor

Setup

In this step, we will create a working directory and populate it with an archive folder and a signed version InCert engine executable and its support libraries.

1. Start by creating a working directory on your computer.

2. Create a sub-directory named "Archive" in your working directory.

3. Download the following files from the InCert server to your working directory:

• Engine.exe
• Engine.exe.config
• Elevator.exe
• Ninject.dll
• BouncyCastle.crypto.dll
• DataContracts.dll
• log4net.dll
• RestSharp.dll

4. using signtool.exe and your code-signing certificate, sign engine.exe:

Customizing the engine title and color-scheme

In this step, we will create an initialization task branch and assign an application title and initialize the engine's appearance.

1. From your working directory, launch engine.exe. If you signed engine.exe correctly and all of its support libraries are in-place, you should see the generic InCert splash screen followed by a "Could not retrieve status" error dialog. Don't panic! Things are working as expected at this point.

2. In your Archive folder, create an xml file named "init.xml" with this content:

<?xml version="1.0" encoding="utf-8" ?>
<Content xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://incert.incommon.org/schemas ../../Schemas/tasklist.xsd">
  <Branches>
    <RoleBranch name="initialize" role="Initialize">

    </RoleBranch>
  </Branches>
</Content>>

Two things are important here:

1. The RoleBranch tag tells the engine to accept that branch as the "Initialize" branch. When the engine gets to the point where it needs to initialize its settings, it will automatically search for and run its "Initialize" branch.

2. If you are using an xml editor that supports schemas, you can download the InCert schemas to your computer and point the "xsi:schemaLocation" attribute to these schemas. This will afford an extent of tag-completion that will help with adding and modifying your content xml.

3. Set the engine's title and institution by adding a "UserInterface.SetApplicationProperties" block to the "Initialize" role branch:

<?xml version="1.0" encoding="utf-8" ?>
<Content xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://incert.incommon.org/schemas ../../Schemas/tasklist.xsd">
  <Branches>
    <RoleBranch name="initialize" role="Initialize">
      <UserInterface.SetApplicationProperties>
        <Properties>
  	    <Title>Your Cert</Title>
  	    <Institution>Your Institution</Institution>
        </Properties>
      </UserInterface.SetApplicationProperties>
      </RoleBranch>
  </Branches>
</Content>

Of course, you can change "Your Cert" and "Your Institution" to better values. If you omit the "UserInterface.SetApplicationProperties" branch, the engine will default to "InCert" and "InCommon."

4. Add "UserInterface.SetColorValues" and "UserInterface.SetDefaultFont" blocks to your "Initialize" role branch to set the engine's colors and font:

<?xml version="1.0" encoding="utf-8" ?>
<Content xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://incert.incommon.org/schemas ../../Schemas/tasklist.xsd">
  <Branches>
    <RoleBranch name="initialize" role="Initialize">
      <UserInterface.SetApplicationProperties>
        <Properties>
          <Title>Your Cert</Title>
          <Institution>Your Institution</Institution>
        </Properties>
      </UserInterface.SetApplicationProperties>

      <UserInterface.SetColorValues>
        <Properties>
          <Setter key="BodyTextColor">White</Setter>
          <Setter key="LinkTextColor">#FFE373</Setter>
          <Setter key="TitleTextColor">White</Setter>
          <Setter key="SplashScreenBackgroundColor">#4f7fb0</Setter>
          <Setter key="DisabledTextColor">Gray</Setter>
          <Setter key="InverseTitleTextColor">White</Setter>
          <Setter key="InverseBodyTextColor">White</Setter>
          <Setter key="BorderColor">DarkGray</Setter>
          <Setter key="CheckMarkColor">DarkGreen</Setter>
          <Setter key="BackgroundColor">#4f7fb0</Setter>
          <Setter key="NavigationTextColor">White</Setter>
        </Properties>
      </UserInterface.SetColorValues>

      <UserInterface.SetDefaultFont>
        <Properties>
          <FontFamily>Verdana</FontFamily>
        </Properties>
      </UserInterface.SetDefaultFont>
    </RoleBranch>
  </Branches>
</Content>

5. Save your init.xml file and open a command prompt in your archive directory.

6. At the command prompt, type "makecab init.xml settings.cab" to compress "init.xml" into settings.cab.

If everything worked correctly, you should see "settings.cab" in your archive directory.

If you open settings.cab, it should contain init.xml.

7. Copy settings.cab from your archive folder into your working directory.

8. Using signtool.exe and your code signing certificate, sign settings.cab.

Configuring the engine to talk to your InCert server

In this step, we will configure the engine to communicate with your InCert server. Here again, we will be editing your "initialize" role branch.

1. In your working directory, run engine.exe. If you completed the last step correctly, the engine should display a customized splash screen before exiting with a "Could not retrieve status" error. Again, don't panic! Things are working as expected at this point.

2. In your archive directory, re-open init.xml and add a "WebServices.SetDefaultEndpointUrl" block your "Initialize" role branch to specify your default web-services' endpoint:

<WebServices.SetDefaultEndpointUrl>
  <Properties>
    <Value>https://certdev0.incommontest.org/cgi-bin/incommon_server.py</Value>
  </Properties>
</WebServices.SetDefaultEndpointUrl>

If you don't yet have an InCert server, you can use the above to use the InCert test server. If you are implementing your own InCert server, consult this page for a list of api-expectations.

3. You will also need to tell the engine where to find its content files and downloadables. To do this, add two "WebServices.SetEndpointUrlForFunction" blocks:

<WebServices.SetEndpointUrlForFunction>
  <Properties>
    <Function>GetContent</Function>
    <Url>https://certdev0.incommontest.org/incommon/windows/content/</Url>
  </Properties>
</WebServices.SetEndpointUrlForFunction>

<WebServices.SetEndpointUrlForFunction>
  <Properties>
    <Function>GetFileInfo</Function>
    <Url>https://certdev0.incommontest.org/incommon/windows/downloads/</Url>
  </Properties>
</WebServices.SetEndpointUrlForFunction>

Here, "GetContent" determines where the engine will download its content files from, and "GetFileInfo" determines where the engine will look for its downloadable definitions files. To see what these directories contain on the InCert test server, click here and here.

4. After you have added these three blocks, your init.xml file should be as follows:

<?xml version="1.0" encoding="utf-8" ?>
<Content xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://incert.incommon.org/schemas ../../Schemas/tasklist.xsd">
  <Branches>
    <RoleBranch name="initialize" role="Initialize">
      <UserInterface.SetApplicationProperties>
        <Properties>
          <Title>Your Cert</Title>
          <Institution>Your Institution</Institution>
        </Properties>
      </UserInterface.SetApplicationProperties>

      <UserInterface.SetColorValues>
        <Properties>
          <Setter key="BodyTextColor">White</Setter>
          <Setter key="LinkTextColor">#FFE373</Setter>
          <Setter key="TitleTextColor">White</Setter>
          <Setter key="SplashScreenBackgroundColor">#4f7fb0</Setter>
          <Setter key="DisabledTextColor">Gray</Setter>
          <Setter key="InverseTitleTextColor">White</Setter>
          <Setter key="InverseBodyTextColor">White</Setter>
          <Setter key="BorderColor">DarkGray</Setter>
          <Setter key="CheckMarkColor">DarkGreen</Setter>
          <Setter key="BackgroundColor">#4f7fb0</Setter>
          <Setter key="NavigationTextColor">White</Setter>
        </Properties>
      </UserInterface.SetColorValues>

      <UserInterface.SetDefaultFont>
        <Properties>
          <FontFamily>Verdana</FontFamily>
        </Properties>
      </UserInterface.SetDefaultFont>

      <WebServices.SetDefaultEndpointUrl>
        <Properties>
          <Value>https://certdev0.incommontest.org/cgi-bin/incommon_server.py</Value>
        </Properties>
     </WebServices.SetDefaultEndpointUrl>

     <WebServices.SetEndpointUrlForFunction>
        <Properties>
          <Function>GetContent</Function>
          <Url>https://certdev0.incommontest.org/incommon/windows/content/</Url>
        </Properties>
       </WebServices.SetEndpointUrlForFunction>

       <WebServices.SetEndpointUrlForFunction>
         <Properties>
           <Function>GetFileInfo</Function>
           <Url>https://certdev0.incommontest.org/incommon/windows/downloads/</Url>
         </Properties>
       </WebServices.SetEndpointUrlForFunction>
    </RoleBranch>
  </Branches>
</Content>

5. Save init.xml and run makecab.exe again to add it to a new settings.cab file. Copy settings.cab to your working directory and re-sign it with signtool.exe. See steps 6-8 above for more details.

6. Start engine.exe from your working directory. If you've completed the above correctly and are using the InCert test server, the engine should start and display its elevation dialog.

If you choose to elevate the engine, it should show the InCert logon dialog:

Note that the engine is using the content files on the InCert test server to configure and display the logon dialog, but it is getting its colors and title from the settings we specified in our init.xml content file. Pretty cool!

If you're using your own server and you haven't added any content yet, you will likely get an error. But don't panic! We'll cover adding remote content in the next tutorial.