GeneralConfiguration

Introduction

The NCIP 2 Toolkit supports configuration via Java properties files, Spring beans, or both.

Using properties files

The default behavior is to look for properties files in the classpath. The default properties file name is toolkit.properties. Typically an ILS connector comes with a toolkit.properties file within it. You will either have to modify that file or override some of its values to configure the connector for your instance of the ILS (e.g. with the username and password for the ILS database). We recommend that you override the values in the connector's toolkit.properties file setting them in the servlet context.

Overriding properties in the servlet context -- Tomcat

In tomcat you can define a servlet Context element outside the war file, as described in the tomcat documentation here. While there are several ways to do this, the recommended approach is to create individual files (with a ".xml" extension) in the $CATALINA_BASE/conf/[enginename]/[hostname]/ directory. Any property set in the servlet context will take precedence over those in the toolkit.properties file included in the war. You can even direct the toolkit to read a different toolkit.properties file entirely.

For example, to set the URL of your Millennium system for the Millennium connector, create a $CATALINA_BASE/conf/[enginename]/[hostname]/[appname].xml file containing this:

<?xml version='1.0' encoding='utf-8'?>
<Context>

  <!-- Use this to override the connector's value for this property. -->
  <Parameter name="MillenniumConfiguration.URL" value="http://jasmine.uncc.edu" override="true"/>

</Context>

enginename defaults to Catalina; hostname defaults to localhost; appname defaults to the name of the war file, e.g. for millennium.war it would be millennium.

You can use this approach to disable a service that is supported by the connector but which you do not use. Simply override the property for that service and set its value to 'null':

<?xml version='1.0' encoding='utf-8'?>
<Context>

  <!-- Use this to disable a service that's defined in the connector's default toolkit.properties file. -->
  <Parameter name="LookupUserService.Class" value="null" override="true"/>

</Context>

Or to turn on the inclusion of stack traces in the response messages:

<?xml version='1.0' encoding='utf-8'?>
<Context>

  <!-- Turn on inclusion of stack traces in ProblemDetail of response messages when an exception occurs. -->
  <Parameter name="CoreConfiguration.IncludeStackTracesInProblemResponses" value="true" override="true"/>

</Context>

To avoid having to change the $CATALINA_BASE/conf/[enginename]/[hostname]/[appname].xml every time you want to change a property, you can set the ToolkitConfiguration.LocalPropertiesFile property to direct the Toolkit to load a second properties file containing overrides to the properties in the connector's toolkit.properties file:

<?xml version='1.0' encoding='utf-8'?>
<Context>

  <!-- Use this to override what file the Toolkit loads its properties from. -->
  <Parameter name="ToolkitConfiguration.LocalPropertiesFile" value="../localtoolkit.properties" override="true"/>

</Context>

Then create a file named localtoolkit.properties in the $CATALINA_BASE directory (or wherever else you set the property to point) and enter the property overrides there.

Finally, you can direct the Toolkit to load a different properties file than the one that comes with the connector:

<?xml version='1.0' encoding='utf-8'?>
<Context>

  <!-- Use this to replace the toolkit.properties file entirely. -->
  <Parameter name="ToolkitConfiguration.PropertiesFile" value="../replacementtoolkit.properties" override="true"/>

</Context>

Then create a file named replacementtoolkit.properties in the $CATALINA_BASE directory (or wherever else you set the property to point) and enter the property overrides there.

Overriding properties in the servlet context -- Jetty

The same principle can be applied to Jetty by customizing the override-web.xml file.

(Tested with Jetty 7.5.1 and 7.4.4 & the Symphony connector)

Place the override-web.xml file within a ../contexts/symphony.d/ folder (if using the symphony.war for example...or use dummy.d folder if using the dummy.war...)

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app 
   xmlns="http://java.sun.com/xml/ns/javaee" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" 
   version="2.5"> 


<!-- This web.xml format file is an override file that is applied to the test webapp AFTER
     it has been configured by the default descriptor and the WEB-INF/web.xml descriptor -->

  <!-- Add or override context init parameter -->
  <context-param>
    <param-name>SirsiScriptURL</param-name>
    <param-value>http://urlforyour.sirsiscripts.yourdomain.edu/sirsi/</param-value>
  </context-param>
  <context-param>
    <param-name>HOME_LIBRARY</param-name>
    <param-value>LEHIGH</param-value>
  </context-param>
  <context-param>
    <param-name>AGENCY_ID</param-name>
    <param-value>LEHI</param-value>
  </context-param>
  <context-param>
    <param-name>AUTH_BARCODE</param-name>
    <param-value>Barcode Id</param-value>
  </context-param>
  <context-param>
    <param-name>AUTH_UID</param-name>
    <param-value>Username</param-value>
  </context-param>
  <context-param>
    <param-name>PRIV_STAT_DESCRIPTION</param-name>
    <param-value>User Status</param-value>
  </context-param>
  <context-param>
    <param-name>PRIV_TYPE_STATUS</param-name>
    <param-value>STATUS</param-value>
  </context-param>
  <context-param>
    <param-name>PRIV_USER_PROFILE_DESCRIPTION</param-name>
    <param-value>User Profile</param-value>
  </context-param>
  <context-param>
    <param-name>PRIV_TYPE_PROFILE</param-name>
    <param-value>PROFILE</param-value>
  </context-param>
  <context-param>
    <param-name>PRIV_LIB_DESCRIPTION</param-name>
    <param-value>User Library</param-value>
  </context-param>
  <context-param>
    <param-name>PRIV_TYPE_LIBRARY</param-name>
    <param-value>LIBRARY</param-value>
  </context-param>
  <context-param>
    <param-name>PRIV_CAT_DESCRIPTION</param-name>
    <param-value>User Category One</param-value>
  </context-param>
  <context-param>
    <param-name>PRIV_TYPE_CAT</param-name>
    <param-value>CAT1</param-value>
  </context-param>
  <context-param>
    <param-name>daysUntilHoldExpires</param-name>
    <param-value>7</param-value>
  </context-param>

</web-app>

You will also need a symphony.xml file placed within the ../contexts/ folder. (The symphony.xml file name matches the name of the war file -- symphony.war. If you are using another connector.war -- the file name should match the name of the war file you are using) The symphony.xml file should look like this:



<?xml version="1.0"  encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">

<!-- ==================================================================
Configure and deploy the test web application in $(jetty.home)/webapps/test

Note. If this file did not exist or used a context path other that /test
then the default configuration of jetty.xml would discover the test
webapplication with a WebAppDeployer.  By specifying a context in this
directory, additional configuration may be specified and hot deployments 
detected.
===================================================================== -->

<Configure class="org.eclipse.jetty.webapp.WebAppContext">


  <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
  <!-- Required minimal context configuration :                        -->
  <!--  + contextPath                                                  -->
  <!--  + war OR resourceBase                                          -->
  <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
  <Set name="contextPath">/symphony</Set>
  <Set name="war"><SystemProperty name="jetty.home" default="."/>/webapps/symphony.war</Set>
  <Set name="overrideDescriptor"><SystemProperty name="jetty.home" default="."/>/contexts/symphony.d/override-web.xml</Set>


</Configure>

NOTE: the above technique (defining a Context) is only useable within a webapp. Thus if your Toolkit-based app is an NCIP initiator, not a responder, see GeneralConfiguration#Configuring_the_Toolkit_in_non-webapp_environments.