Tag Replacement in Addon Settings
To better integrate with external systems such as Caiasoft or ReShare, some Atlas addons make use of a feature called “tag replacement” that allows you to configure a tag defining a specific database table and field from which to pull a value into an addon setting. When the addon runs, that tag will be replaced with the appropriate value located and pulled from the database for each specific request.
However, as the names of different fields and their values may not match exactly between an Atlas product like ILLiad or Aeon and an external integrating system, addons that integrate with these systems will sometimes also need to map the necessary Atlas fields and values to their appropriate counterparts in the external system. As such, tag replacement will often require configuring two separate settings within the addon to accomplish this:
A field lookup setting that first defines an Atlas database field from which to pull a value. This is the setting where the tag itself is configured.
A separate field mapping setting that defines how to adjust that value appropriately before sending it to the integrating system.
Tag replacement will sometimes only require configuring the first field lookup setting when mapping is not necessary. In these cases, a separate field mapping setting will not be available.
Field Lookup Setting
This setting makes use of a specifically formatted tag to define which database field the addon will use to pull the value that will be sent to the integrating system. This tag generally uses the format {TableField:<DatabaseTableName>.<FieldName>} where <DatabaseTableName> and <FieldName> define the name of the database table and the specific field in that table from which to pull the value.
Example
A field lookup setting containing {TableField:User.NVTGC} will look at the User table in the database, and from that table, pull the value stored in the NVTGC field.
Using Static Values
Field lookup settings that use the tag replacement feature do not require configuring a tag for that setting. A static value (i.e., a value that does not change) can be used in place of the tag if you would like to pass through the same value each time rather than a dynamically changing value pulled from the database.
Example
If you have only one NVTGC value you’d like to pass through each time the addon runs, instead of entering the tag {TableField:User.NVTGC} in the field lookup setting to pull the user’s NVTGC value from the database, you can simply enter the static value of the NVTGC you want to use (e.g. “ILL”).
Appending a Static Value
Static values can also be appended before or after the value pulled from the field defined in the tag.
Field Mapping Setting
This setting defines how to map a value pulled from the Atlas database field specified in the field lookup setting to its appropriate corresponding value in the integrating system. Mapping settings are in the format <Key>=<NewValue>, where <Key> defines a specific value pulled from the Atlas database and <NewValue> defines the corresponding value in the integrating system to which it should be changed.
Mapping settings can contain multiple comma-separated key-value pairs in the case that several different Atlas values need to be mapped to new values in the integrating system (e.g. “ILL=DEFAULT_CIRC_DESK, MAIN=MAIN”)
Field Lookup and Mapping Workflow Example
To understand how the field lookup and mapping settings work together within the workflow of an addon, consider the following User record for Matt Calsada and addon setting configurations:
User Record
Field Name | Value |
|---|---|
FirstName | Matt |
LastName | Calsada |
NVTGC | ILL |
Addon Settings
Setting | Value |
|---|---|
Field Lookup | {TableField:User.NVTGC} |
Field Mapping | ILL=DEFAULT_CIRC_DESK |
Workflow
When a request for Matt Calsada is handled by the addon, it will perform the following processes in this order:
The field lookup setting will use the configured tag to determine that the addon should check the User table in the database and find Matt’s User record.
The addon will then check the NVTGC field on Matt’s User record and pull the value “ILL” contained in this field.
The field mapping setting will cause the addon to take the pulled “ILL” value and change it to “DEFAULT_CIRC_DESK” before it is sent to the integrating system.
“DEFAULT_CIRC_DESK” will be sent to the integrating system and the rest of the addon workflow will proceed normally.