Refineries

What is a Refinery?

A refinery is a command that creates a record while simultaneously creating a relationship and relationship type associated with that same record. A refinery can also match on an existing record in a database, and create a relationship between that record and the source data.

A refinery takes a particular data format in given source data, and transforms it through a specific behavior as it is imported into CollectiveAccess. In other words, refineries tell CollectiveAccess how to import certain data, such as names, dates, and relationships, through a specific text command. This then determines how the data will be displayed once it is imported.

A refinery, at a simplistic level, is what it sounds like - it refines an individual data import mapping and allows for greater complexity in data representation.

Note

If a data import requires related records, then refineries must be used. For more on how to implement these in an import mapping, and why, see Relationships and Creating an Import Mapping: Overview page.

Types of Refineries

There are a few types of refineries commonly used in CollectiveAccess:

  • Splitters: A Splitter creates records, matches records with existing data, or parses apart specific data elements, literally “splitting” apart values, such as first and last names. Splitters can be applied to a variety of primary tables in CollectiveAccess. For more on Splitters, see Splitters in the Import Mapping tutorial.

  • Joiners: A Joiner is used primarily for data that includes names and dates. Joiners are used when two or more parts of a name located in different areas of the data source need to be conjoined into a single record. A dateJoiner makes a single range out of two or more dates in the data source.

  • Builders: A Builder creates an upper hierarchy above the to-be-imported data. For more, see Builders.

For a comprehensive list of refineries, see the table below.

Refinery

Parameters Used

Function

Special Notes

entitySplitter

delimiter; relationshipType; entityType; attributes; relationshipTypeDefault; entityTypeDefault; interstitial; relatedEntities; nonPreferredLabels; parents; skipIfValue; relationships; matchOn; displaynameFormat; doNotParse; dontCreate; ignoreParent

Creates an Entity Record or finds an exact match on Entity Name, and creates a relationship as defined in the import mapping. Breaks up parts of names, sets Entity type, and other parameters.

None

entityHierarchyBuilder

parents

Creates an upper hierarchy of occurrences only when the table of the import is set to ca_entities

Map the CA table.element (Column 3 in an import mapping) to ca_entities.parent_id instead of ca_entities

entityJoiner

entityType; entityTypeDefault; forename; surname; other_forenames; middlename; displayname; prefix; suffix; attributes; nonPreferred_labels; relationshipType; relationshipTypeDefault; skipifValue; relatedEntities; interstitial

Merges data from two or more source data columns to make a single entity record (when first and last Entity names are in two different columns, for example).

None

collectionSplitter

delimiter; relationshipType; collectionType; attributes; relationshipTypeDefault; collectionTypeDefault; parents; nonPreferredLabels; interstitial; skipIfValue; relationships; matchOn; ignoreParent; dontCreate

Creates a Collection Record or finds an exact match on name, and creates a flat relationshp to the imported record, with the parent parameter building an upper hierarchy above the related collection.

Builds a hierarchy when the import table is set to ca_collections

collectionHierarchyBuilder

parents; relationships

Creates an upper hierarchy of collections only when the import table is set to ca_collections

Map the CA table.element (Column 3 in an import mapping) to ca_collectionss.parent_id instead of ca_collections

placeSplitter

delimiter; relationshipType; placeType; attributes; relationshipTypeDefault; placeTypeDefault; placeHierarchy; nonPreferredLabels; interstitial; parents; relationships; matchOn; ignoreParent; dontCreate

Creates a Place Record or finds an exact match on name, and creates a relationship as defined in the import mapping

None

placeHierarchyBuilder

parents; relationships

Creates an upper hierarchy of places only when the import table is set to ca_places

Map the CA table.element (Column 3 in an import mapping) to ca_places.parent_id instead of ca_places

movementSplitter

delimiter; relationshipType; movementType; attributes; parents; relationshipTypeDefault; movementTypeDefault; nonPreferredLabels; insterstitial; relationships; matchOn; ignoreParent; dontCreate

Creates a Movement Record or finds an exact match on name, and creates a relationship

None

objectLotSplitter

delimiter; relationshipType; objectLotStatus; objectLotStatusDefault; objectLotType; attributes; relationshipTypeDefault; objectLotTypeDefault; nonPreferredLabels; interstitial; relationships; matchOn; ignoreParent; dontCreate

Creates an Object Lot Record or finds an exact match on name, and creates a relationship

None

objectSplitter

delimiter; relationshipType; objectType; attributes; parents; relationshipTypeDefault; objectTypeDefault; nonPreferredLabels; interstitial; relationships; matchOn; ignoreParent; dontCreate

Creates an Object Record or finds an exact match on name, and creates a relationship

None

objectRepresentationSplitter

objectRepresentationType; attributes; mediaPrefix; matchOn; dontCreate

Locates media by finding an exact match on filename, and generates an Object Representation for the object being imported

Splitter should be mapped to the name of the media to be imported

objectHierarchyBuilder

parents; matchOn; dontMatchOnLabel; relationships

Imports a hierarchy of List Items when the import table is set to ca_objects

Map the CA table.element (Column 3 in an import mapping) to ca_objects.parent_id instead of ca_objects

occurrenceSplitter

delimiter; relationshipType; occurrenceType; attributes; parents; relationshipTypeDefault; occurrenceTypeDefault; nonPreferredLabels; interstitial; relationships; matchOn; ignoreParent; dontCreate

Creates an Occurrence Record or finds an exact match on name, and creates a relationship

None

occurrenceHierarchyBuilder

parents; relationships

Creates an upper hierarchy fo occurrences only when the import table is set to ca_occurrences

Map the CA table.element (Column 3 in an import mapping) to ca_occurrences.parent_id instead of ca_occurrences for occurrence_Splitter

listItemSplitter

delimiter; relationshipType; listItemType; attributes; parents; list; relationshipTypeDefault; listItemTypeDefault; interstitial; relationships; matchOn; ignoreParent; dontCreate

Creates a List Item or finds an exact match on name, and creates a relationship

None

listItemHierarchyBuilder

parents; list; relationships

Imports a hierarchy of List Items when the import table is set to ca_list_items

Map the CA table.element (Column 3 in an import mapping) to ca_list_items.parent_id instead of ca_list_items for listItemSplitter

listItemIndentedHierarchyBuilder

levels; levelTypes; list; mode

Builds a hierarchical list from data sources where indents are used (in Excel) to indicate a hierarchical structure

The list can be imported without relationships to any extant or newly created records; the list can be imported in context of and as metadata for an import that maps authority records of another type (objects that carry the list items as metadata)

storageLocationSplitter

hierarchicalStorageLocationTypes; delimiter; hierarchicalDelimiter; parents; nonPreferredLabels; interstitial; relationshipType; storageLocationType; attributes; relationshipTypeDefault; storageLocationTypeDefault; relationships; matchOn; ignoreParent; dontCreate

Creates a Storage Location Record or finds an exact match on name, and creates a relationship

None

storageLocationHierarchyBuilder

parents; relationships

Creates an upper hierarchy fo occurrences only when the import table is set to ca_occurrences

Map the CA table.element (Column 3 in an import mapping) to ca_storage_locations.parent_id instead of ca_storage_locations for storageLocationSplitter

loanSplitter

loanType; relationshipType; delimiter; attributes; relationshipTypeDefault; loanTypeDefault; interstitial; parents; relationships; matchOn; ignoreParent; dontCreate

Creates a Loan Record or finds an exact match on name, and creates a relationship

The loanSplitter creates new records, and as result, full container paths must be specified in the attributes parameter (for example, ca_table.container_code.subElement_code)

measurementsSplitter

delimiter; units; elements; attributes

Formats data values that are mapped to an element of the datatype Length or Weight. Will parse dimension expressions in the form dimension1/delimiter/dimension2, and so on

Parsing includes applying default dimensions when none are specified, stripping extraneous trailing text and normalizing unit specifications. The measurementsSplitter does not create new records; it only maps data. As a result, full container paths must be specified in the attributes/elements parameter (for example, use subElement_code or measurementsWidth)

tourStopSplitter

delimiter; relationshipType; tourStopType; attributes; tour; relationshipTypeDefault; tourStopTypeDefault; nonPreferredLabels; interstitial; relationships; ignoreParent; dontCreate

Creates a Tour Stop Record or finds an exact match on name, and creates a relationship

None

tourMaker

tourType; attributes; tourTypeDefault

Creates a tour parent in a tour stop mapping

None

dateJoiner

mode; month; day; year; startDay; startMonth; startYear; endDay; endMonth; endYear; expression; start; end; skipStartIfExpression; skipStartIfExpressionReplacementValue; skipEndIfExpression; skipEndIfExpressionReplacementValue

Merges data from two or more source data columns to make a single data field in CollectiveAccess

Any text wapped with the date() function will parse as a numeric value that can be then compared as is with any other numeric quanitity. For example: “date(^start) > date(^end)” will evaluate true if the “start” date is after the end date.

dateAccuracyJoiner

accuracyField; dateFormat; accuracyValueDay; accuracyValueMonth; accuracyValueYear; dateParseFailureReturnMode; unknownAccuracyValueReturnMode

Merges a date input field with an accuracy input field, where the source data specifies granularity of a date in a separate column from the date value. For example, a date of 2014-04-01 with an accuracy of month would result in the date 2014-04 being stored in CollectiveAccess

Map the date value field into the CA attribute, then use the refinery and refinery settings to specify other parameters.

ATRelatedGetter

Refinery Parameter

Refineries can’t function properly without refinery parameters. Refinery parameters simply define the conditions for the refinery. An example is below:

entitySplitter

{“relationshipType”: “creator”, “entityType”: “ind”}

To the left (example Column 6) is the actual refinery itself, made up of CollectiveAccess-specific text that is one continuous string. On the right is the refinery parameter, written in JSON. What is this telling the source data to do?

Note

There are no spaces used in writing Refineries.

The refinery, entitySplitter, is telling CollectiveAccess that within the source data there is a name that should be parsed, or, literally “split,” or separated (first, last). Therefore, during the import CollectiveAccess will be able to identify what source data falls under this command, and execute it.

The refinery parameter is further defining the refinery by stating the type of relationship that the source data should have and the type of entity that is being imported. In this example, the names apply to a single individual (the entityType) and the relationship to the objects is the relationshipType of “creator.”

Once imported into CollectiveAccess, this refinery and its parameter that exists in the import mapping will look like:

../../../../_images/refparam1.png

Note that Refineries are optional. If source data does not require more complex elements, they are not needed in a mapping. However, Refineries are extremely useful in pre-defining these more complex elements which determine how data is inter-connected, and automatically importing data in the most straightforward, and logical, format.

For a comprehensive list of refinery parameters for each refinery, see the tables below.

Splitters

entitySplitter

Type of Refinery Parameter

Parameter Notes

Example

delimiter

Sets the value of the delimiter to break on, separating data source values

{“delimiter”: “;”}

relationshipType

Accepts a constant type code for the relationship type or a reference to the location in the data source where the type can be found

{“relationshipType”: “^10”} or {“relationshipType”: “author”}

entityType

Accepts a constant list item idno from the list entity_types or a reference to the location in the data source where the type can be found

{“entityType”: “individual”}

attributes

Sets or maps metadata for the entity record by referencing the metadataElement code and the location in the data source where the data values can be found
{
“attributes”: {
“address”: {

“address1”: “^24”, “address2”: “^25”, “city”: “^26”, “stateprovince”: “^27”, “postalcode”: “^28”, “country”: “^29”

}

}

}

attributes

To map source data to idnos in an entitySplitter, see the ‘attributes’ parameter above. An exception exists for when idnos are set to be auto-generated. To create auto-generated idnos within an entitySplitter, use the following syntax.

“attributes”: {“idno”:”%”}

relationshipTypeDefault

Sets the default relationship type that will be used if none are defined or if the data source values don’t match any values in the CollectiveAccess system

{“relationshipTypeDefault”:”creator”}

entityTypeDefault

Sets the default entity type that will be used if none are defined or if the data source values do not match any values in the CollectiveAccess list entity_types

{“entityTypeDefault”:”individual”}

interstitial

Sets or maps metadata for the interstitial movement Relationship record by referencing the metadataElement code and the location in the data source where the data values can be found.
{
“interstitial”: {

“relationshipDate”: “^4”

}

}

relatedEntities

This allows you to create and/or relate additional entities to the entity being mapped. For example, if you are running an Object mapping and using an entitySplitter to generate related Individuals, but you also want to create entity records for each individual’s affiliation, use this setting. “Name” is the name of the entity, which will be automatically split into pieces and imported. If you want to explicitly map pieces of a name (surname, forename) you can omit “name” and use “forename”, “middlename”, “surname”, etc. “type”, “attributes,” and “relationshipType” operate just as they would in a regular splitter.From version 1.5 this is now deprecated in favor of the ‘relationships’ setting.

{“relatedEntities”: [{“type”:”ind”, “name”: “^3”, “attributes”:{}, “relationshipType”:”related”}]}

nonPreferredLabels

Maps source data cells to ca_entities.nonpreferred_labels of the entity being generated or matched by the entitySplitter

“nonPreferredLabels”: [{“forename”: “^5”, “surname”:”^6”}]

parents

Builds hierarchical records above the entity being generated or matched by the entitySplitter. The parent parameter has several sub-parameters including:

idno: maps the level-specific idno

name: maps the level-specific preferred_label

type: maps the level-specific record type (must match the item idno exactly)

attributes: maps the (optional) level-specific metadata. Includes the metadataElement code and the data source.

rules: maps any (optional) level-specific rules
{
“parents”: [
{

“idno”: “^5”, “name”: “^6”, “type”: “organization”, “attributes”: {

“ca_entities.description”: “^7”

}

}

]

}

skipIfValue

Skip if imported value is in the specified list of values.

{“skipIfValue”: “unknown”}

relationships

From version 1.5. A list of relationships using the relevant splitter refineries. The settings for this item reflect the settings used for the relevant splitter refinery. The only additional setting here is relatedTable which is a required value.
{
“relationships”[
{

“relatedTable”: “ca_objects”, “type” : “moving_image”, “relationshipType”: “creator”, “preferredLabel”: “^7”, “attributes” : {

“technique” : “^10”

}

}, {

“relatedTable”: “ca_entities”, “type” : “individual”, “relationshipType”: “parent”, “preferredLabels” : [{“forename”: “^5”, “surname”:”^6”}], “attributes” : {

“gender” : “^33”

}

}

]

}

matchOn

From version 1.5. Defines exactly how the splitter will establish matches with pre-existing records. For example, you might be importing a data set in which entities are only listed by last name, but you want to make sure those entities merge with pre-existing records that include the full name. In that case, you could set “matchOn” to “surname.” Or perhaps the data set includes multiple individuals with identical names. Here you might want to match on “idno” instead. You can also list multiple fields in the matchOn parameter, and it will try multiple matches in the order specified.

{“matchOn”: [“labels”, “idno”]} -Will try to match on labels first, then idno. {“matchOn”: [“idno”, “labels”]} - Will do the opposite, first idno and then labels. You can also limit matching by doing one or the other. Eg: {“matchOn”: [“idno”]} will only match on idno. {“matchOn”: [“surname”]} will only match on surname. {“matchOn”: [“^ca_entities.your_custom_code”]} will match on a custom metadata element in the entity record. Use the syntax ^ca_entities.metadataElement code.

displaynameFormat

From version 1.5. Allows you to format the output of the displayName. Options are: “surnameCommaForename” (forces display name to be surname, forename); “forenameCommaSurname” (forces display name to be forename, surname); “forenameSurname” (forces display name to be forename surname); “original” (is the same as leaving it blank; you just get display name set to the imported text). This option also supports an arbitrary format by using the sub-element codes in a template, i.e. “^surname, ^forename ^middlename”. Doesn’t support full format templating with <unit> and <ifdef> tags, though.

{“displaynameFormat”: “surnameCommaForename”}

doNotParse

From version 1.7. This setting will force the import to migrate an organization’s name as is when using the “entity_class” = ORG setting. Otherwise parts of the name get lost in the parse.

{“doNotParse”: “1”}

dontCreate

From version 1.5. If set to true (or any non-zero value) the splitter will only do matching and will not create new records when matches are not found.

{“dontCreate”: “1”}

ignoreParent

From version 1.5. For use with entity hierarchies. When set to true this parameter allows global match across the entire hierarchy, regardless of parent_id. Use this parameter with datasets that include values to be merged into existing hierarchies but that do not include parent information. Paired with matchOn it’s possible to merge the values using only name or idno, without any need for hierarchy info. Not ideal for situations where multiple matches can not be disambiguated with the information available.

{“ignoreParent”: “1”}

collectionSplitter

Type of Refinery Parameter

Parameter Notes

Example

delimiter

Sets the value of the delimiter to break on, separating data source values

{“delimiter”: “;”}

relationshipType

Accepts a constant type code for the relationship type or a reference to the location in the data source where the type can be found. Note (for object data): if the relationship type matches that set as the hierarchy control, the object will be pulled in as a “child” element in the collection hierarchy

{“relationshipType”: “part_of”}

collectionType

Accepts a constant list item idno from the list collection_types or a reference to the location in the data source where the type can be found

{“collectionType”: “box”}

attributes

Sets or maps metadata for the collection record by referencing the metadataElement code and the location in the data source where the data values can be found
{
“attributes”: {
“collectionDateSet”: {

“collectionDate”: “^12”

}

}

}

relationshipTypeDefault

Sets the default relationship type that will be used if none are defined or if the data source values don’t match any values in the CollectiveAccess system

{“relationshipTypeDefault”:”part_of”}

collectionTypeDefault

Sets the default collection type that will be used if none are defined or if the data source values do not match any values in the CollectiveAccess list collection_types

{“collectionTypeDefault”:”series”}

parents

Maps or builds the parent levels above the record laterally related to the imported data. The parent parameter has several sub-parameters including:

idno: maps the level-specific idno

name: maps the level-specific preferred_label

type: maps the level-specific record type (must match the item idno exactly)

attributes: maps the (optional) level-specific metadata. Includes the metadataElement code and the data source.

rules: maps any (optional) level-specific rules .
{
“parents”: [
{

“idno”: “^/inm:SeriesNo”, “name”: “^/inm:SeriesTitle”, “type”: “series”, “attributes”: { “ca_collections.description”: “^7”}

}, {

“idno”: “^/inm:CollectionNo”, “name”: “^/inm:CollectionTitle”, “type”: “collection”, “rules”: [

{

“trigger”: “^/inm:Status = ‘in progress’”, “actions”: [

{

“action”: “SET”, “target”: “ca_collections.status”, “value”: “edit”

}

]

}

]

}

]

}

nonPreferredLabels

List of non-preferred labels to apply to collections.

“nonPreferredLabels”: “^4”

interstitial

Sets or maps metadata for the interstitial movement Relationship record by referencing the metadataElement code and the location in the data source where the data values can be found.
{
“interstitial”: {

“relationshipDate”: “^4”

}

}

skipIfValue

Skip if imported value is in the specified list of values.

{“skipIfValue”: “unknown”}

relationships

From version 1.5. A list of relationships using the relevant splitter refineries. The settings for this item reflect the settings used for the relevant splitter refinery. The only additional setting here is relatedTable which is a required value.
{
“relationships”[
{

“relatedTable”: “ca_entities”, “type” : “ind”, “relationshipType”: “creator”, “preferredLabel”: “^7”, “attributes” : {

“notes” : “^10”

}

}, {

“relatedTable”: “ca_entities”, “type” : “org”, “relationshipType”: “source”, “preferredLabels” : [{“forename”: “^5”, “surname”:”^6”}], “attributes” : {

“phone” : “^33”

}

}

]

}

matchOn

From version 1.5. Defines exactly how the splitter will establish matches with pre-existing records. You can set the splitter to match on idno, or labels. You can also include both labels and idno in the matchOn parameter, and it will try multiple matches in the order specified.

{“matchOn”: [“labels”, “idno”]} -Will try to match on labels first, then idno. {“matchOn”: [“idno”, “labels”]} - Will do the opposite, first idno and then labels. You can also limit matching by doing one or the other. Eg: {“matchOn”: “idno”]} will only match on idno. {“matchOn”: [“^ca_collections.your_custom_code”]} will match on a custom metadata element in the collection record. Use the syntax ^ca_collections.metadataElement code.

ignoreParent

From version 1.5. For use with collection hierarchies. When set to true this parameter allows global match across the entire hierarchy, regardless of parent_id. Use this parameter with datasets that include values to be merged into existing hierarchies but that do not include parent information. Paired with matchOn it’s possible to merge the values using only name or idno, without any need for hierarchy info. Not ideal for situations where multiple matches can not be disambiguated with the information available.

{“ignoreParent”: “1”}

dontCreate

From version 1.5. If set to true (or any non-zero value) the splitter will only do matching and will not create new records when matches are not found.

{“dontCreate”: “1”}

placeSplitter

Type of Refinery Parameter

Parameter Notes

Example

delimiter

Sets the value of the delimiter to break on, separating data source values

{“delimiter”: “;”}

relationshipType

Accepts a constant type code for the relationship type or a reference to the location in the data source where the type can be found.

{“relationshipType”: “location”}

placeType

Accepts a constant list item idno from the list place_types or a reference to the location in the data source where the type can be found

{“placeType”: “country”}

attributes

Sets or maps metadata for the place record by referencing the metadataElement code and the location in the data source where the data values can be found
{
“attributes”: {

“placeNote”: “^12”

}

}

relationshipTypeDefault

Sets the default relationship type that will be used if none are defined or if the data source values don’t match any values in the CollectiveAccess system

{“relationshipTypeDefault”:”location”}

placeTypeDefault

Sets the default place type that will be used if none are defined or if the data source values do not match any values in the CollectiveAccess list place_types

{“placeTypeDefault”:”country”}

placeHierarchy

Identifier of the place hierarchy to add places under.

{“placeHierarchy”: “dc”}

nonPreferredLabels

List of non-preferred labels to apply to places.

“nonPreferredLabels”: “^4”

interstitial

Sets or maps metadata for the interstitial movement Relationship record by referencing the metadataElement code and the location in the data source where the data values can be found.
{
“interstitial”: {

“relationshipDate”: “^4”

}

}

parents

Place parents to create, if required. The parent parameter has several sub-parameters including:

idno: maps the level-specific idno

name: maps the level-specific preferred_label

type: maps the level-specific record type (must match the item idno exactly)

attributes: maps the (optional) level-specific metadata. Includes the metadataElement code and the data source.

rules: maps any (optional) level-specific rules
{
“parents”: [
{

“idno”: “^5”, “name”: “^6”, “type”: “country”, “attributes”: {

“ca_places.description”: “^7”

}

}

]

}

relationships

From version 1.5. A list of relationships using the relevant splitter refineries. The settings for this item reflect the settings used for the relevant splitter refinery. The only additional setting here is relatedTable which is a required value.
{
“relationships”[
{

“relatedTable”: “ca_entities”, “type” : “ind”, “relationshipType”: “creator”, “preferredLabel”: “^7”, “attributes” : {

“notes” : “^10”

}

}, {

“relatedTable”: “ca_entities”, “type” : “org”, “relationshipType”: “source”, “preferredLabels” : [{“forename”: “^5”, “surname”:”^6”}], “attributes” : {

“phone” : “^33”

}

}

]

}

matchOn

From version 1.5. Defines exactly how the splitter will establish matches with pre-existing records. You can set the splitter to match on idno, or labels. You can also include both labels and idno in the matchOn parameter, and it will try multiple matches in the order specified.

{“matchOn”: [“labels”, “idno”]} -Will try to match on labels first, then idno. {“matchOn”: [“idno”, “labels”]} - Will do the opposite, first idno and then labels. You can also limit matching by doing one or the other. Eg: {“matchOn”: [“idno”]} will only match on idno. {“matchOn”: [“^ca_places.your_custom_code”]} will match on a custom metadata element in the place record. Use the syntax ^ca_places.metadataElement code.

ignoreParent

From version 1.5. For use with place hierarchies. When set to true this parameter allows global match across the entire hierarchy, regardless of parent_id. Use this parameter with datasets that include values to be merged into existing hierarchies but that do not include parent information. Paired with matchOn it’s possible to merge the values using only name or idno, without any need for hierarchy info. Not ideal for situations where multiple matches can not be disambiguated with the information available.

{“ignoreParent”: “1”}

dontCreate

From version 1.5. If set to true (or any non-zero value) the splitter will only do matching and will not create new records when matches are not found.

{“dontCreate”: “1”}

movementSplitter

Type of Parameter

Parameter Notes

Example

delimiter

Sets the value of the delimiter to break on, separating data source values

{“delimiter”: “;”}

relationshipType

Accepts a constant type code for the relationship type or a reference to the location in the data source where the type can be found.

{“relationshipType”: “related”}

movementType

Accepts a constant list item idno from the list movement_types or a reference to the location in the data source where the type can be found.

{“movementType”: “movement”}

attributes

Sets or maps metadata for the place record by referencing the metadataElement code and the location in the data source where the data values can be found
{
“attributes”: {

“movementNote”: “^12”

}

}

parents

Movement parents to create, if required.

relationshipTypeDefault

Sets the default relationship type that will be used if none are defined or if the data source values don’t match any values in the CollectiveAccess system

{“relationshipTypeDefault”:”related”}

movementTypeDefault

Sets the default movement type that will be used if none are defined or if the data source values do not match any values in the CollectiveAccess list movement_types.

{“movementTypeDefault”:”movement”}

nonPreferredLabels

List of non-preferred labels to apply to movements.

{ “nonPreferredLabels”: “^4”}

interstitial

Sets or maps metadata for the interstitial movement Relationship record by referencing the metadataElement code and the location in the data source where the data values can be found.
{
“interstitial”: {

“relationshipDate”: “^4”

}

}

relationships

From version 1.5. A list of relationships using the relevant splitter refineries. The settings for this item reflect the settings used for the relevant splitter refinery. The only additional setting here is relatedTable which is a required value.
{
“relationships”[
{

“relatedTable”: “ca_entities”, “type” : “ind”, “relationshipType”: “creator”, “preferredLabel”: “^7”, “attributes” : {

“notes” : “^10”

}

}, {

“relatedTable”: “ca_entities”, “type” : “org”, “relationshipType”: “source”, “preferredLabels” : [{“forename”: “^5”, “surname”:”^6”}], “attributes” : {

“phone” : “^33”

}

}

]

}

matchOn

From version 1.5. Defines exactly how the splitter will establish matches with pre-existing records. You can set the splitter to match on idno, or labels. You can also include both labels and idno in the matchOn parameter, and it will try multiple matches in the order specified.

{“matchOn”: [“labels”, “idno”]} -Will try to match on labels first, then idno. {“matchOn”: [“idno”, “labels”]} - Will do the opposite, first idno and then labels. You can also limit matching by doing one or the other. Eg: {“matchOn”: [“idno”]} will only match on idno. {“matchOn”: [“^ca_movements.your_custom_code”]} will match on a custom metadata element in the movement record. Use the syntax ^ca_movements.metadataElement code.

ignoreParent

From version 1.5. For use with movement hierarchies. When set to true this parameter allows global match across the entire hierarchy, regardless of parent_id. Use this parameter with datasets that include values to be merged into existing hierarchies but that do not include parent information. Paired with matchOn it’s possible to merge the values using only name or idno, without any need for hierarchy info. Not ideal for situations where multiple matches can not be disambiguated with the information available.

{“ignoreParent”: “1”}

dontCreate

From version 1.5. If set to true (or any non-zero value) the splitter will only do matching and will not create new records when matches are not found.

{“dontCreate”: “1”}

objectLotSplitter

Type of Refinery Parameter

Parameter Notes

Example

delimiter

Sets the value of the delimiter to break on, separating data source values

{“delimiter”: “;”}

relationshipType

Accepts a constant type code for the relationship type or a reference to the location in the data source where the type can be found.

{“relationshipType”: “part_of”}

objectLotStatus

Accepts a constant list item idno from the list object_lot_statuses or a reference to the location in the data source where the status can be found.

{“objectLotStatus”: “pending_accession”}

objectLotStatusDefault

Sets the default lot status that will be used if none are defined or if the data source values do not match any values in the CollectiveAccess list object_lot_statuses.

{“objectLotStatusDefault”:”accessioned”}

objectLotType

Accepts a constant list item idno from the list object_lot_types or a reference to the location in the data source where the type can be found.

{“objectLotType”: “gift”}

attributes

Sets or maps metadata for the object lot record by referencing the metadataElement code and the location in the data source where the data values can be found
{
“attributes”: {

“lotNote”: “^12”

}

}

relationshipTypeDefault

Sets the default relationship type that will be used if none are defined or if the data source values don’t match any values in the CollectiveAccess system

{“relationshipTypeDefault”:”related”}

objectLotTypeDefault

Sets the default object lot type that will be used if none are defined or if the data source values do not match any values in the CollectiveAccess list object_lot_types.

{“objectLotTypeDefault”:”gift”}

nonPreferredLabels

List of non-preferred labels to apply to object lots.

{ “nonPreferredLabels”: “^4”}

insterstitial

Sets or maps metadata for the interstitial movement Relationship record by referencing the metadataElement code and the location in the data source where the data values can be found.
{
“interstitial”: {

“relationshipDate”: “^4”

}

}

relationships

From version 1.5. A list of relationships using the relevant splitter refineries. The settings for this item reflect the settings used for the relevant splitter refinery. The only additional setting here is relatedTable which is a required value.
{
“relationships”[
{

“relatedTable”: “ca_entities”, “type” : “ind”, “relationshipType”: “creator”, “preferredLabel”: “^7”, “attributes” : {

“notes” : “^10”

}

}, {

“relatedTable”: “ca_entities”, “type” : “org”, “relationshipType”: “source”, “preferredLabels” : [{“forename”: “^5”, “surname”:”^6”}], “attributes” : {

“phone” : “^33”

}

}

]

}

matchOn

From version 1.5. Defines exactly how the splitter will establish matches with pre-existing records. You can set the splitter to match on idno, or labels. You can also include both labels and idno in the matchOn parameter, and it will try multiple matches in the order specified.

{“matchOn”: [“labels”, “idno”]} -Will try to match on labels first, then idno. {“matchOn”: [“idno”, “labels”]} - Will do the opposite, first idno and then labels. You can also limit matching by doing one or the other. Eg: {“matchOn”: [“idno”]} will only match on idno. {“matchOn”: [“^ca_object_lots.your_custom_code”]} will match on a custom metadata element in the object lot record. Use the syntax ^ca_object_lots.metadataElement code.

ignoreParent

From version 1.5. For use with object lot hierarchies. When set to true this parameter allows global match across the entire hierarchy, regardless of parent_id. Use this parameter with datasets that include values to be merged into existing hierarchies but that do not include parent information. Paired with matchOn it’s possible to merge the values using only name or idno, without any need for hierarchy info. Not ideal for situations where multiple matches can not be disambiguated with the information available.

{“ignoreParent”: “1”}

dontCreate

From version 1.5. If set to true (or any non-zero value) the splitter will only do matching and will not create new records when matches are not found.

{“dontCreate”: “1”}

objectRepresentationSplitter

Type of Refinery Parameter

Parameter Notes

Example

objectRepresentationType

Sets the object representation type to “front” or “back.”

{“objectRepresentationType”: “front”}

attributes

Sets the attributes for the object representation. “Media” sets the source of the media filename in the data, which is what will match on the actual media file in the import directory. Note: filenames in source data may or may not the include file extension, but source data must match filename exactly. Set the media filename to idno, using “idno”. Additional attributes, such as the example, “internal_notes”, can also be set here.
{ “attributes”:
{

“media”: “^1”, “internal_notes”: “^2”, “idno”: “^1”

}

}

mediaPrefix

Set the directory containing the media to be matched on here. In the following example, the import directory contains a folder named tiff/.

{“mediaPrefix”: “tiff/”}

matchOn

From version 1.5. Defines exactly how the splitter will establish matches with pre-existing records. You can set the splitter to match on idno, or labels. You can also include both labels and idno in the matchOn parameter, and it will try multiple matches in the order specified.

{“matchOn”: [“labels”, “idno”]} -Will try to match on labels first, then idno. {“matchOn”: [“idno”, “labels”]} - Will do the opposite, first idno and then labels. You can also limit matching by doing one or the other. Eg: {“matchOn”: [“idno”]} will only match on idno. {“matchOn”: [“^ca_object_representations.your_custom_code”]} will match on a custom metadata element in the representation record. Use the syntax ^ca_object_representations.metadataElement code.

dontCreate

From version 1.5. If set to true (or any non-zero value) the splitter will only do matching and will not create new records when matches are not found.

{“dontCreate”: “1”}

occurrenceSplitter

Refinery Parameter Type

Parameter Notes

Example

delimiter

Sets the value of the delimiter to break on, separating data source values

{“delimiter”: “;”}

relationshipType

Accepts a constant type code for the relationship type or a reference to the location in the data source where the type can be found.

{“relationshipType”: “related”}

occurrenceType

Accepts a constant list item idno from the list occurrence_types or a reference to the location in the data source where the type can be found.

{“occurrenceType”: “event”}

attributes

Sets or maps metadata for the occurrence record by referencing the metadataElement code and the location in the data source where the data values can be found
{
“attributes”: {

“dates”: “^10”

}

}

parents

Occurrence parents to create, if required.
{
“parents”: [
{

“idno”: “^2”, “name”: “^3”, “type”: “event”,

}, {

“idno”: “^5”, “name”: “^6”, “type”: “series”,

}

]

}

relationshipTypeDefault

Sets the default relationship type that will be used if none are defined or if the data source values don’t match any values in the CollectiveAccess system

{“relationshipTypeDefault”:”related”}

occurrenceTypeDefault

Sets the default occurrence type that will be used if none are defined or if the data source values do not match any values in the CollectiveAccess list occurrence_types.

{“occurrenceTypeDefault”:”event”}

nonPreferredLabels

List of non-preferred labels to apply to objects.

{ “nonPreferredLabels”: “^4”}

interstitial

Sets or maps metadata for the interstitial movement Relationship record by referencing the metadataElement code and the location in the data source where the data values can be found.
{
“interstitial”: {

“relationshipDate”: “^4”

}

}

relationships

From version 1.5. A list of relationships using the relevant splitter refineries. The settings for this item reflect the settings used for the relevant splitter refinery. The only additional setting here is relatedTable which is a required value.
{
“relationships”[
{

“relatedTable”: “ca_entities”, “type” : “ind”, “relationshipType”: “creator”, “preferredLabel”: “^7”, “attributes” : {

“notes” : “^10”

}

}, {

“relatedTable”: “ca_entities”, “type” : “org”, “relationshipType”: “source”, “preferredLabels” : [{“forename”: “^5”, “surname”:”^6”}], “attributes” : {

“phone” : “^33”

}

}

]

}

matchOn

From version 1.5. Defines exactly how the splitter will establish matches with pre-existing records. You can set the splitter to match on idno, or labels. You can also include both labels and idno in the matchOn parameter, and it will try multiple matches in the order specified.

{“matchOn”: [“labels”, “idno”]} -Will try to match on labels first, then idno. {“matchOn”: [“idno”, “labels”]} - Will do the opposite, first idno and then labels. You can also limit matching by doing one or the other. Eg: {“matchOn”: [“idno”]} will only match on idno. {“matchOn”: [“^ca_occurrences.your_custom_code”]} will match on a custom metadata element in the occurrence record. Use the syntax ^ca_occurrences.metadataElement code.

ignoreParent

From version 1.5. For use with occurrence hierarchies. When set to true this parameter allows global match across the entire hierarchy, regardless of parent_id. Use this parameter with datasets that include values to be merged into existing hierarchies but that do not include parent information. Paired with matchOn it’s possible to merge the values using only name or idno, without any need for hierarchy info. Not ideal for situations where multiple matches can not be disambiguated with the information available.

{“ignoreParent”: “1”}

dontCreate

From version 1.5. If set to true (or any non-zero value) the splitter will only do matching and will not create new records when matches are not found.

{“dontCreate”: “1”}

listItemSplitter

Type of Refinery Parameter

Parameter Notes

Example

delimiter

Sets the value of the delimiter to break on, separating data source values

{“delimiter”: “;”}

relationshipType

Accepts a constant type code for the relationship type or a reference to the location in the data source where the type can be found.

{“relationshipType”: “location”}

listItemType

Accepts a constant list item idno from the list or a reference to the location in the data source where the type can be found.

{“listItemType”: “concept”}

attributes

Sets or maps metadata for the list value by referencing the metadataElement code and the location in the data source where the data values can be found. You usually don’t set attributes for a list item, but you can here if you need to.
{
“attributes”: {

“listItemNote”: “^12”

}

}

parents

Maps or builds the parent levels above the record laterally related to the imported data. The parent parameter has several sub-parameters including:

idno: maps the level-specific idno

name: maps the level-specific preferred_label

type: maps the level-specific record type (must match the item idno exactly)

attributes: maps the (optional) level-specific metadata. Includes the metadataElement code and the data source.

rules: maps any (optional) level-specific rules .
{
“parents”: [
{

“idno”: “^12”, “name”: “^14”, “type”: “concept”, “attributes”: { “ca_list_items.description”: “^7”}

}, {

“idno”: “^16”, “name”: “^17”, “type”: “guide”, “rules”: [

{

“trigger”: “^3= ‘in progress’”, “actions”: [

{

“action”: “SET”, “target”: “ca_list_items.status”, “value”: “edit”

}

]

}

]

}

]

}

list

Enter the list_code for the list that the item should be added to. This is mandatory - if you forget to set it or set it to a list_code that doesn’t exist the mapping will fail.)

{“list”: “list_code”}

relationshipTypeDefault

Sets the default relationship type that will be used if none are defined or if the data source values don’t match any values in the CollectiveAccess system

{“relationshipTypeDefault”:”concept”}

listItemTypeDefault

Sets the default list item type that will be used if none are defined or if the data source values do not match any values in the CollectiveAccess list list_item_types

{“listItemTypeDefault”:”concept”}

interstitial

Sets or maps metadata for the interstitial vocabulary Relationship record record by referencing the metadataElement code and the location in the data source where the data values can be found.
{“interstitial”: {

“description”: “^4”

}

}

relationships

From version 1.5. A list of relationships using the relevant splitter refineries. The settings for this item reflect the settings used for the relevant splitter refinery. The only additional setting here is relatedTable which is a required value.

{ “relationships” : [

{

“relatedTable”: “ca_entities”, “type” : “ind”, “relationshipType”: “creator”, “preferredLabel”: “^7”, “attributes” : {

“notes” : “^10”

}

}, {

“relatedTable”: “ca_entities”, “type” : “org”, “relationshipType”: “source”, “preferredLabels” : [{“forename”: “^5”, “surname”:”^6”}], “attributes” : {

“phone” : “^33”

}

}

]

}

matchOn

From version 1.5. Defines exactly how the splitter will establish matches with pre-existing records. You can set the splitter to match on idno, or labels. You can also include both labels and idno in the matchOn parameter, and it will try multiple matches in the order specified.

{“matchOn”: [“labels”, “idno”]} -Will try to match on labels first, then idno. {“matchOn”: [“idno”, “labels”]} - Will do the opposite, first idno and then labels. You can also limit matching by doing one or the other. Eg: {“matchOn”: [“idno”]} will only match on idno. {“matchOn”: [“^ca_list_items.your_custom_code”]} will match on a custom metadata element in the list item record. Use the syntax ^ca_list_items.metadataElement code.

ignoreParent

From version 1.5. For use with list item hierarchies. When set to true this parameter allows global match across the entire hierarchy, regardless of parent_id. Use this parameter with datasets that include values to be merged into existing hierarchies but that do not include parent information. Paired with matchOn it’s possible to merge the values using only name or idno, without any need for hierarchy info. Not ideal for situations where multiple matches can not be disambiguated with the information available.

{“ignoreParent”: “1”}

dontCreate

From version 1.5. If set to true (or any non-zero value) the splitter will only do matching and will not create new records when matches are not found.

{“dontCreate”: “1”}

storageLocationSplitter

Type of Refinery Parameter

Parameter Notes

Example

hierarchicalStorageLocationTypes

Sets the storage location types used to label each level in a numerically expressed hierarchy
{
“hierarchicalStorageLocationTypes”: [

“room”, “rack”, “cabinet”

]

}

delimiter

Sets the value of the delimiter to break on, separating data source values

{“delimiter”:”;”}

hierarchicalDelimiter

Specifies the delimiter to on which to break when designating hierarchicalStorageLocationTypes

{“hierarchicalDelimiter”:”.”}

parents

Maps or builds the parent levels above the record laterally related to the imported data. The parent parameter has several sub-parameters including:

idno: maps the level-specific idno

name: maps the level-specific preferred_label

type: maps the level-specific record type (must match the item idno exactly)

attributes: maps the (optional) level-specific metadata. Includes the metadataElement code and the data source.

rules: maps any (optional) level-specific rules .
{
“parents”: [
{

“idno”: “^10”, “name”: “^12”, “type”: “cabinet”, “attributes”: { “ca_storage_location.description”: “^7”}

}, {

“idno”: “^14”, “name”: “^16”, “type”: “room”, “rules”: [

{

“trigger”: “^18= ‘in progress’”, “actions”: [

{

“action”: “SET”, “target”: “ca_storage_locations.status”, “value”: “edit”

}

]

}

]

}

]

}

nonPreferredLabels

List of non-preferred labels to apply to tour stops.

{“nonPreferredLabels”:”^5”}

interstitial

Sets metadata for the Relationship record (between the target of the mapping and the related entity via the splitter)
{
“interstitial”: {

“relationshipDate”: “^4”

}

}

relationshipType

Accepts a constant type code for the relationship type or a reference to the location in the data source where the type can be found.

{“relationshipType”:”home”}

storageLocationType

Accepts a constant list item idno from the list storage_location_types or a reference to the location in the data source where the type can be found.

{“storageLocationType”:”room”}

attributes

Sets or maps metadata for the storage location record by referencing the metadataElement code and the location in the data source where the data values can be found.

{“attributes”:{“storage_description”:”^7”, “storage_dates”:”8”}}

relationshipTypeDefault

Sets the default relationship type that will be used if none are defined or if the data source values do not match any values in the CollectiveAccess system

{“relationshipTypeDefault”:”located”}

storageLocationTypeDefault

Sets the default storage location type that will be used if none are defined or if the data source values do not match any values in the CollectiveAccess list storage_location_types {“storageLocationTypeDefault”:”permanent”} storageLocationSplitter relationships

{“storageLocationTypeDefault”:”permanent”}

relationships

From version 1.5. A list of relationships using the relevant splitter refineries. The settings for this item reflect the settings used for the relevant splitter refinery. The only additional setting here is relatedTable which is a required value.
{
“relationships”[
{

“relatedTable”: “ca_entities”, “type” : “ind”, “relationshipType”: “creator”, “preferredLabel”: “^7”, “attributes” : {

“notes” : “^10”

}

}, {

“relatedTable”: “ca_entities”, “type” : “org”, “relationshipType”: “source”, “preferredLabels” : [{“forename”: “^5”, “surname”:”^6”}], “attributes” : {

“phone” : “^33”

}

}

]

}

matchOn

From version 1.5. Defines exactly how the splitter will establish matches with pre-existing records. You can set the splitter to match on idno, or labels. You can also include both labels and idno in the matchOn parameter, and it will try multiple matches in the order specified.

{“matchOn”: [“labels”, “idno”]} -Will try to match on labels first, then idno. {“matchOn”: [“idno”, “labels”]} - Will do the opposite, first idno and then labels. You can also limit matching by doing one or the other. Eg: {“matchOn”: [“idno”]} will only match on idno. {“matchOn”: [“^ca_storage_locations.your_custom_code”]} will match on a custom metadata element in the location record. Use the syntax ^ca_storage_locations.metadataElement code.

ignoreParent

From version 1.5. When set to true this parameter allows global match across the entire hierarchy, regardless of parent_id. Use this parameter with datasets that include values to be merged into existing hierarchies but that do not include parent information. Paired with matchOn it’s possible to merge the values using only name or idno, without any need for hierarchy info. Not ideal for situations where multiple matches can not be disambiguated with the information available.

{“ignoreParent”: “1”}

dontCreate

From version 1.5. If set to true (or any non-zero value) the splitter will only do matching and will not create new records when matches are not found.

{“dontCreate”: “1”}

loanSplitter

Type of Refinery Parameter

Parameter Notes

Example

loanType

Accepts a constant list item from the list loan_types

{“loanType”:”out”}

relationshipType

Accepts a constant type code for the relationship type or a reference to the location in the data source where the type can be found. Note for object data: if the relationship type matches that which is set as the hierarchy control, the object will be pulled in as a “child” element in the loan hierarchy

{“relationshipType”:”part_of”}

delimiter

Sets the value of the delimiter to break on, separating data source values

{“delimiter”:”.”}

attributes

Sets or maps metadata for the loan record by referencing the metadataElement code and the location in the data source where the data values can be found.
{
“attributes”: {

“loanDate”: “^11”

}

}

relationshipTypeDefault

Sets the default relationship type that will be used if none are defined or if the data source values do not match any values in the CollectiveAccess system

{“relationshipTypeDefault”:”part_of”}

loanTypeDefault

Sets the default loan type that will be used if none are defined or if the data source values do not match any values in the CollectiveAccess list loan_types.

{“loanTypeDefault”:”in”}

interstitial

Sets metadata for the Relationship record (between the target of the mapping and the related entity via the splitter)
{
“interstitial”: {

“relationshipDate”: “^4”

}

}

parents

Loan parents to create, if required. The parent parameter has several sub-parameters including:

idno: maps the level-specific idno

name: maps the level-specific preferred_label

type: maps the level-specific record type (must match the item idno exactly)

attributes: maps the (optional) level-specific metadata. Includes the metadataElement code and the data source.

rules: maps any (optional) level-specific rules
{
“parents”: [
{

“idno”: “^5”, “name”: “^6”, “type”: “in”, “attributes”: {

“ca_loans.description”: “^7”

}

}

]

}

relationships

From version 1.5. A list of relationships using the relevant splitter refineries. The settings for this item reflect the settings used for the relevant splitter refinery. The only additional setting here is relatedTable which is a required value.
{
“relationships”[
{

“relatedTable”: “ca_entities”, “type” : “ind”, “relationshipType”: “creator”, “preferredLabel”: “^7”, “attributes” : {

“notes” : “^10”

}

}, {

“relatedTable”: “ca_entities”, “type” : “org”, “relationshipType”: “source”, “preferredLabels” : [{“forename”: “^5”, “surname”:”^6”}], “attributes” : {

“phone” : “^33”

}

}

]

}

matchOn

From version 1.5. Defines exactly how the splitter will establish matches with pre-existing records. You can set the splitter to match on idno, or labels. You can also include both labels and idno in the matchOn parameter, and it will try multiple matches in the order specified.

{“matchOn”: [“labels”, “idno”]} -Will try to match on labels first, then idno. {“matchOn”: [“idno”, “labels”]} - Will do the opposite, first idno and then labels. You can also limit matching by doing one or the other. Eg: {“matchOn”: [“idno”]} will only match on idno. {“matchOn”: [“^ca_loans.your_custom_code”]} will match on a custom metadata element in the loan record. Use the syntax ^ca_loans.metadataElement code.

ignoreParent

From version 1.5. For use with loan item hierarchies. When set to true this parameter allows global match across the entire hierarchy, regardless of parent_id. Use this parameter with datasets that include values to be merged into existing hierarchies but that do not include parent information. Paired with matchOn it’s possible to merge the values using only name or idno, without any need for hierarchy info. Not ideal for situations where multiple matches can not be disambiguated with the information available.

{“ignoreParent”: “1”}

dontCreate

From version 1.5. If set to true (or any non-zero value) the splitter will only do matching and will not create new records when matches are not found.

{“dontCreate”: “1”}

measurementSplitter

Type of Refinery Parameter

Parameter Notes

Example

delimiter

Sets the value of the delimiter to break on, separating measurement values

{“delimiter”: “x”}

units

Sets the value of the measurement unit

{“units”: “in”}

elements

Maps the components of the dimensions to specific metadata elements
{
“elements”: [
{

“quantityElement”: “measurementWidth”, “typeElement”: “measurementsType”, “type”: “width”

}, {

“quantityElement”: “measurementHeight”, “typeElement”: “measurementsType2”, “type”: “height”

}

]

} Note: the typeElement and type sub-components are optional and should only be used in measurement containers that include a type drop-down.

attributes

Maps the other non-measurement elements that may be in the same container. Values here are set for all measurements being split.
{
“attributes”: {

“notes”: “^1”

}

}

tourStopSplitter

Builders

Please see Builders.

Joiners

entityJoiner

Type of Refinery Parameter

Parameter Notes

Example

entityType

Accepts a constant list item idno from the list entity_types or a reference to the location in the data source where the type can be found

{“entityType”: “person”}

entityTypeDefault

Sets the default entity type that will be used if none are defined or if the data source values do not match any values in the CollectiveAccess list entity_types.

{“entityTypeDefault”: “person”}

forename

Accepts a constant value for the forename or a reference to the location in the data source where the forename can be found.

{“forename”:”^3”}

surname

Accepts a constant value for the surname or a reference to the location in the data source where the surname can be found.

{“surname”: “^2”}

other_forenames

Accepts a constant value for the entity’s other forenames or a reference to the location in the data source where the other forenames can be found.

{“other_forenames”: “^10”}

middlename

Accepts a constant value for the middlename or a reference to the location in the data source where the middlename can be found.

{“middlename”: “^12”}

displayname

Accepts a constant value for the displayname or a reference to the location in the data source where the displayname can be found.

{“displayname”: “^14”}

prefix

Accepts a constant value for the prefix or a reference to the location in the data source where the prefix can be found.

{“prefix”: “^14”}

suffix

Accepts a constant value for the suffix or a reference to the location in the data source where the suffix can be found.

{“suffix”: “^14”}

attributes

Sets or maps metadata for the entity record by referencing the metadataElement code and the location in the data source where the data values can be found.
{
“attributes”: {
“agentDateSet”: {

“agentDate”: “^12”

}

}

}

nonpreferred_labels

List of non-preferred label values or references to locations in the data source where nonpreferred label values can be found. Use the split value for a label to indicate a value that should be split into entity label components before import.
{
“nonpreferred_labels”: [
{

“forename”: “^5”, “surname”: “^6”

}

]

} OR {

“nonpreferred_labels”: [
{

“split”: “^4”

}

]

}

relationshipType

Accepts a constant type code for the relationship type or a reference to the location in the data source where the type can be found

{“relationshipType”: “^10”}

relationshipTypeDefault

Sets the default relationship type that will be used if none are defined or if the data source values do not match any values in the CollectiveAccess system.

{“relationshipTypeDefault”: “author”}

skipIfValue

Skip if imported value is in the specified list of values.

{“skipIfValue”: “unknown”}

relatedEntities

This allows you to create and/or relate additional entities to the entity being mapped. For example, if you are running an Object mapping and using an entityJoiner to generate related Individuals, but you also want to create entity records for each individual’s affiliation, use this setting. “Name” is the name of the entity, which will be automatically split into pieces and imported. If you want to explicitly map pieces of a name (surname, forename) you can omit “name” and use “forename”, “middlename”, “surname”, etc. “type”, “attributes,” and “relationshipType” operate just as they would in a regular splitter.

{“relatedEntities”: [{“type”:”ind”, “name”: “^3”, “attributes”:{}, “relationshipType”:”related”}]}

interstitial

Sets metadata for the Relationship record (between the target of the mapping and the related entity via the splitter)
{
“interstitial”: {

“relationshipDate”: “^4”

}

}

dateJoiner

Type of Refinery Parameter

Parameter Notes

Example

mode

Determines how dateJoiner joins date values together. Two-column range (aka “range”) is the default if mode is not specified. Options are: multiColumnDate, multiColumnRange, range

{“mode”: “multiColumnDate”}

month

Maps the month value for the date from the data source. (For Multi-column date)

{“month”: “^4”}

day

Maps the day value for the date from the data source. (For Multi-column date)

{“day”: “^5”}

year

Maps the year value for the date from the data source. (For Multi-column date)

{“year”: “^6”}

startDay

Maps the day value for the start date from the data source. (For Multi-column range)

{“startDay”: “^4”}

startMonth

Maps the month value for the start date from the data source. (For Multi-column range)

{“startMonth”: “^5”}

startYear

Maps the year value for the start date from the data source. (For Multi-column range)

{“startYear”: “^6”}

endDay

Maps the day value for the end date from the data source. (For Multi-column range)

{“endDay”: “^7”}

endMonth

Maps the month value for the end date from the data source. (For Multi-column range)

{“endMonth”: “^8”}

endYear

Maps the year value for the end date from the data source. (For Multi-column range)

{“endYear”: “^9”}

expression

Date expression (For Two-column range)

{“expression” : “^dateExpression”}

start

Maps the date from the data source that is the beginning of the conjoined date range. (For Two-column range)

{“start” : “^dateBegin”}

end

Maps the date from the data source that is the end of the conjoined date range. (For Two-column range)

{“end”: “^dateEnd”}

skipStartIfExpression

Expression that if evaluating to true “start” date is omitted from joined range. Note “date” function – see above.

{“skipEndIfExpression”: “date(^end) < 1800”}

skipStartIfExpressionReplacementValue

Optional replacement value for start date when it is skipped by expression. Allows you to force start date to something if skip expression is true.

{“skipStartIfExpressionReplacementValue”: “unknown”}

skipEndIfExpression

Expression that if evaluating to true “end” date is omitted from joined range. Note “date” function – see above.

{“skipEndIfExpression”: “date(^end) > 2020”}

skipEndIfExpressionReplacementValue

Optional replacement value for end date when it is skipped by expression. This exists to allow you to force the end date to something specific like “present” for living artist’s life dates.

{“skipEndIfExpressionReplacementValue”: “present”}

dateAccuracyJoiner

Type of Refinery Parameter

Parameter Notes

Example

accuracyField (required)

The field in which the date accuracy is stored (case-insensitive values are defined by accuracyValueDay, accuracyValueMonth and accuracyValueYear settings)

{“accuracyField”: “14”} <= Where 14 is the column of the source data. Note that this does not get prefixed with the usual ‘^’.

dateFormat

The format in which the input dates are expected. Defaults to ‘Y-m-d’ (2014-04-01). Values come from phpDateTime::createFromFormat()

{“dateFormat”: “j-M-Y”} <= Would parse 15-Feb-2009

accuracyValueday

The case-insensitive value in the accuracy field that indicates that the date is accurate to the day. Default value is ‘day’.

{“accuracyValueDay”: “d”}

accuracyValueMonth

The case-insensitive value in the accuracy field that indicates that the date is accurate to the month. Default value is ‘month’.

{“accuracyValueMonth”: “m”}

accuracyValueYear

The case-insensitive value in the accuracy field that indicates that the date is accurate to the year. Default value is ‘year’.

{“accuracyValueYear”: “y”}

dateParseFailureReturnMode

Defines what should be returned if the input date cannot be parsed, available values are “null” (the default) and “original”

{“dateParseFailureReturnMode”: “original”}

unknownAccuracyValueReturnMode

Defines what should be returned if the value of the accuracy column is unknown, available values are “null”, “original” and “normalised” (the default)

{“unknownAccuracyValueReturnMode”: “null”}