System of Record Specifications

Owned by ScottS
Last updated: Mar 04, 2010 by Jeremy JeremyVersion comment
3 min read

XML-based Specifications

The default sample web application looks for *.xml located in the WEB-INF/sors directory. It loads them as XML-based specification files. Production deployments using the XML-based specifications would want to relocate that directory outside of the web application, and also enable the reloading of specifications at periodic intervals (the current one doesn't have a trigger to reload).

What does the specification look like?

The specification at the moment is rather simple. This version may not survive beyond these initial releases, depending on the progression of the feature set. Here's a complete example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<specification>
   <name>fooBar</name>
   <requiredProperties>
      <property>required.property.1</property>
      <property>required.property.2</property>
      <property>required.property.3</property>
   </requiredProperties>
   <disallowedProperties>
      <property>my.bar</property>
      <property>foo.bar</property>
   </disallowedProperties>
   <allowedInterfaces>
      <interface>HUMAN</interface>
      <interface>BATCH</interface>
   </allowedInterfaces>
   <notificationSchemes>
      <entry>
         <key>HUMAN</key>
         <value>email</value>
      </entry>
      <entry>
         <key>BATCH</key>
         <value>letter</value>
      </entry>
   </notificationSchemes>
   <allowedValuesForProperties>
      <allowedValuesForProperty>
         <property>test.property</property>
         <values>
            <value>BAR</value>
            <value>FOO</value>
         </values>
      </allowedValuesForProperty>
   </allowedValuesForProperties>
   <sizesForCollectionProperties>
      <collection property="collection.1" max="20" min="5"/>
   </sizesForCollectionProperties>
</specification>

Lets Take a Closer Look

<name>fooBar</name>

Name defines the short name for SoR. This is most likely part of the path during a RESTful call, etc. Currently, we only define a short name. Future versions MAY define a longer, more descriptive name for display purposes, as well as a description.

<requiredProperties>
   <property>required.property.1</property>
   <property>required.property.2</property>
   <property>required.property.3</property>
</requiredProperties>

This defines the fields that an SoR MUST send. Its input will be rejected if they are missing. (Missing generally implies NULL in Computer Science terms). The actual "properties" or "fields" will be described later.

<disallowedProperties>
   <property>my.bar</property>
   <property>foo.bar</property>
</disallowedProperties>

This describes the fields that an SoR CANNOT send. Its input will be rejected if they are detected (i.e. non-NULL). The actual fields will be described later. If a field is not on the disallowed list, it can be sent.

<allowedInterfaces>
   <interface>HUMAN</interface>
   <interface>BATCH</interface>
</allowedInterfaces>

This describes which methods that SoR is allowed to send input on. Current values are HUMAN, BATCH, REALTIME. HUMAN generally indicates a WEB UI, BATCH indicates a FILE feed, and REALTIME indicates an API such as REST.

<notificationSchemes>
   <entry>
      <key>HUMAN</key>
      <value>email</value>
   </entry>
   <entry>
      <key>BATCH</key>
      <value>letter</value>
   </entry>
</notificationSchemes>

This section is currently not used. Its a reserved area for future use when the application may be able to send notifications on activation keys instead of merely returning them.

<allowedValuesForProperties>
   <allowedValuesForProperty>
      <property>test.property</property>
      <values>
         <value>BAR</value>
         <value>FOO</value>
      </values>
   </allowedValuesForProperty>
</allowedValuesForProperties>

This section describes the values that are allowed for the "Type" properties (i.e. address type, etc.). If the property has no values listed in this section, its assumed any value is allowed to be sent.

<sizesForCollectionProperties>
   <collection property="collection.1" max="20" min="5"/>
</sizesForCollectionProperties>

This section describes the size requirements for collections. For example, we must send at least one address per role, etc.

Properties

The following properties can either be used with required or disallowed:

  • person.sorId
  • person.dateOfBirth
  • person.gender
  • person.ssn
  • reconciliation.emailAddress
  • reconciliation.phoneNumber
  • reconciliation.addressLine1
  • reconciliation.city
  • reconciliation.region
  • reconciliation.postalCode

The following properties are the list of collections:

  • role.urls
  • role.emailAddresses
  • role.phones
  • role.addresses
  • role.leaves
  • person.names

The following properties are the ones for which you may specify types:

  • url.type
  • sponsor.sponsorType
  • role.personStatus
  • phone.addressType
  • phone.phoneType
  • name.type
  • leave.reason
  • emailAddress.addressType
  • address.type