The Date Validation filter is used to compare dates from within a single message. The filter is generally used in the following situations:

  • To compare two dates from the same message.
  • To compare a date from the message against a static date; example, 01/01/2000.
  • To compare a date from the message against a predefined date; for example, TODAY.

All messages entering this filter must be of the type contained in the definition file associated with the filter and must be syntactically valid. Validation and filtering of syntactically invalid messages is done separately through the use of a validation filter and conditional connectors.

If a message is found to contain one or more dates which is not valid for the specified validation rule, a property is set with the these validation errors. This property can then be used by the HL7 Acknowledgement Generation filter to generate a negative acknowledgment. The original message is output intact from the Code Validation filter regardless of the validity or otherwise of the codes which it contains.

Configuration Properties

Property

Description

Concurrency

The maximum level of concurrency for this filter. A setting of 0 (zero) means unlimited. Limiting the level of concurrency limits memory usage.

Definition File

The definition file for input messages.

Dates To Validate

Array of the dates to compare. Click the Browse button to display the Dates to Validate screen, which enables you to enter the dates and formats for validation. Refer to Validating Dates for details.

Normalise Time Zones

Options: true, false. Default: true
Specify how time zones are applied to dates.

  • If true, the date is normalized with the time zones from the date input or from the defaults.
  • If false, the time zone information is ignored.

Offset Time Zones

Enables you to specify a time zone to be used if the supplied date does not have time zone information. This is useful if a date has no time zone or if the time zone it has is different from the server time zone.

  • The format for Offset Time Zone is the offset from UTC in the format +-hhmm.
  • If the string 'ERROR' is entered as the offset when time zone information is missing, it is treated as an error.
  • If Offset Time Zones is blank the server's current time zone is used.
    This field is only available if Normalize Time Zones is true.

Always Apply Time Zone Offset

Options: true, false. Default: false.
Enables you to specify if the Offset Time Zone is always applied even if the date has a time zone. This allows the configuration to correct a time if it is incorrect by a known amount.
This field is only available if Normalize Time Zones is true.

Fail Action

The fail action where the filter returns the message if a comparison fails. The following options are available:

  • Continue Processing - if Continue Processing is selected the filter returns to the normal connector and the property DateValidationSuccessful needs to be checked to see if all the comparisons succeed.
  • Send to Error Node - if Send to Error Node is selected the filter returns to the error connector if any comparisons fail. If there are any errors that occur during the comparison (for example, cannot parse the date) the filter is returned to the error connection irrespective of the Fail Action setting. The DateValidationInternalError and DateValidationMessageError Output Properties can be used to determine if any error occurred in this case.

Output Property

The message property to which a validation error list should be outputted to when validation errors are detected. This output is used as input for the HL7 ACK filter. A leading $ in front of this property name is ignored.

Validating Dates

The Dates to Validate screen enables you to specify the dates and formats for validation.

Property

Description

Date1

The date for the left hand side of the comparison. Refer to Dates for details about the date format that can be used.

Format1

The format of the string that is used to parse Date1. If left blank the default HL7 date format (DTTM) is used. Refer to Format Strings for details about the format string.

Comparator

The Comparator that is used to compare the dates between Date1 and Date2. The following options may be selected:

  • < (less than)
  • <= (less than or equal)
  • = (equal)
  • > (greater than)
  • >= (greater than or equal)
  • != (not equal)

Date2

The date for the right hand side of the comparison. Refer to Dates for details about the date format that can be used.

Format2

The format of the string that is used to parse Date2. If left blank the default HL7 date format (DTTM) is used. Refer to Format Strings for details about the format string.

Precision/Difference

The precision and the allowable difference that is used in the comparison. The Precision/Difference specifies two things.

  • What precision the date should be validated to; for example, check year, month, and day. The precision is set by specifying the lowest precision required to be checked (refer to Symbols for details). For example, if the precision is set to d, the year, month, and day are compared, if precision is set to h, the year, month, day, and hours are compared.
  • The allowable difference between the two dates. The difference modifier is a combination of an optional sign and the allowed integer difference. The optional sign specifies if you want to check for a positive or negative difference.

The difference is applied to Date2, effectively turning Date2 into a range.
For example, if Date2 has a time 13.10 and the difference operator is -60m Date2 becomes the range 12.10 to 13.10.

Dates

The Date fields can be used to specify 4 different types of dates.

  • Date from the message body. The string is in the standard Rhapsody format for a message path MSH.DateTimeOfMessage.Time.
  • Date from the message properties. Used to specify a field from the message properties; for example, $StartTime. Message properties are prefixed with the dollar $ character.
  • Static Date. Used to specify a static date. The date must start with a number and the format can be any format that the format string can be specified; for example, 200411011120.
  • Predefined Date. Used to specify a predefined date such as TODAY or NOW. Refer to Predefined Dates for a list of predefined Dates.

The order the string is matched is as follows:

  • If the first character is a number it is matched as a static date.
  • If the first character is a {$} it is message property.
  • If it is anything else:
    1. It is checked to see if it is a Predefined Date.
    2. It is checked to see if it is a message path.

Predefined Dates

Predefined Date

Meaning

TODAY

The current date, there is no time.

NOW

The current date and time.

START_OF_MONTH

The first day in the current month, there is no time.

END_OF_MONTH

The last day in the current month, there is no time.

START_OF_YEAR

The first day in the current year, there is no time.

END_OF_YEAR

The last day in the current year, there is no time.

If a predefined Date is used the format sting is not required and is ignored.

Predefined Date Offset

Predefined Dates can have an offset applied. This is done be adding the offset string after the predefined date. The offset string must start with a '+' or '-'. This is followed by the offset amount which is an integer amount followed by the offset type; for example hours or minutes (refer to Symbols for the offset types that can be used). Multiple offset amounts can be also be added.

For example, NOW+1h30m is the current time plus one hour 30 minutes. TODAY-14d is two weeks before the current date.

Symbols

These Symbols are used in the following places:

  • Predefined Date Offset.
  • Precision/Difference.
  • Regular expression order.

Symbol

Meaning

y

Year

M

Month

d

Day

h

Hour

m

Minute

s

Second

S

Millisecond

z

Time zone

Format Strings

The format string specifies how the date specified in the Date Field is parsed. If no format string is specified, the default HL7 date format (DTTM) is used. Format Strings can be difficult to get right so use the Predefined format if possible.

Three different formats can be used for the format string:

If a simple match string is used, the Normalize Time zone field can only be set to false if there is no time zone matching specified in the simple match string.

Match String

To specify the time format, use a date and time pattern string. This is internally parsed by a Java SimpleDateFormat. In the date and time pattern, all ASCII letters are reserved as pattern letters, which are defined as the following:

Symbol

Meaning

Example

G

era designator

AD

y

year

1996

M

month in year

July & 07

d

day in month

10

h

hour in am/pm (1~12)

12

H

hour in day (0~23)

0

m

minute in hour

30

s

second in minute

55

S

millisecond

978

E

day in week

Tuesday

D

day in year

189

F

day of week in month

2 (2nd Wed in July)

w

week in year

27

W

week in month

2

a

am/pm marker

PM

k

hour in day (1~24)

24

K

hour in am/pm (0~11)

0

z

time zone

+1200

'

escape for text

 

''

single quote

'

The following table illustrates simple match strings and how they are parsed.

Date and Time Pattern

Parsed as...

yyyy.MM.dd G 'at' HH:mm:ss

2001.07.04 AD at 12:08:56

EEE, MMM d, ''yy

Wed, Jul 4, '01

yyyyy.MMMMM.dd GGG hh:mm aaa

02001.July.04 AD 12:08 PM

EEE, d MMM yyyy HH:mm:ss

Wed, 4 Jul 2001 12:08:56

yyMMddHHmmssz

010704120856+1200

Regular Expression

If the date string is too complicated to parse with a match string, a regular expression can be used.

A regular expression is specified by the REG\ tag, followed by the order the fields are to be matched. The order is specified using field symbols (refer to Symbols for details) followed by the regular expression, separated by '\'; for example, REG\Mdy\(\d{2})/(\d{2})/(\d{4}).

  • Regular expression must be a valid gnu.regexp regular expression.
  • A two digit year is adjusted so that it is within 80 years before and 20 years after the current year.

The following table illustrates regular expression strings and how they are parsed.

Date and Time Pattern

Parsed as...

REG\dMy\
(\d{2})/(\d{2})/(\d{4})

22/12/2005

REG\y\(..)

05

REG\dMyhm\
(\d{2})(\d{2})(\d{4}) (\d{2}):(\d{2})

05102005 10:20

REG\yMdhmsSz\
(\d{4})(?:(\d{2})(?:(\d{2})(?:(\d{2})(?:(\d{2})(?:(\d{2})
(?:\.(\d{1,4})?)?)?)?)?)?)?([+-]\d{4})?

2005121012+1200 and 20051210121025+1200 notice all the groups except year are optional.

The patterns have been line wrapped for layout.

Predefined Formats

Predefined Format Common Date formats are already defined and can be used by entering the defined text. Predefined formats are standard formats the Date Validation filter knows how to parse. These should be used whenever the standard format is used.

Code

Meaning

HL7/DTTM

Formats a HL7 2.4 DTTM date.

HL7/DT

Format a HL7 2.4 DT date.

Date Comparison Calculation Examples

The comparison is calculated as follows:

  • Date1 Comparator Date2
    If there is a difference modifier the difference is applied to Date2. Date2 becomes a range.
    If it is a signed difference; for example, -20m (Difference = -20)
  • Date1 Comparator ((Date2+Difference) to Date2)
    Or +20m (Difference = +20)
  • Date1 Comparator ((Date2+Difference) to Date2)
    If it is a non-signed difference; for example, 20m (Difference = 20)
  • Date1 Comparator ((Date2 - Difference) to (Date2
    + Difference))

Date1

05/11/2004 11:28

12/08/2004 11:28

12/08/2004 11:28

12/08/200411:28

Comparator

=

=

=

=

Date2

12/08/2004 11:39

12/08/2004 11:39

12/08/2004 11:39

12/08/2004 11:39

Precision/Difference

h

m

20m

+20m

Calculation

12/08/2004 11 = 12/08/2004 11

12/08/2004 11:28 = 12/08/2004 11:39

12/08/2004 11:28 = (12/08/2004 11:19 To 12/08/2004 11:59)

12/08/2004 11:28 = (12/08/2004 11:59 To 12/08/2004 11:39)

Outcome

TRUE As the precision was hours

FALSE As precision was minutes

TRUE As 11:28 is in the range 11:19 to 11:59

FALSE As 11:28 is not in the range 11:59 to 11:39

Date1

12/08/2004 11:28

05/11/2004 11:28

05/11/2004 11:28

08/11/2004 11:28

Comparator

>

=

=

>

Date2

12/08/2004 11:39

TODAY (TODAY = 08/11/2004)

TODAY-3d (TODAY = 08/11/2004)

NOW-3h30m (NOW = 08/11/2004 13:00:54) \

Precision/Difference

-20M

d

d

m

Calculation

12/08/2004 11:28 > (12/08/2004 11:19 To 12/08/2004 11:39)

05/11/2004 = 08/11/2004

05/11/2004 = (08/11/2004 - 3 days)

08/11/2004 11:28 > 08/11/2004 13:00 - 3 hours and 30 minutes.

Outcome

TRUE As 11:28 is > 11:19 which is in the range 11:19 to 11:39

FALSE As the precision was days.

TRUE As TODAY (08/11/2004 ) - 3 days is 05/11/2004

TRUE As NOW (08/11/2004 13:00) - 3 hours and 30 minutes is 08/11/2004 09:30

Repeating Message Components

The filter handles repeated message components in the following way:

  • Both paths must return the same number of dates and will be compared on a one by one basis; for example, Date1\n\ == Date2n.
  • One path must return one date, all the repeats will be compared with the single date; for example, Date1\0\ == Date2\n\ or Date1\n\ == Date20.

If the paths have a different number of repeats an unbalanced repeats message error is reported.

Return Mode

The filter can return to the normal connector or it can return to the error connector. The filter returns to the normal connector if the validation is successful. If the validation fails the return is determined by the configuration.

If there are any errors that cause a comparison not to be preformed; for example, parsing errors, the filter always returns to the error connector.

Published Properties

Property Name

Content Description

DateValidationSuccessful

Set to true if all the date comparisons pass, or set to false if one or more comparisons fail. This property is always set.

Output Property (from configuration)

Stores the list of validation errors this filter detected. This property is used as the input for the ACK filter or the Audit com point.

DateValidationMessageError

Specifies whether this message could not complete validation because of an error in the message; for example, invalid date or unbalanced repeats.

DateValidationInternalError

Specifies whether this message could not complete validation because of an internal error in the filter; for example, message parse error, path not valid or property missing. Messages that have this type of error will have an exception attached to them.

TimeZoneWarning

Set to true if the dates in a comparison have different time zones. Set to false if no comparisons have different time zones or the timezone could not be checked. This is only checked on dates that both have regular expression Format strings and timezones inputted.