As of ILLiad Web Platform v9.2.3 and ILLiad Customization Manager v9.2.6, the ApiRequestMapping table in the ILLiad Customization Manager allows you to configure mappings that will transform the submitted values for specified fields on incoming ILLiad requests before they are stored in the ILLiad database when receiving new transactions from an external application or system through the ILLiad Web Platform. For example, you might use this feature to map the pickup location codes submitted with new requests from an external application to the corresponding code for each location used in ILLiad if the codes differ between the two applications. This article will detail how this table is configured and provide several examples of the different types of data transformations that the table can perform on incoming transaction field values.
Overview | Configuring the ApiRequestMapping Table | Example Use Cases | Data Type Support
Overview
The ApiRequestMapping table can be configured to match submitted field values using text comparisons or regular expression evaluation, and then replace those values with either static values or with a replacement that can take advantage of regular expression capture groups, depending on your needs. Each entry in the ApiRequestMapping table must specify a corresponding row in the WebPlatformConfig table so that the data transformation is only applied to requests submitted using the API key configured in that row. As each application or external system accessing the ILLiad Web Platform should have its own unique API Key configured in the WebPlatformConfig table, you can use the ApiRequestMapping table to set up unique data transformations for each external system you have configured to submit new requests to ILLiad in the WebPlatformConfig table.
Configuring the ApiRequestMapping Table
To configure a new entry in the ApiRequestMapping table:
- Navigate to System | General | ApiRequestMapping in the ILLiad Customization Manager.
- Click New Record.
- Fill out the following fields:
| WebPlatformConfigID | The ID of the entry in the WebPlatformConfig table containing the specific API key for which you want the data transformation applied. |
| ILLiadFieldName |
The name of the ILLiad field to which the mapping applies and into which the transformed data will be stored. Valid fields are those defined in the Create Transaction endpoint for submitting new requests to the ILLiad web platform, with some exceptions. Not all fields from the Transactions table are supported for use with this feature. See Data Type Support below for more information on supported fields. |
| RemoteFieldValue |
The value to use when comparing against the submitted value for the ILLiadFieldName field to determine if the transformation specified in the ILLiadFieldValue column should be applied. How this value is formatted varies depending on the action specified in the Action column for this mapping:
|
| ILLiadFieldValue | The value that should replace the submitted value for the ILLiadFieldName field in the case that the comparison defined in the RemoteFieldValue column matches the submitted value. The value in this column can contain references to regular expression capture groups when using the Replace action. |
| Action |
This can be set to one of two values, depending on how you want to match and transform the incoming value from the submitted transaction before it is stored in the ILLiad database:
See the Example Use Cases section below for more information on how to configure entries in the ApiRequestMapping table for each of these actions. |
Example Use Cases
This section will detail several examples of how to use the Replace and Substitute actions in conjunction with the ILLiadFieldName, RemoteFieldValue, and ILLiadFieldValue columns to configure various types of mappings to transform incoming transaction data.
Note: The WebPlatformConfigID column value is omitted in each of the configuration examples below, but should be configured to contain the ID of the entry in the WebPlatformConfig table containing the specific API key for which you want the data transformation applied when adding these rules to the ApiRequestMapping table.
Using the Replace Action | Using the Substitute Action
Using the Replace Action
The Replace action applies regular expressions defined in the RemoteFieldValue column to the value from the incoming transaction's ILLiadFieldName field to determine if the value matches the criteria to apply the mapping and perform the data transformation defined in the ILLiadFieldValue column. The data transformation can either use capture groups to capture all or part of an incoming RemoteFieldValue and transfer that data dynamically into the format specified in the ILLiadFieldValue column, can simply replace that incoming value with a static value specified in the ILLiadFieldValue column. An example of each type of data transformation is provided below.
Replacement with Capure Groups | Replacement with Static Values
Replacement with Capture Groups
The following rules will use a regular expression defined in the RemoteFieldValue column to match the incoming value and replace it with a value defined in the ILLiadFieldValue column that uses capture groups to incorporate the submitted data. This is done by using a series of regular expressions in the RemoteFieldValue and ILLiadFieldValue columns as follows:
- Using regular expressions, define a group or groups of values to be captured from the incoming remote field in the RemoteFieldValue column. Groups are defined by a set of parentheses and will be numbered starting at an index of 1 from left to right.
- Use appropriate numbered group replacement expressions ($1, $2, etc.) in the ILLiadFieldValue column to define how those group(s) captured from the remote field value should be used to modify the value before it is written to the ILLiad database.
Testing Regular Expressions
The following resource is helpful in testing regular expressions: https://regex101.com/
Example 1: Capture Part of an Incoming Value to Remove a Text Prefix
This rule will strip the "Phone: " prefix from an incoming phone number value so that only the phone number itself is stored in the specified ILLiad transaction field:
Configuration:
| ILLiadFieldName | RemoteFieldValue | ILLiadFieldValue | Action |
| ItemInfo1 | Phone: (.+) | ($1) | Replace |
Results:
When incoming data from the ItemInfo1 field on the submitted transaction matches the format "Phone: [Any Value]" all data after the "Phone:" prefix is captured and stored in the ItemInfo1 field without the "Phone: " prefix. For example, an incoming transaction submitting the value ”Phone: 555-555-5555” for the ItemInfo1 field will result in an ILLiad transaction object where the ItemInfo1 field is set to ”555-555-5555”.
Note: Using the ".+" regular expression in the RemoteFieldValue column will mean that only submitted values that contain a value after the "Phone: " prefix will be considered a match for this rule. If no value is present after this prefix (e.g., a value of "Phone: " with no actual phone number or other value following the prefix), the rule will not be considered a match and the mapping will not be applied.
Example 2: Capture an Incoming Value and Add a Text Prefix
This rule will capture all data submitted for the specified transaction field and add a pre-defined text prefix to the value stored for the field on the new ILLiad transaction:
Configuration:
| ILLiadFieldName | RemoteFieldValue | ILLiadFieldValue | Action |
| ItemInfo2 | (.+) | User submitted value: ($1) | Replace |
Results:
All incoming data submitted for the ItemInfo2 field on the incoming transaction is captured and stored in the ItemInfo2 field using the format "User submitted value: [Captured Remote Value]". For example, if the incoming transaction submits the value ”Sample” for the ItemInfo2 field, this will result in an ILLiad transaction object where the ItemInfo2 field is set to “User submitted value: Sample”.
Note: Using the ".+" regular expression in the RemoteFieldValue column will mean that only submitted values that contain an actual value (including a blank space) will be considered a match for this rule. If no value is submitted for the ItemInfo2 field, the rule will not be considered a match and the mapping will not be applied.
Replacement with Static Values
The following rule will apply the regular expression defined in the RemoteFieldValue column to the submitted value for the field specified in the ILLiadFieldName column to determine if the value matches and the mapping rule should be applied. If it matches, the new transaction’s field value will be set to the static value specified in the ILLiadFieldValue column. This action does not make use of capture groups and is useful for transforming submitted field values that do not typically need to be replaced with dynamic values.
Example 1: Replace Incoming Field Values Containing "Offsite" with a Static Value
This rule can be used to replace any incoming values with the text offsite with a static value:
Configuration:
| ILLiadFieldName | RemoteFieldValue | ILLiadFieldValue | Action |
| Location | .*offsite.* | Atlas Offsite Storage | Replace |
Results:
When a new transaction is submitted with a Location field that contains the text "offsite" anywhere in the submitted value, the Location field value will be set to "Atlas Offsite Storage".
Description of the Regular Expression Match Performed
The RemoteFieldValue makes use of the .* regular expression to perform the match for the incoming field value. Placing the regular expression .* before and after the value "offsite" in the RemoteFieldValue column means that the submitted value can contain any or no value before or after the string "offsite" for this rule to be considered a match. For example, this rule will consider submitted values of "offsite", "Atlas offsite", "Offsite location", or "Atlas offsite location" to be a match and will apply the mapping to replace that value with the value "Atlas Offsite Storage".
Using the Substitute Action
The Substitute action is used to perform a blanket substitution with the static value defined in the ILLiadFieldValue column for the exact, case-sensitive value specified in the RemoteFieldValue column.
Substitution with a Static Value
If the submitted value for the field specified in the ILLiadFieldName column exactly matches the value specified in the RemoteFieldValue column, the new transaction’s field value will be set to the static value specified in the ILLiadFieldValue column. The submitted value must match the RemoteFieldValue exactly and is case-sensitive.
Example 1: Map an Incoming Repository Code to the Repository's Full Name
The following rule can be used to translate a repository code to the repository's full name:
Configuration:
| ILLiadFieldName | RemoteFieldValue | ILLiadFieldValue | Action |
| Location | AOS | Atlas Offsite Storage | Substitute |
Results:
When a new transaction is submitted with a Location field value of "AOS", it will be mapped to the value "Atlas Offsite Storage" (i.e., "Atlas Offsite Storage" will be the value set for the new ILLiad request in the Location field instead of "AOS").
Note: In this example, the submitted value for the Location field must match the RemoteFieldValue AOS exactly, so submitted values such as "Aos" or "The AOS" will not be considered a match and the mapping will not be applied in those cases.
Example 2: Define a Default Value for a Field When None is Provided
The following rule can used to define a default value for a field if none is provided.
Configuration:
| ILLiadFieldName | RemoteFieldValue | ILLiadFieldValue | Action |
| ItemInfo1 | None Selected | Substitute |
Results:
When a new transaction is submitted with an empty ItemInfo1 field, it will be mapped to the value "None Selected" (i.e., "None Selected" will be the value set for the new ILLiad request in the ItemInfo1 field).
Note: ILLiad will treat a null value as an empty string (""), meaning that this mapping rule will be performed both in the case that ItemInfo1 is submitted as an empty string or not submitted at all. If any other value at all is submitted for ItemInfo1, this rule won't apply and the mapping will not be performed.
Data Type Support
Support for the different actions that can be performed by the ApiRequestMapping table described in the Example Use Cases section above will vary based on the data type of the ILLiad field used in the ILLiadFieldName column:
Only fields defined in the Create Transaction endpoint used for submitting new requests to the ILLiad web platform, with some exceptions. These are typically all fields contained in the ILLiad Transactions database table. You can view the complete list of these fields in the ILLiad Database Tables documentation. Note that fields with the field type "nvarchar(3)" in this article are considered Boolean fields.
Note: In addition to the fields prohibited by the data type restrictions noted below, the TransactionNumber, CreationDate, and TransactionDate fields are also not supported for use with this feature.
| Data Type | Supported Actions |
| String |
|
| Int, Decimal, Double |
Note: For any numeric fields, ILLiad will try to convert the submitted value to a string before applying the mapping rules. There are potential issues during this string conversation, such as leading or trailing zeros being truncated from the incoming value. |
| Boolean |
The following strings are supported for evaluating incoming Boolean field values and for setting the new values for Boolean fields:
Note: In order to create a mapping rule that assigns a default value to a Boolean field when no value is submitted for that field, it must be nullable. Otherwise, the field will have a default value of false and will never be considered a match for the mapping rule. Nullable Boolean fields are:
|
| Enumerations | Enumerations (the RequestType and ProcessType fields) are not supported. |
| DateTime | DateTime fields such as DueDate are not supported. |