Terry's ORA Tips

Transformations

This page created 29 May 2020

Version note: Applies to ORA 1.00

This article describes what I believe are the most useful Transformations offered by Online Repository Assistant (ORA). Transformations are used to modify the data ORA obtains from genealogical services to suit the user's preferences. Other articles in my ORA Section cover other topics about using the software.

Topics Included in this Article
Formatting Dates
Changing the way dates are output
Separating Parts of a Field
Separating Name and Place parts from a combined field
Counting Parts in a Field
Counting how many parts there are in a multipart name or place field
Replacing Parts of Text
Replacing or removing characters in a field
State Names and Postal Codes
Converting State names to postal codes, or the reverse
Changing the Case of Text
Uppercase, lowercase, initial caps, have it your way
Changing Numbers to Words
Spelling out numbers
Using Multiple Transformations
When more than one Transformation is required to achieve your result
Conclusions
Additional comments and links on Templates

My article on Template Basics describes how to construct Templates in ORA to manipulate the data collected and displayed in the ORA Control Panel, or typed into your genealogy program. Transformations, as their name suggests, "transform" the data collected in a variety of ways so that the data collected appears in the output in formats you may prefer.

This article describes the most useful, in my opinion, of the many available Transformations. For information about others not described here see ORA Help.

Transformations are entered inside the square brackets that enclose the name of a Variable, following the name and separated by a colon. The general format is:

[Variable:Transformation]

Some Transformations have parameters that control exactly how they work. For a Transformation with parameters the general format is:

[Variable:Transformation:parameter1:parameter2]

The following sections describe some of the available transformations in detail.

Formatting Dates

My article on ORA Basics describes how to set the format ORA will use to present data items recognized as dates. You would generally set this to the format you will use most often. Template Variables referring to fields with dates will output them in the selected format. If none of these choices suits your preferences, or if you want different formats for different purposes, Transformations are available to change the format output by a specific Template.

The date Transformation uses the term ":date" followed by one or more parameters. Each parameter is a series of code letters separated by literal text characters. The codes for the date elements are listed in the table below :

Code Output
d day, written as a one or two-digit number
dd day, written as a two-digit number, with leading zero if needed
m month, written as a one or two-digit number, e.g. 1, or 11
mm month, written as a two-digit number with leading zero if needed, e.g. 01
mmm month, written as a three-letter abbreviation in lower-case, e.g. jan
Mmm month, written as a three-letter abbreviation in mixed-case, e.g. Jan
MMM month, written as a three-letter abbreviation in upper-case, e.g. JAN
mmmm month, written out in lower case, e.g. january
Mmmm month, written out in mixed case, e.g. January
MMMM month, written as a written out in upper-case, e.g. JANUARY
yyy year, written as a three or four-digit number
yyyy year, written as four digits, with leading zero for years before 1000

The characters separating the day, month, and year codes can be most character strings. The letters d, m, and y, and characters with special meaning to ORA, like colons, angle brackets, and square brackets, must be preceded by the escape character – " \ " – as in the last example below.

Some examples of date Variables with different Transformations are listed in the following table, where the Date field contains the date 24 March 1950:

Variable and Transformation Sample Output
[Date:date:yyyy-mm-dd] 1950-03-24
[Date:date:Mmmm d, yyyy] March 24, 1950
[Date:date:d Mmm yyyy] 24 Mar 1950
[Date:date:\date\: d Mmm, yyy] date: 24 Mar, 1850

The last example illustrates that the output of the :date Transformation can include any literal text as long as an escape character is before any characters that have special meaning. In this example that applies to the " d " in "date" because it would otherwise been seen as a request to output the day, and before the colon after "date" because it would otherwise be seen as a separator for another parameter.

These examples use only a single parameter, which is applied in all conditions. When the second, optional, parameter is present, it is used when the date contains a month and year but no day. The third is used when there is a year but no month or day. When these parameters are omitted the format specifed by the preceding parameter is used in those cases, with the missing day or month output as "0."

Separating Parts of a Field

In many records names of persons or places have multiple elements in a single field, for example a place field that contains city, county, and state, separated by commas. The split Transformation can be used to output a single value from such a field.

The split Transformation uses the term ":split" followed by two parameters. The first parameter tells the Transformation which character separates the items, which are typically commas in place names, and spaces in the names of people, though others may occur. The second parameter is a number that tells the Transformation which item in the field is desired. You can count from either the beginning or end of the field. Counting from the end is indicated by putting a minus sign in front of the number.

Some examples of place Variables with different split Transformations are listed in this table, where the Place field contains "Atlanta, Fulton, Georgia, USA":

Variable and Transformation Sample Output
[Place:split:,:1] Atlanta
[Place:split:,:2] Fulton
[Place:split:,:-2] Georgia

In practice, separating parts of places, especially the town or city part, can be messy when records include ward numbers, districts, and other "place" names that may not be desired. My example Template article on Extracting City Names describes a more complex Template to address such cases.

Counting Parts in a Field

The previous section describes how to use the :split Transformation to separate parts of a field that contains multiple parts, as often is found in fields for the names of people or places. A related Transformation can count how many parts exist in such a field, which can be useful in constructing certain Templates.

Like other Transformations, it is entered in a Variable by adding the name of the Transformation – ":splitCount" – after the name of the field. It requires one parameter; the character that separates the items in the field. An example of this Transformation is this expression:

[Place:splitCount:,]

would produce these results:

Value in Field Template Output
Jackson, Shelby, Indiana 3
Shelby, Indiana 2

In practice I find this Transformation most useful when combined with a Value Test Variable, as discussed in my article in Intermediate Template Methods. An example of this application is this expression:

<[?:Place:splitCount:,=2]city of [Place]>

would produce these results:

Value in Field Template Output
Jackson, Indiana city of Jackson, Indiana
Jackson, Shelby, Indiana {nothing}

In the first case in this example, the count equals two, so the Value Test returns true and the remainder of the expression, consisting of the literal text "city of " and the name of the place, are output. In the second case, the count equals three, which the Value Test returns false, so nothing is output.

Another example of the use of this Transformation is in my Extracting City Names example Template.

Replacing Parts of Text

The fields ORA collects from the pages in a genealogical service sometimes contain characters we do not want to record in our data. For example, items in a field may be separated by underscore characters while we prefer to use a hyphen, comma, or space. Or a numeric field may contain leading zeros which we prefer to omit. The replace Transformation can replace or remove undesired characters.

The replace Transformation uses the term ":replace" followed by one required and two optional parameters. The first parameter tells the Transformation what text is to be replaced. The second tell it what characters to replace that text with. If there is no second parameter the specified text is removed and nothing is put in its place.

This table provides some examples of the use of the replace Transformation using just the first two parameters, which are sufficient in many cases:

Variable and Transformation Value of Field Sample Output
[Film:replace:_:-] T625_375 T625-375
[Occupation:replace:_:, ] farmer_blacksmith farmer, blacksmith
[Roll:replace:^0+] 0360 360

In the first two examples above the first parameter is ordinary text – the underscore character. There is a second parameter so the underscore is replaced with a hyphen in the first example and a comma followed by a space in the second.

In the third example the first parameter – " ^0+ " – is a "Regular Expression" that means "find the number zero as many times as it occurs at the beginning the text." Explaining Regular Expressions is beyond the scope of this article; if you want to know more about them I suggest you Goggle the term. Suffice it to say that the one in the example is a useful one that can be applied without understanding the details. In this example there is no second parameter, so the leading zeros are removed but not replaced.

The third parameter, which is optional, may contain "Flags" that control the operation of the replace Transformation. There are two Flags available:

If the third parameter is omitted the Transformation assumes both are to be used, as if you included both. To omit both Flags, that is to search for only the first occurrence of the target string and to match only the case of that string as entered, place a space in the third parameter. To use one of the Flags but not the other, enter the one you want to use.

State Names and Postal Codes

Genealogists generally avoid using postal codes for place names because they seem to change over time and may not be familiar to foreign readers. However they are handy to save space in applications that are not published, like file names for saved images and labels for source definitions that are used only internally by your genealogy program. Most records seem to express state and province names spelled out in full. ORA provides a handy Transformation to output those names as postal codes, and the reverse.

The abbr Transformation transforms a full state or province name to the postal code for it, and the full Transformation does the reverse. They use the term ":abbr" and ":full" respectively, and have a single parameter, the name of the lookup table to be used. Tables available as of this writing are:

Table Description
au_states Australian States and Territories
ca_provinces Canadian Provinces and Territories
place A combination of the other geographical tables
us_states US States

Some examples of place Variables using abbr and full Transformations are listed in this table:

Variable and Transformation Value of State Sample Output
[State:abbr:us_states] California CA
[State:full:us_states] CA California
[State:full:us_states] California {no output}

Note the last example – when the value in the field is not a value found in the table there is no output.

Changing the Case of Text

There are several Transformations that manipulate the case of text found in fields when you prefer it be presented differently in the output of your Template. They are:

This table provides some examples of the use of these Transformations:

Variable and Transformation Value of City Sample Output
[City:capitalize] WILKES-BARRE Wilkes-Barre
[City:initialCapital] WILKES-BARRE Wilkes-barre
[City:lowercase] Wilkes-Barre wilkes-barre
[City:uppercase] Wilkes-Barre WILKES-BARRE

Changing Numbers to Words

Sometimes a numeric value is expressed in a document, or is extracted in the genealogy service record, as a numeral but we prefer, to record it spelled out in words. The numberToWords Transformation changes numbers up to 999,999 into words. The numbers may contain commas between thousands groups and decimal points, but other punctuation formats are not supported. Numbers not supported are output unchanged. Non-numeric values result in no output

This table provides some examples of the use of these Transformations:

Variable and Transformation Value of Age Sample Output
[Age:numberToWords] 23 twenty three
[Age:numberToWords] 23.5 twenty three and 50/100
[Age:numberToWords] twenty three {no output}

Using Multiple Transformations

The above sections describe how to use Transformations to modify the data collected by ORA before pasting it into your genealogy program. But sometimes you may need to make more than one Transformation to obtain the result you want.

For example you may need to extract the name of a state from a field that also contains the names of the city and county, and then change the result to a postal code. You can do that by "chaining" Transformations together, one after the other. In this example, we show how to first extract the name of the state, then convert that to a postal code. In this example the Place field contains "Atlanta, Fulton, Georgia":

Variable and Transformation Sample Output
[Place:split:,:-1] Georgia
[Place:split:,:-1:abbr:us_states] GA

As seen here, the Transformations must be listed in the order in which they are to be applied to the data. In this case the name of the state must be extracted from the field before it can be looked up in a table to find the postal code.

If any of the Transformations other than the last has optional parameters, they must be supplied. Otherwise the name of the next Transformation will be interpreted as a parameter, which is unlikely to succeed.

Conclusions

ORA's Templates offer powerful tools to reduce the effort needed to transfer data from online genealogical services to your genealogy program. This article covers only the basics of employing these tools. For more information I suggest the following:

ReigelRidge Home Terry's Tips Home Contact Terry

 

Fewer than ten copies of my book, A Primer for The Master Genealogist, remain.
If you have been thinking of getting a copy now would be a good time.

Details are can be seen here.

 

Copyright 2000- by Terry Reigel