Skip to main content
Version: ILLiad 10.0 (Pre-release) 🚧

Docline API Configuration

This integration allows your library to connect directly with the National Library of Medicine's DOCLINE system, streamlining your interlibrary loan workflow by enabling the submission and updating of DOCLINE requests directly through the ILLiad client.

This guide will walk you through the complete setup process, from initial configuration to verifying that everything is working correctly.

The following video demonstrates how to generate API credentials, authenticate with DOCLINE, and verify your connection:

ILLiad 10 DOCLINE API Configuration video thumbnail

Prerequisites​

Before you begin setting up the DOCLINE API integration, make sure you have the following in place:

System Requirements​

  • Web browser access - You'll need a web browser for the authentication process
  • ILLiad Administrator access - You'll need access to the ILLiad Customization Manager

Configuration Requirements​

  • WebApiUrl configured - Your WebApiUrl customization key must be properly set up in ILLiad. This is essential for the OAuth authentication process to work correctly. The underlying customization key is named DoclineApiCredentials.
Important Note

The WebApiUrl setting is crucial for DOCLINE integration because it's used to create the callback URL that DOCLINE will use during the authentication process. Without this, the setup cannot proceed. This setting cannot contain localhost or 127.0.0.1.

Initial Setup Overview​

Setting up DOCLINE integration involves three main phases:

  1. Generate API credentials - Create the connection credentials that ILLiad will use to communicate with DOCLINE
  2. Authenticate with DOCLINE - Complete the OAuth authentication process to authorize ILLiad to access your DOCLINE account
  3. Verify the connection - Test that everything is working correctly

The entire process typically takes just a few minutes and is done through the ILLiad Customization Manager interface.

Multi-Site Installations​

If you're running a shared ILLiad server that serves multiple libraries, each site gets its own set of credentials. This ensures that each library maintains independent access to DOCLINE services.

The system automatically manages separate credentials based on your site's NVTGC, so you don't need to worry about cross-site authentication conflicts.

Step-by-Step Setup​

Step 1: Open the DOCLINE Configuration​

  1. Open the ILLiad Customization Manager
  1. In the left navigation menu, expand System > Docline
  1. Locate and click on DoclineApiCredentials in the customization keys list
What You'll See

You'll see a configuration area specifically for DOCLINE with a credentials field and several buttons. Initially, the credentials field will be empty and you'll see a "Generate Credentials" button.

Step 2: Generate Your API Credentials​

  1. Click the Generate Credentials button
What Happens Next

When you click this button, ILLiad will:

  • Connect to the National Library of Medicine's DOCLINE system
  • Register your ILLiad installation as an authorized application
  • Generate unique API credentials specifically for your library
  • Store these credentials securely in your ILLiad database
  1. Wait for the credential generation to complete

You'll see the credentials field populate with your new API credentials (displayed in a format like ClientId:ClientSecret). The field is read-only for security purposes.

  1. Verify the credentials were generated successfully

Once credentials are generated, you'll notice these important changes:

  • The credentials field now contains your API credentials
  • The "Generate Credentials" button has been replaced with a "Clear Credentials" button
  • A "Log In to DOCLINE" button is now available

Step 3: Authenticate with DOCLINE​

Now that you have credentials, you need to complete the authentication process:

  1. Click the Log In to DOCLINE button
Browser Window Opens

When you click this button, your default web browser will automatically open and navigate to the DOCLINE authentication page. Make sure popup blockers aren't preventing the authentication window from opening.

  1. Complete the OAuth authentication in your web browser

Your default web browser will open and navigate to the DOCLINE authentication page. You'll be prompted to:

  • Log in to your DOCLINE account using your NLM credentials
  • Authorize ILLiad to access your DOCLINE account on behalf of your library
  1. Complete the authorization process

Follow the prompts in your browser to complete the authorization. Once finished, you can close the browser window and return to the Customization Manager.

Have Your Credentials Ready

Keep your DOCLINE login credentials handy - you'll need them to complete the OAuth authorization process. These are the credentials you use to log in to the DOCLINE website, not the API credentials that were just generated.

Browser Requirements

Ensure your web browser can access the DOCLINE website and that any security software or popup blockers won't interfere with the authentication process.

Step 4: Confirm Successful Authentication​

Back in the Customization Manager, you should see that the authentication was successful:

  1. Verify the button has changed to Log Out of DOCLINE
Authentication Complete!

When you see the "Log Out of DOCLINE" button, it means:

  • Your credentials were successfully generated
  • The OAuth authentication process completed successfully
  • ILLiad is now authorized to communicate with DOCLINE on your behalf
  • The integration is ready to use

Verification​

To confirm that your DOCLINE API integration is working correctly:

Test the Connection​

  1. Check the authentication status - In the Customization Manager, you should see the "Log Out of DOCLINE" button, indicating an active, authenticated connection.
  1. Verify automatic token refresh - The system will automatically manage your authentication tokens behind the scenes. You don't need to manually refresh or renew them.

Expected Behavior After Setup​

Once setup is complete, you should expect:

What to Expect
  • Seamless integration - DOCLINE functionality will be available throughout ILLiad without requiring additional authentication steps
  • Automatic token management - The system handles authentication token renewal automatically
  • Persistent authentication - Your authentication will remain active until you explicitly log out or clear credentials

Troubleshooting Common Issues​

"WebApiUrl not found" Error​

Configuration Issue

If you see the error "WebApiUrl not found. Unable to authenticate with DOCLINE. Please check your configuration.":

  1. Check that your WebApiUrl customization key is properly configured (remember that it must not contain localhost or 127.0.0.1)
  2. Verify that the WebApiUrl is accessible from your ILLiad server
  3. Contact your system administrator if you're unsure about your WebApiUrl configuration

Credential Generation Fails​

Connection Problems

If credential generation doesn't work:

  1. Check firewall settings to ensure outbound HTTPS connections are allowed
  2. Try the generation process again after a few minutes

Browser Authentication Issues​

Authentication Problems

If the OAuth authentication process fails:

  1. Ensure your web browser can access the DOCLINE website
  2. Verify your DOCLINE account credentials are correct
  3. Check that popup blockers aren't preventing the authentication window from opening
  4. Try using a different web browser if issues persist
  5. For administrators: verify that the registry data value at Computer\HKEY_CLASSES_ROOT\x-atlas-illiad-docline\shell\open\command is the current location of CustomizationManager.exe.

Credential Invalidation Due to URL Change​

Automatic Reset

If you see an error about WebApiUrl having changed since credentials were generated:

  1. Your DOCLINE credentials will be automatically cleared
  2. Click "Generate Credentials" to create new credentials
  3. Complete the authentication process again

This occurs when the WebApiUrl customization key is modified after DOCLINE credentials have been generated, which invalidates the existing credentials for security reasons.

Next Steps​

Now that your DOCLINE API integration is set up and verified, you're ready to explore the full capabilities of the DOCLINE API integration:

Configure Docline field translations Configure Docline work form mappings Docline Borrowing request workflow Docline Lending request workflow

Start Using DOCLINE Features​

With the integration active, you can now:

  • Submit interlibrary loan requests through DOCLINE directly from ILLiad
  • Receive automatic status updates in ILLiad on your DOCLINE requests
  • Streamline your workflow between ILLiad and DOCLINE systems
Keep Your Setup Secure

Your API credentials are stored securely in your ILLiad database. Only use the "Clear Credentials" option if you need to reset your integration or if instructed to do so by technical support.

This documentation covers the basic setup process for DOCLINE API integration. For advanced configuration options and troubleshooting, please refer to the additional guides in this section.