Docline Field Translations

When your ILLiad system receives requests from the DOCLINE API, it needs to know where to put all that information in your ILLiad transactions. That's where field translations come in - they're like a roadmap that tells ILLiad which DOCLINE fields should go into which ILLiad fields.

Think of it as having a conversation between two systems that speak different languages. DOCLINE might send you a field called requesting_library, but ILLiad wants to store that information in Transaction.LendingLibrary. Field translations make that connection happen automatically.

For a full list of DOCLINE fields available for translation, refer to the list of DOCLINE field names.

Field Translation Direction

Field translations only work in one direction: DOCLINE → ILLiad. They map incoming DOCLINE request data to your ILLiad transaction fields, but don't affect requests that originate in ILLiad and get sent to DOCLINE.

Overview

Field translations work behind the scenes every time a DOCLINE request comes into your system. Here's what happens:

1. DOCLINE sends a request with information about what someone wants to borrow
2. Your ILLiad system looks at the field translations to figure out where each piece of information should go
3. The system maps the data from DOCLINE fields into the right ILLiad transaction fields
4. A new transaction gets created with all the information in the right places

Field translations can be conditional and vary between borrowing and lending processes. For example, an author's name might go into different fields depending on whether someone is requesting a copy of an article or wants to borrow an entire book. Some fields even have different mappings depending on whether your library is borrowing from others or lending to others.

Screenshot placeholder: Overview diagram showing DOCLINE request flow through field translations to create ILLiad transaction

Process-Specific Mappings

Borrowing and lending processes may have different field mappings for the same DOCLINE fields. Always verify which process type your mappings are configured for when troubleshooting issues.

Default Mappings

Your ILLiad system comes with a comprehensive set of pre-configured field translations that handle the most common scenarios. These default mappings cover both borrowing and lending processes and are designed to work for most libraries right out of the box. Some mappings work the same way for both processes, while others are specifically tailored to whether you're borrowing from other libraries or lending to them.

Basic Request Information

Screenshot placeholder: Default field mappings table showing basic request information mappings in Customization Manager

The foundation of every DOCLINE request gets mapped to core transaction fields:

DOCLINE Field	ILLiad Field	Purpose
id	Transaction.ILLNumber	Unique identifier for the request
requesting_library	Transaction.LendingLibrary	Which library is making the request
max_cost	Transaction.MaxCost	Maximum amount the borrower is willing to pay
need_by_date	Transaction.WantedBy	When the patron needs the material
service_level.value	Transaction.Rush	Whether this is a rush request
copyright_compliance.value	Transaction.CopyrightComp	Copyright compliance information

Publication Information

Screenshot placeholder: Publication information mapping examples showing conditional field routing

Here's where things get interesting. The same DOCLINE field might go to different places in ILLiad depending on what type of request it is:

Conditional Field Translations

Notice how the same DOCLINE field (like author) automatically goes to different ILLiad fields based on the request type. This ensures your transaction data is always organized correctly without any manual intervention.

DOCLINE Field	ILLiad Field (Article Requests)	ILLiad Field (Loan Requests)
author	Transaction.PhotoItemAuthor	Transaction.LoanAuthor
journal_title	Transaction.PhotoJournalTitle	Transaction.LoanTitle
book_title	Transaction.PhotoJournalTitle	Transaction.LoanTitle

This conditional mapping ensures that author and title information ends up in the right fields based on whether someone wants a photocopy or wants to borrow the actual item.

Article and Chapter Details

For copy requests, you need specific information about articles and chapters:

DOCLINE Field	ILLiad Field	Notes
article_title	Transaction.PhotoArticleTitle	Title of the specific article
chapter_title	Transaction.PhotoArticleTitle	Title of the book chapter
article_authors	Transaction.PhotoArticleAuthor	Authors of the article
chapter_author	Transaction.PhotoArticleAuthor	Author of the chapter
article_volume_string	Transaction.PhotoJournalVolume	Journal volume number
article_issue	Transaction.PhotoJournalIssue	Journal issue number
article_pages	Transaction.PhotoJournalInclusivePages	Page range being requested

Advanced Pattern Matching

Screenshot placeholder: Advanced pattern matching configuration showing regex patterns and extraction examples

Some DOCLINE fields contain multiple pieces of information that need to be split up. The system can use pattern matching to extract what it needs:

Pattern Complexity

Pattern matching uses regular expressions to extract specific parts of field values. The complexity and requirements of these patterns can vary significantly between borrowing and lending processes.

Date Information: The article_year_string field might contain "2023 Jan" and the system can:

• Extract just "2023" for the year field
• Extract "Jan" for the month field
• Send different parts to different fields based on request type
• Use different extraction patterns for borrowing vs lending (borrowing allows optional year with pattern (\d{4})?(?:\s*)([a-zA-Z]{3})?, while lending requires year with pattern (\d{4})(?:\s*)([a-zA-Z]{3})?)

Identifiers: Multiple identifier fields can be checked in priority order. For ISBN/ISSN information, the system looks at:

1. issn_isbn first
2. journal_issn if the first isn't available
3. journal_issn_electronic as a final option

Borrowing vs Lending Process Differences

Screenshot placeholder: Side-by-side comparison of borrowing vs lending field mapping configurations

While most field mappings work the same way regardless of whether you're borrowing from other libraries or lending to them, there are some important differences to be aware of:

Critical Process Differences

The differences between borrowing and lending field mappings are not just preferences - they're designed to support different workflows. Pay special attention to PMID field mapping and date pattern requirements.

PMID Field Mapping: This is the most significant difference between processes:

• Borrowing requests: The article_pmid field maps only to Transaction.PMID
• Lending requests: The article_pmid field maps to both Transaction.ESPNumber and Transaction.PMID

Publisher Field Mapping:

• Borrowing requests: Publisher information uses direct field mapping
• Lending requests: Publisher information uses conditional mapping based on other field values

Date Pattern Complexity: The system uses different regex patterns depending on the process:

• Borrowing patterns: Allow for more flexibility, such as (\d{4})?(?:\s*)([a-zA-Z]{3})? where the year is optional
• Lending patterns: Require more specific formats, such as (\d{4})(?:\s*)([a-zA-Z]{3})? where the year is required

These differences ensure that each process handles the information in the way that works best for that particular workflow.

Delivery and Contact Information

DOCLINE requests include detailed delivery information that maps to custom fields:

DOCLINE Field	ILLiad Field	Purpose
patron_name	Custom.BorrowerTN	Name of the person requesting the material
delivery_odyssey	Custom.OdysseyAddress	Electronic delivery address
borrower_comments	Custom.Comments	Special instructions from the borrower
delivery_institution_name	Custom.ShipTo.Institution	Institution name for shipping
delivery_library_dept_name	Custom.ShipTo.Department	Department within the institution
delivery_street_1	Custom.ShipTo.Address1	Primary street address
delivery_street_2	Custom.ShipTo.Address2	Secondary address line
delivery_city	Custom.ShipTo.Locality	City for delivery
delivery_state_province	Custom.ShipTo.Region	State or province
delivery_zip	Custom.ShipTo.PostalCode	Postal/ZIP code
delivery_country	Custom.ShipTo.Country	Country for international shipping

Screenshot placeholder: Complete default field mappings table in Customization Manager showing all delivery and contact information mappings

Custom Mappings

While the default mappings work great for most situations, every library is different. You might need to customize how certain fields get mapped to better fit your workflows or to capture information in custom fields that are specific to your library.

Accessing Field Translations

Screenshot placeholder: Customization Manager main interface with System Tables highlighted

You'll find field translation settings in the Customization Manager:

1. Open the Customization Manager from your ILLiad Client
2. Navigate to System Tables in the left sidebar
3. Find the DOCLINE section and click on it
4. Select DoclineFieldTranslations from the list

Screenshot placeholder: Step-by-step navigation path from System Tables → DOCLINE → DoclineFieldTranslations

Navigation Helper

If you can't find the DOCLINE section, use the search function in Customization Manager to quickly locate "DoclineFieldTranslations" table.

Understanding the Translation Settings

Screenshot placeholder: DoclineFieldTranslations table interface showing column headers and sample records

Each field translation record has several important pieces:

Record Structure

Every field translation record follows the same structure, but the way you fill out the fields determines whether it's a simple direct mapping or a complex conditional mapping.

Field Name: This is the DOCLINE field name that contains the information you want to map. You can actually specify multiple field names separated by pipe symbols (|) if you want the system to try several fields in order.

Target: This is where the information should go in ILLiad. You can specify multiple targets separated by commas if you want the same information copied to several places.

Process Type: Choose whether this mapping applies to Borrowing requests, Lending requests, or both.

Translation Type:

• ImportTarget: A direct mapping that always applies (these are tried first)
• ComparatorImportTarget: A conditional mapping that only applies when another field has a specific value (these are used as fallback if no ImportTarget mapping applies)

Creating Simple Field Translations

Let's say you want to map a DOCLINE field called special_instructions to a custom field called Transaction.SpecIns. Here's how:

1. Click "Add New Record" in the DoclineFieldTranslations table
2. Set the Field Name to special_instructions
3. Set the Target to Transaction.SpecIns
4. Choose the Process Type Borrowing or Lending--if you want the field translation to work for both, you will need to create two field translation entries
5. Set Translation Type to ImportTarget
6. Save your changes

Screenshot placeholder: Add new record dialog for DoclineFieldTranslations showing simple mapping configuration fields

Testing New Field Translations

After creating a new field mapping, always test it with sample data before relying on it for production requests.

Creating Conditional Field Translations

Conditional field translations are more sophisticated - they only apply when certain conditions are met. For example, you might want author information to go to different fields based on the request type:

1. Create the first field translation:

   • Field Name: author
   • Target: Transaction.PhotoItemAuthor
   • Translation Type: ComparatorImportTarget
   • Match Field Name: request_type_requested.value
   • Match Value: Copy

2. Create the second field translation:

   • Field Name: author
   • Target: Transaction.LoanAuthor
   • Translation Type: ComparatorImportTarget
   • Match Field Name: request_type_requested.value
   • Match Value: Loan

Now the system will put author information in different places depending on whether it's a copy or loan request.

Screenshot placeholder: Conditional field translation configuration showing Match Field Name and Match Value fields filled out

Exact Matching Required

Conditional field translations require exact matches for field names and values. "Copy" is different from "copy" - case sensitivity matters!

Using Multiple Source Fields

Sometimes you want to check several DOCLINE fields and use whichever one has information. You can specify multiple field names separated by pipe symbols:

Field Name: issn_isbn|journal_issn|journal_issn_electronic Target: Transaction.Issn

The system will try each field in order until it finds one with data.

Mapping to Multiple Targets

If you want the same DOCLINE information copied to multiple ILLiad fields, separate the target field names with commas:

Field Name: article_pmid Target: Transaction.PMID (for borrowing) or Transaction.ESPNumber,Transaction.PMID (for lending)

This puts the PubMed ID in the PMID field for borrowing requests, but for lending requests it goes to both the ESP Number field and the PMID field.

Data Overwrite Risk

Be extremely careful when mapping to multiple targets. You could accidentally overwrite important information in existing fields or create data conflicts.

Advanced Pattern Extraction

For more complex scenarios, you can use pattern extraction to pull specific parts of a field value. This requires setting up a regular expression pattern that tells the system exactly what to extract.

For example, if a DOCLINE field contains "2023 Jan" and you want to extract just the year:

Field Name: article_year_string Target: Transaction.PhotoJournalYear Import Regex Pattern: (\d{4}) or (\d{4})?(?:\s*)([a-zA-Z]{3})?

The pattern (\d{4}) tells the system to find and extract a four-digit number (the year). More complex patterns like (\d{4})?(?:\s*)([a-zA-Z]{3})? can handle optional years and month abbreviations, with different complexity depending on whether it's used for borrowing or lending.

Advanced Feature Warning

Regular expression patterns require technical expertise and can break field translations if configured incorrectly. Always test thoroughly in a development environment first.

Testing Field Translations

After you've set up custom field translations, it's important to test them to make sure they're working correctly. Here's how to verify your field translations are doing what you expect:

Test with Sample Data

Screenshot placeholder: Testing workflow diagram showing steps from custom field translation setup to verification

The best way to test field translations is to work with your DOCLINE contacts to send some test requests that you can monitor:

1. Set up your custom field translations in the Customization Manager
2. Save and restart your ILLiad services to ensure the changes take effect
3. Ask your DOCLINE contacts to send a few test requests with known data
4. Check the resulting ILLiad transactions to see if the information ended up in the right fields

Screenshot placeholder: Sample ILLiad transaction showing mapped fields with annotations pointing to DOCLINE source data

Coordination with DOCLINE

Work with your DOCLINE contacts to schedule test requests during low-traffic periods. This makes it easier to identify and examine the test transactions.

Monitoring Field Translation Activity

You can keep an eye on how field translations are working by checking the ILLiad client logs. Look for entries that mention field translation activity - they'll show you which DOCLINE fields were processed and where the information was placed.

Verifying Conditional Field Translations

Conditional field translations require special attention because they only work under specific circumstances:

1. Test with requests that meet the condition (e.g., Copy requests if your condition checks for request_type_request.value = "Copy")
2. Test with requests that don't meet the condition to make sure the mappfield translation is ignored when it should be
3. Check that the Match Field Name and Match Value are exactly what appears in the actual DOCLINE requests

Common Testing Scenarios

New Custom Field Translation: Send a test request with known data in the DOCLINE field and verify it appears in your custom ILLiad field.

Modified Existing Field Translation: Compare how the same type of request was handled before and after your changes.

Conditional Logic: Send both Copy and Loan requests to ensure conditional field translations work correctly for each type.

Multiple Source Fields: Send requests with data in different priority fields to ensure the fallback logic works.

Borrowing vs Lending Differences: Test the same field with both borrowing and lending requests to verify process-specific field translations work correctly (such as PMID field translations).

Mapping Precedence: Verify that ImportTarget field translations are tried before ComparatorImportTarget field translations as expected.

Documentation Best Practice

Keep detailed notes about your test requests and results. Include the DOCLINE field values, expected ILLiad fields, and actual results. This documentation will be invaluable for troubleshooting and staff training.

Troubleshooting

Even with careful setup, you might run into issues with field translations. Here are the most common problems and how to solve them:

Information Not Appearing in Expected Fields

Screenshot placeholder: Example ILLiad transaction with missing field data highlighted

Symptoms: DOCLINE requests are coming in, but information isn't showing up where you expect it in ILLiad transactions.

Common Issue

This is the most frequently reported field translation problem. Usually it's a simple mismatch between configured field names and the actual DOCLINE field names.

Possible Causes:

• The DOCLINE field name in your field translation doesn't match the actual field name in the incoming request
• The field translation record is set up for the wrong process type (Borrowing vs. Lending)
• There's a typo in the Target field name

Solutions:

1. Check the exact DOCLINE field names by looking at the raw request data or consulting DOCLINE documentation
2. Verify the Process Type matches the type of requests you're receiving
3. Double-check spelling of both DOCLINE field names and ILLiad target field names
4. Restart ILLiad services after making changes to ensure they take effect

Conditional Field Translations Not Working

Symptoms: Your conditional field translations seem to be ignored, or information is going to the wrong fields.

Possible Causes:

• The Match Field Name doesn't exactly match the field name in DOCLINE requests
• The Match Value doesn't exactly match the values that actually appear in requests
• Multiple conditional field translations conflict with each other

Solutions:

1. Verify the exact field names and values that appear in real DOCLINE requests
2. Check for case sensitivity - "Copy" is different from "copy"
3. Look for extra spaces or other characters in field values
4. Test with known data to isolate the problem

Screenshot placeholder: Troubleshooting interface showing actual DOCLINE field values compared to configured match values

Information Appearing in Wrong Fields

Symptoms: Data from DOCLINE is showing up in your ILLiad transactions, but not where you want it.

Possible Causes:

• Multiple field translation records are conflicting
• Default field translations are overriding your custom field translations
• Regular expression patterns are extracting unexpected parts of field values

Solutions:

1. Review all field translation records for the same DOCLINE field name
2. Check the precedence between ImportTarget and ComparatorImportTarget field translations
3. Test regex patterns separately to ensure they're working as expected
4. Consider the order in which translations are processed

Custom Fields Not Saving Data

Symptoms: Your field translations to custom fields seem correct, but the data isn't being saved.

Possible Causes:

• The custom field doesn't exist in your ILLiad system
• The custom field name format is incorrect
• Field length restrictions are causing data to be truncated

Solutions:

1. Verify the custom field exists and is active in your system
2. Check the custom field name format (e.g., Custom.FieldName vs. just FieldName)
3. Review field length limits and consider truncating long values
4. Test with shorter sample data to isolate length issues

Services Not Picking Up Changes

Symptoms: You've made changes to field translations, but they don't seem to be taking effect.

Solutions:

1. Save your changes in the Customization Manager
2. Restart the ILLiad services that handle DOCLINE integration
3. Wait for the changes to propagate in multi-server environments
4. Check for caching that might be preventing updates from taking effect

Production Safety

Always test field translation changes in a development environment before implementing them in production. DOCLINE integration affects real patron requests - incorrect field translations can disrupt your entire interlibrary loan workflow.