3.2 Dynamic Free Fields, Codes and Records

This section describes the default behavior of integration points that accept dynamic field, code and record values. The configuration of the relevant dynamic field usages drive how the integration point processes a request with new dynamic field values. The driving aspects are the usage type (field, code or record), whether the field can have multiple values, whether the field vale is time valid and whether the field values have a key identifier.

Dynamic field values can be created and updated through the <dynamicField> element. The name attribute in this element identifies the field that is created or updated. If an update request does not include a <dynamicField> element for a dynamic field usage with existing values, then those existing values are not touched. In other words, the default behavior for an integration point is that an update request without a <dynamicFields> element leaves all existing dynamic field values intact.

This section describes update behavior in particular, since the initial insertion of new values is the same across all types and usage configuration.

3.2.1 Free Field Values

Like any dynamic field, free fields can be configured to have multiple values and these values can be configured to be time valid. Free field values are either dates, numbers or character strings; they never have a functional identifier. This makes the update behavior straightforward; sending in (a) value(s) for a single-value non-time-valid field, a multi-value non-time-valid field or a multi-value time-valid fields always results in a full replacement of all the existing values.

Single-value time-valid fields have slightly different behavior; sending in a new value for such a field will delete any values with a later start date, will cut off any overlapping value with an earlier start date, but will not touch any existing value that is end-dated before the start date of the new value.

The following pseudo XML reflects the structure of a single-value time-valid free field

<dynamicFields>
  <dynamicField
    name="occupation"
  >
    <value
      startDate="2010-05-01"      
      endDate="2012-09-30"    
    >Baker</value>

Suppose that, before the request is processed, the following values exist for the "occupation" field:

Occupation
Value	Start	End
Butcher	2005-01-01	2009-12-31
Courier	2010-01-01	2011-05-31
Shopkeeper	2011-06-01	n/a

The result of the update request would be:

Occupation
Value	Start	End
Butcher	2005-01-01	2009-12-31
Courier	2010-01-01	2010-04-30
Baker	2010-05-01	2012-09-30

The "Shopkeeper" value is removed because it started after the "Baker" value in the update request. The "Courier" value is cut off one day prior to the "Baker" value to make sure that there is no overlap in time. The "Butcher" value remains untouched.

For time-valid dynamic fields, the  startDate attribute in the <value> element is required; the XML schema definition does not enforce this because the same element is also used for non-time-valid fields.

The value of a dynamic free field can be a date, number or character string. Since the schema has no knowledge of the configuration of the field, the content of the <value> element is validated by the integration point logic. Date values must be sent in according to the xsd:date format, i.e., YYYY-MM-DD. The decimal character for number values must be accordance with the installation settings. If an integration point fails to parse a dynamic field value as a date, the error message GEN-PROC-001 (Value provided is not of type Date) is generated. If an integration point fails to parse a dynamic field value as a number, the error message GEN-PROC-002 (Value provided is not of type Number) is generated.

The schema definition does not except empty <value> elements. In order to sent in an update that clears all values for a particular dynamic field, the update request should include a <dynamicField> element without a <value> element, as reflected in the following pseudo code:

<dynamicFields>
  <dynamicField
    name="occupation"/>

The following is an example for the update of a single-value non-time-valid dynamic field with usage name "comment":

<dynamicFields>
  <dynamicField  
    name="comment"
  >
    <value>Need to verify spelling of surname</value>
  </dynamicField>