Knowledge base

Understanding Xcb Xml configuration files

Purpose

Xcb retrieves its startup configuration from Xml files stored in the folder into which the application was installed. This article explains how to access manage these configuration files.

Explanation

All the user editable configuration files for the system are located in %ProgramFiles%\Xtheta\Xcb\WebApp\Config. Each of the Xml files in this folder control different aspects of the Xcb startup configuration:

  • Xcb.authentication.config - Manages authentication and access control settings for the Xcb web app.
  • Xcb.database.config - Contains database connection information for all the Xcb applications.
  • Xcb.email.config - Contains email server connection details that the system uses when sending outgoing mail.
  • Xcb.logging.config - Contains logging settings used when support needs to trace a problem in the system.
  • Xcb.services.config - Contains details about the services that the Xcb Service Manager must manage. 

General Configuration Structure

Xcb uses the standard Microsoft Xml application configuration system to manage its startup configuration. Each configuration file in Xcb contains one or more configuration sections. Each of these sections can contain additional nested configuration sections or several configuration settings. Each file has a limited range of settings that it supports.

Database Configuration File

The Xcb.database.config file contains the connection information that the software uses to access the database. This file contains two sub-sections: store and routing

store Sub-Section

The store section contains information about where the XCB data is being stored and what type of access method should be used to get to the information. For example, this section may contain settings that point XCB to multiple database servers and a folder of XML documents.


factory Setting

XCB accesses data using a series of factories that ‘construct’ a way of getting to the data. Each data source needs to be connected to its own factory. The factory setting allows you to add a new data factory to the list of factories that the application will use. The setting is made up of a name value and a type value. The name must be unique. The factory setting also contains a factory-configuration subsection that lists the factory specific configuration information necessary to connect to the data source.


Supported Factory Types

Currently, XCB only supports the NHibernateConversationFactory. This factory is designed to manufacture database connections. Future versions of XCB will most likely provide support for additional factories.

Example

The following example configures two factories.

<Xtheta.DataAccess xmlns="urn:xtheta.utility.database.configuration" ...>
<store>
<factory name="DEVELOPMENT" type="NHibernateConversationFactory">
<factory-configuration>
…
</factory-configuration>
</factory>
<factory name="PRODUCTION" type="NHibernateConversationFactory">
<factory-configuration>
…
</factory-configuration>
</factory>
</store>
</Xtheta.DataAccess>

routing Sub-Section

The routing section contains a series of routes that tell XCB how it should choose to access the databases that were listed in the store section. For example, the section may route some users to a production database server while routing all the rest to a development system.

method Setting

There are several ways in which requests for information can be routed to the correct system. The method setting allows you to add a routing method to the list of current routing methods. This setting is made up of a name value and a type value. The name must be unique. The method setting also contains a list of route sub-settings and a routing-config sub-section that tell the method how routing should be performed.


Routing methods operate in the same order they are listed in the configuration file. The system stops processing routing requests once it finds the first route sub-setting that matches.
route Sub-Setting

The route sub-setting specifies where requests should be routed for a specified route name. This setting is made up of a sourceName value and destinationFactory value. The sourceName contains the name of the source that is requesting data (this value is different depending on the routing method being used). The destinationFactory contains a comma separated list of the factories from which the data can be retrieved.

routing-config Sub-Section

The routing-config sub-section contains a list of method specific options. This section contains one or more option settings that configure how the method should operate. Each option setting has a name value and a value. The valid option names depend on the routing method being used.

Supported Method Types

Xcb supports a several routing methods. Each method routes requests using its own specialized criteria:

  • RoutingMethodDefault: Routes all requests to the route sourceName ‘Unknown.’
  • RoutingMethodNamespace: Routes requests to a sourceName that matches the module name of the module making the request.
  • RoutingMethodTypeName: Routes requests to a sourceName that matches the type making the request.
  • RoutingMethodAuthenticationTicket: Routes requests based on an authenticated user’s ticket. The routeBy option controls which portion of the user’s ticket is used to create the route sourceName. If routeBy is set to:
    • username: the route sourceName will be set to the user’s username.
    • siteAcronym: the route sourceName will be set to the user’s assigned site (or ‘null’ if the user does not have an assigned site).
    • customerCode: the route sourceName will be set to the user’s assigned site/customer combination (or ‘null:null’ if the user does not have an assigned site/customer combination).
  • RoutingMethodBatchFilerCode: Routes requests to a sourceName that matches the site acronym associated with the filer code in an ABI, ACE or AES transmission batch.

Example

The following example routes requests in the following way:

  • Requests from an authenticated user called ‘testuser’ are routed to DEVELOPMENT.
  • Requests from an ABI/ACE/AES transmission batch containing a filer code that is associated with site ‘TSI’ will be routed to DEVELOPMENT.
  • All other requests are routed to either PRODUCTION1 or PRODUCTION2
<Xtheta.DataAccess xmlns="urn:xtheta.utility.database.configuration">
<routing>
<method name="FinalStep"type="RoutingMethodDefault">
<route sourceName="Unknown"destinationFactory="PRODUCTION1,PRODUCTION2"/>
</method>
<method name="MiddleStep"type="RoutingMethodFilerCode">
<route sourceName="TSI"destinationFactory="DEVELOPMENT"/>
</method>
<method name="FirstStep"type="RoutingMethodAuthenticationTicket">
<routing-config>
<option name="routeBy"value="username"/>
</routing-config>
<route sourceName="testuser"destinationFactory="DEVELOPMENT"/>
</method>
</routing>
</Xtheta.DataAccess>



Additional information

Please be aware that changing any system configuration involves some risk.  Xtheta cannot be responsible for software failures due to incorrect or incomplete changes to the system configuration.  In addition, we do not support editing any configuration files other than the ones named above.  If you wish to be able to change some other setting, please contact our support department for guidance.

Categories

Applies to

General information

  • Last updated: 4/3/2015

Any feedback is appreciated