Splitters

Splitter refineries can either create records or match data to existing records (following a mapping’s existingRecordPolicy) or break a single string of source data into several metadata elements in CollectiveAccess. Splitters for relationships are used when several parameters are required, such as setting a record type and setting a relationship type. Using the entitySplitter, a name in a single location (i.e. column) in a data source can be parsed (into first, middle, last, prefix, suffix, et al.) within the new record. Similarly the measurementSplitter breaks up, for example, a list of dimensions into to a CollectiveAccess container of sub-elements. “Splitter” also implies that multiple data elements, delimited in a single location, can be “split” into unique records related to the imported record.

Refinery Options

Splitter

Refinery Options

collectionSplitter

attributes, collectionType, collectionTypeDefault, delimiter, dontCreate, ignoreParent

entitySplitter

attributes, delimiter, displayNameFormat, dontCreate, entityType, entityTypeDefault, ignoreParent

listItemSplitter

attributes, delimiter, dontCreate, ignoreParent

loanSplitter

attributes, delimiter, dontCreate, ignoreParent

measurementsSplitter

attributes, delimiter, elements

movementSplitter

attributes, dontCreate, ignoreParent

placeSplitter

attributes, dontCreate, ignoreParent

objectSplitter

attributes, dontCreate, ignoreParent

objectLotsSplitter

attributes, dontCreate, ignoreParent

occurrenceSplitter

attributes, dontCreate, ignoreParent

tourStopSplitter

attributes, dontCreate, ignoreParent

storageLocationSplitter

attributes, dontCreate, ignoreParent

attributes

Sets or maps metadata for newly created records by referencing the metadataElement code and the location in the data source where the data values can be found

See below for additonal attribute settings for the entitySplitter and objectRepresentationSplitter

Example

{"attributes": {
   "address": {
      "address1": "^24",
      "address2": "^25",
      "city": "^26",
      "stateprovince": "^27",
      "postalcode": "^28",
      "country": "^29"
   }
}
        }

entitySplitter Additional Properties

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":"%"}

objectRepresentationSplitter Additional Properties

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"
}
}

*Type

Accepts a constant list item idno from the list (collection_types, object_types, entity_types, list_item_types, loan_types) or a reference to the location in the data source where the type can be found

{"collectionType": "box"}

{"entityType": "person"}

{"listItemType": "concept"}

{"loanType":"out"}

*TypeDefault

Sets the default type that will be used if none are defined or if the data source values do not match any values in the CollectiveAccess list types (collection_types, object_types, entity_types, list_item_types, loan_types).

{"collectionTypeDefault":"series"}

{"entityTypeDefault":"individual"}

{"loanTypeDefault":"in"}

{"listItemTypeDefault":"concept"}

relationshipType

Specifies the relationship type to use for relationships created between related records matched or created by the splitter and the subject record. Can be either a constant value or a reference to a location in the data source where the relationship type value can be found.

relationshipTypeDefault

Specifies a relationship type to use if relationshipType is not set. This is useful when relationshipType references a location in the data source that is not always set.

extractRelationshipType

If set the splitter will attempt to extract relationship type from the data being split. By default it will consider text enclosed in parens as relationship type values. Set to “{}” or “[]” or look for text enclosed with those brackets instead. [Available from version 1.8]

relationshipTypeDelimiter

If set splitter will use the relationship type value as a list of types with the specified delimiter. A relationship will be created between split records and the subject record for each relationship type in the list. [Available from version 1.8]

delimiter

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

{"delimiter": ";"}

Applicable Refineries: collection Splitter, entitySplitter, listItemSplitter, loanSplitter, measurementsSplitter, movementSplitter, placeSplitter, objectSplitter, objectLotSplitter, objectRepresentationSplitter, occurrenceSplitter, tourStopSplitter

displayNameFormat

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"}

Applicable Refineries: entitySplitter

dontCreate

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"}

Applicable Refineries: collectionSplitter, entitySplitter, listItemSplitter, loanSplitter, movementSplitter, objectLotsSplitter, objectRepresentationSplitter, objectSplitter, occurrenceSplitter, placeSplitter, tourStopSplitter

elements (for measurements splitter)

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.

Applicable Refineries: measurementsSplitter

ignoreParent

For use with 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"}

Applicable Refineries: collectionSplitter, entitySplitter, listItemSplitter, loanSplitter, movementSplitter, objectLotsSplitter, objectSplitter, occurrenceSplitter, placeSplitter, tourStopSplitter

ignoreType

For use with hierarchies. Normally the splitter will only look for matching records with the same type as that in the import data. When set to true this parameter allows global matching across the entire hierarchy, ignoring record type. Use this parameter with datasets that include values to be merged into existing hierarchies where type may not be stated accurately or at all. Paired with matchOn it’s possible to merge the values using only name or idno, without regard for type. Note that in situations where multiple matches on idno or label occur across types, use of this option may lead to incorrectly imported data.

{"ignoreType": "1"}

Applicable Refineries: objectSplitter, objectLotSplitter, objectRepresentationSplitter, entitySplitter, occurrenceHierarchyBuilder, loanSplitter, movementSplitter, placeSplitter, storageLocationSplitter, listItemSplitter, tourStopSplitter, listItemIndentedHierarchyBuilder, collectionHierarchyBuilder, placeHierarchyBuilder, collectionIndentedHierarchyBuilder, occurrenceHierarchyBuilder, storageLocationHierarchyBuilder, objectHierarchyBuilder, listItemHierarchyBuilder, entityHierarchyBuilder

isPrimary

For use with the objectRepresentationSplitter. When set the first identified representation will be marked primary. In import mappings with multiple uses of objectRepresentationSplitters this option allows for control over which representation is marked as primary. If not set, the first representation created will be marked as primary. (Option is available from version 1.8).

interstitial

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

{
   "interstitial": {
      "relationshipDate": "^4"
   }
}

Applicable Refineries: collectionSplitter, entitySplitter, listItemSplitter, loanSplitter, movementSplitter, objectLotsSplitter, objectSplitter, occurrenceSplitter, placeSplitter, tourStopSplitter

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"}

Applicable Refineries: listItemSplitter

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.”