Skip to main content
ExLibris

Knowledge Assistant

BETA
 
  • Subscribe by RSS
  • Back
    SFX

     

    Ex Libris Knowledge Center
    1. Search site
      Go back to previous article
      1. Sign in
        • Sign in
        • Forgot password
    1. Home
    2. SFX
    3. Product Documentation
    4. Version 4.0
    5. SFX Advanced User's Guide
    6. Plug-In Feature

    Plug-In Feature

    1. Last updated
    2. Save as PDF
    3. Share
      1. Share
      2. Tweet
      3. Share
    1. Overview of the Plug-in Feature
    2. Implementation of the Plug-in Feature
    3. Plug-In Parallel Processing
      1. Overview
      2. Configuring Plug-in Parallel Processing
    4. Plug-in Program for Aleph
      1. Requirements
      2. Setup
      3. Summary Holdings Display
    5. Plug-in Program Based on Z39.50
      1. STEP 1: Provide Local Z39.50 Information in z3950_lookup.config
      2. STEP 2
      3. STEP 3
    6. Plug-in Program for SYNDETICS
    7. Plug-in Program for AIRway Project
    8. Plug-in Program for Ebsco
      1. General Information
      2. API_USER_ID Linking Parameter
      3. Plug-in Details
      4. Conditions for Using the Ebsco Plug-in
      5. Ebsco Plug-in Limitations

    Overview of the Plug-in Feature

    “Traditional” thresholds check whether conditions are met based on the content of the ContextObject (within SFX).
    The plug-in feature introduces a new type of threshold, one which determines if a condition was met based on a value returned by a program.
    For example, if you want a holding link for a particular book or journal to appear in the institution’s SFX menu screen only if the target catalog actually has a record for this particular book or journal, you must set a plug-in threshold for the getHolding target service.
    When a user sends an SFX request, SFX determines the services that are candidates for display in the SFX menu. Before displaying these services, however, SFX checks whether the different conditions—determined by the corresponding thresholds, including the plug-in threshold—are met.
    To determine whether the plug-in threshold is met, SFX runs the program specified in the plug-in threshold. This program checks whether the target catalog has a record for the particular journal/book contained in the SFX request. If the catalog has the book/journal, the program returns the value 1. Otherwise, the program returns the value 0.
    If the program returns 1, the condition in the plug-in threshold is met and the getHolding service is displayed in the SFX menu.
    If the program returns 0, the condition in the plug-in threshold is not met and the getHolding service is not displayed in the SFX menu.

    Implementation of the Plug-in Feature

    You can implement the plug-in feature.
    To implement a plug-in threshold:
    1. Write a stand-alone program that checks the status of a condition. The program should return 0 or 1.

    The location of the program should be:

    /exlibris/sfx_ver/sfx4_1/<instance>/lib/Parsers/PlugIn

    When writing a program, make sure all plug-in subroutines are called lookup.
    1. Set a plug-in threshold on the target or target service level. For example:

      $obj->plugIn(name of plug-in program)

      The following plug-in programs are available in SFX:

      • Aleph.pm – checks whether a specific journal /book exists in the Aleph catalog (version 14.2 or later)
      • z3950_lookup.pm – checks whether a specific journal/book exists in a catalog based on Z39.50
      • syndetics.pm – checks whether the book review for a particular book exists in Syndetics, based on an ISBN search

    Plug-In Parallel Processing

    The following section describes the Parallel Plug-In Processing feature.

    Overview

    The parallel plug-in processing feature aims to reduce the response time of the SFX Menu when multiple plug-ins are used by running several plug-ins in parallel instead of consecutively.
    This feature is optional. It will apply to those plug-ins enabled by the configuration file for parallel processing.
    In a simple scenario, where each target service has only one plug-in and there are no dependencies on data that was fetched by another plug-in, all plug-ins can run in parallel. In other cases, parallel processing is more complicated, for example in case of conflicts, where plug-ins use and update the same CTXO attribute, or in cases where the display logic excludes services against another and both use a plug-in.
    All settings are controlled by the following configuration file:
    /exlibris/sfx_ver/sfx4_1/<instance name>/config/parallel_plugin.config_
    The default number of plug-ins that can be run in parallel is 10. This number is configurable.
    There are two limitations to parallel processing:
    • If the same item has a threshold using several plug-ins, the plug-ins run sequentially.
    • If SFX handles multiple context objects – for example for several related objects in one request – the parallel processing is done for each object, but context objects are handled sequentially.

    Configuring Plug-in Parallel Processing

    The parallel_plugin.config_ configuration file contains sections for all plug-ins that are globally supported for this feature. You can add sections for local plug-ins. Plug-ins can be excluded from or included in the parallel processing.
    Plug-ins that are not listed in the configuration file are processed sequentially, after the plug-ins that are listed are processed. The same applies to plug-ins that are listed but disabled for parallel processing.
    The configuration file is used to control the following settings:
    Plug-In Parallel Processing Configuration Settings
    Parameter Description
    General
    enable_parallel_processing Possible Values: Y/N Enable/disable the parallel functionality across the system.
    max_plugin_excecutions_in_parallel Default Value: 10 The maximum number of plug-ins that can run in parallel.
    For each Plug-In
    Active Possible Values: Y/N Activate the plug-in module in parallel mode.
    insert_data_order The plug-in with the higher number for this parameter inserts its fields first. (This can be overwritten by later plug-in activity if conflicting data is fetched. This applies where several plug-ins populate the same field in the CTXO).
    multiple_running Possible Values: Y – the plug-in should run in parallel every time it runs N – the plug-in should run in parallel only the first time it runs. This may be desired if the same plug-in is used by several active target services, and the first request already returns all the data needed. In this case there is no point in running the plug-in several times in parallel. This applies for example to the EBSCO API plug-in.
    fields_from_ctx_obj Insert the names of the fields from the ctx object with a semicolon (;) separator between them, for example: sfx.aleph_title_index;fetchId. This is needed because at the end of the parallel processing the CTXOs of all the plug-ins that ran in parallel are merged into one CTXO. The fields you add to this parameter tell SFX what fields in the CTXO to populate.

    Plug-in Program for Aleph

    The plug-in program for Aleph uses the X-server functionality (available in Aleph version 14.2.4 and later). The program checks the Aleph catalog for the existence of a bibliographic record for a specific item. Based on the reply of the X-server, the plug-in program decides whether or not to show a link to the catalog in the SFX menu.
    Additionally, it is possible to configure the Aleph plug-in to retrieve Aleph summary holding statements to be displayed in the SFX menu.

    Requirements

    • For ALEPH 14.2.4 through 15, the Aleph license must include Aleph X-server details. Contact your Aleph support team for more information.
    • From Aleph 16.01 onwards, the following additional requirements exist:
      • A special/separate license (from the standard Aleph license) is required for using the X-server.
      • The existence of a staff user WWW-X (similar to Z39 Server).
      • server_ip_allowed with special X entries.

    Setup

    You can set up the plug-in program.
    To set up the Aleph plug-in program:
    1. Log on to your server as the instance user (for example, sfxlcl41).
    2. Navigate to the config directory by typing cn.
    3. Open the aleph_xserver_lookup.config file:

    vi aleph_xserver_lookup.config

    1. In this file, a number of configuration elements need to be entered. If you want the plug-in to check the catalog using ISSN or ISBN identifiers only, enter the URL, ISSN, ISBN index names, and the database name, as well as the URL for your catalog’s X-server. Additionally, specify the timeout value (in seconds).

    For example:

    Section "x_server"

       url         "http://www.university.edu:8991/X"

       issn_index "ISSN"

       isbn_index "ISBN"

       full_title_index   ""    #e.g. TIT

       word_title_index   ""   #e.g. WTI

       database    "USM01"

       timeout "5"

    EndSection

    1. If no ISSN or ISBN is available in the OpenURL, the plug-in program can be configured to check the catalog using title and author information found in the OpenURL.
    • Title search – To configure this option, set the title_option parameter to Y, as in the example below. In addition, provide the codes of the Aleph Title, Title word, and Author indexes. Indexes whose codes are not provided in the configuration file are not used for lookup.

    When searching using the title, a search is first performed on the Aleph full title index using the book or journal title. If this search retrieves zero results, a second search is performed on the Aleph title word index using a limited number of the longest words in the title. The number of words that are used for searching is defined by the num_of_words_for_search parameter. The default number is 4.

    If the book or journal title is longer than 10 words, it is not used for searching and a search is performed using the title’s longest words in the Aleph title word index.

    • Author search – To activate searching using author information, populate the author_index parameter of the configuration file with the Aleph author index code. In addition, if author information is included in the OpenURL and the type of object searched is a book, the first author’s last name will be searched in the Aleph author index.

    The following is an example of this section in the aleph_xserver_lookup.config file:

    Section "x_server"

       url         "http://www.university.edu:8991/X"

       issn_index "ISSN"

       isbn_index "ISBN"

        full_title_index   "TIT"        #e.g. TIT

       word_title_index   "WTI"        #e.g. WTI

       database    "USM01"

    EndSection

     

    Section "searching"

        title_option             "Y"      

        author_index             "WAU"      

        num_of_words_for_search "4"     

    EndSection

    1. Access the SFX Admin Center. In KBManager, locate the relevant target service (for example, LOCAL_CATALOGUE_EX_LIBRIS_ALEPH). In the target service, add the following threshold:

    $obj->plugIn('ALEPH')

    If a global threshold exists, it is recommended that you use the following:

    GLOBAL && $obj->plugIn('ALEPH')

    Use single quotation marks around the word ALEPH in the threshold field.
    1. Test the above by creating an OpenURL (use the OpenURL generator) for a journal or a book that exists in the Aleph OPAC. The link to the Aleph OPAC should appear in the SFX menu screen.

    Summary Holdings Display

    The Aleph plug-in can be configured to retrieve the Aleph summary holding statements for display in the SFX menu.
    holding_information.gif
    Holding Information
    For this feature to work, the following conditions must be met:
    • The Aleph OPAC needs to contain Summary holding statements—for example, in the 852 and 866 MARC fields.
    • The Aleph X-server needs to be configured to include these fields in the X-server present response. (More information about setting this up can be found in the Summary Holdings to Display in SFX: Aleph Side Configuration document located in KB item 16384-42722 How to Display Aleph Summary Holdings in the SFX Menu.)
    • In KBManager, a local target displayer should be added to the Aleph getHolding target service. The value should be set to: ALEPH::ALEPH.
    aleph-aleph.gif
    ALEPH::ALEPH
    To enable the summary holding statement display in the SFX menu, perform the following SFX configuration:
    1. Log on to your server as the instance user (for example, sfxlcl41).
    2. Navigate to the config directory by typing cn.
    3. Open the aleph_xserver_lookup.config file :

    vi aleph_xserver_lookup.config

    1. In the Display section, turn on the summary holding statement display option by setting display_summary_holdings to Y, and specify which MARC field/subfield(s) contain the summary holdings statement.

    In addition, using the cut_off_num parameter, you can determine the maximum number of holding statements to be shown in the SFX menu.

    For example:

    Section "display"

    marc_field                "852$a 866$a"     

    display_summary_holdings "Y"    

    cut_off_num               "10"   

    EndSection

    If there is more than one match for the OPAC Plug-in search, the following message is displayed:

    multiple_results_found.gif
    Multiple Results Found

    Plug-in Program Based on Z39.50

    This plug-in program uses Z39.50 to query the catalog and determine (based on the reply) whether or not to show a link to the catalog in the SFX menu screen. In addition, it is possible to configure the Z39.50 plug-in to retrieve summary holding statements to be displayed in the SFX menu.
    The display summary holdings feature does not work when there is more than one record available for the object.
    To start the program:

    STEP 1: Provide Local Z39.50 Information in z3950_lookup.config

    1. Log on as sfxlcl41.
    2. Enter cn.
    3. Enter vi z3950_lookup.config.
    4. Enter the Z39.50 server address, port, and database name.
    5. Specify whether the ISSN and ISBN query should be performed with or without dashes (where 0 means without dashes and 1 means with dashes).

    For example:

    Section "z3950_server"

    host            " 111.22.3.44"

    port            "210"

    base            "innopac"

    syntax          "USMARC"

    EndSection

     

    Section "dashes"

    isbn_dashes     "0"

    issn_dashes     "1"

    EndSection

    The following are additional configuration options:
    • If no ISSN or ISBN is available in the OpenURL, the plug-in program can be configured to check the catalog using title information found in the OpenURL. To configure this option, set the title_option parameter to Y, as in the example below.

    Section "searching"

    title_option     "Y"

    EndSection

    • The plug-in can be configured to retrieve the catalog summary holding statements for display in the SFX menu. For this feature to work, the following conditions must be met:
      • The OPAC needs to contain Summary holding statements—for example, in the 852 and 866 MARC fields.
      • The Target Displayer for the Aleph getHolding target service needs to be set to: Z3950::Z3950.

    To start using this option, you must configure the Display section of the z3950_lookup.config file. Set the value of display_summary_holdings to Y and specify which MARC field/subfield(s) contain the summary holdings statement.

    In addition, the following two parameters can be configured:

    • cut_off_num – This parameter determines the maximum number of holding statements to be shown in the SFX menu.
    • charset – This optional parameter defines the character set of the z39.50 response. When blank, the default latin1 is used. Use utf8 or another character set if the z39.50 response is sent in a different character set.

    The following is an example of the z3950_lookup.config, where both title and display of summary holding options are turned on:

    Section "z3950_server"

    host            " 111.22.3.44"

    port            "210"

    base            "innopac"

    timeout         "5"

    syntax          "USMARC"

    EndSection

     

    Section "dashes"

    isbn_dashes     "0"

    issn_dashes     "1"

    EndSection

     

    Section "searching"

    title_option     "Y"

    EndSection

     

    Section "display"

    display_summary_holdings "Y"          

    marc_field                "866$a 852$a"

    cut_off_num               "10"

    # optional parameter, can be "", "utf8", "latin1", etc.

    # defines how to interpret raw data received from catalog charset ""

    EndSection

    STEP 2

    In KBManager, add the following threshold in the target service level of the catalog target:

    $obj->plugIn('Z3950Lookup')

    If a global threshold exists, it is recommended that you use: GLOBAL && $obj->plugIn('Z3950Lookup')
    When the option to display summary holdings is turned on, the following target displayer is added in the target service level of the catalog target:
    Z3950-Z3950.gif
    Z3950::Z3950

    STEP 3

    Now that the plug-in feature is implemented, test it using an OpenURL of a journal or book that is available in the OPAC. Verify that the target shows up in the SFX menu screen.
    You can also test this by using an OpenURL of a journal or book that is not available in the OPAC. The catalog target should not show up in the SFX menu screen.
    If you encounter problems with the Z39.50 plug-in, it is recommended that you use the Z39.50 diagnostics tool (part of the server_admin_util) described in the SFX System Administration Guide.
    It is possible to configure the Z39.50 plug-in to retrieve summary holding statements to be displayed in the SFX menu. For more information, see Summary Holdings Display.

    Plug-in Program for SYNDETICS

    You do not have to make any changes to ensure that the SYNDETICS target uses the plug-in.
    In KBManager, note that the TARGET_SERVICE global threshold for the SYNDETICS target is:

    $obj->need('ISBN') && $obj->plugIn('syndetics')

    A configuration file exists in each local instance to determine the time-out – the number of seconds SFX waits for a response from Syndetics before it is considered non-responsive and a failed threshold check.
    The following is the location and file name:
    /exlibris/sfx_ver/sfx4_1/<instance>/config/syndetics.config_

    Section "general_configuration"

    #    set timeout value

           timeout "10"

    For more information about the Syndetics target, see the SFX Target Configuration Guide.

    Plug-in Program for AIRway Project

    This plug-in is to be used only with the AIRWAY_PROJECT target. When run, this plug-in sends a request to the AIRway Project server and checks whether it contains a record for the requested item. You do not need to make changes to the AIRway Project target in order to use the plug-in. The target service global threshold for the AIRway Project target is $obj->plugIn (AIRWAYLookup) in KBManager.

    Plug-in Program for Ebsco

    General Information

    SFX can use an API on EBSCOHOST to pre-check the availability of an item and retrieve the direct URL. This mechanism improves the availability indication in cases where not all articles in a particular issue are available on the EBSCO platform. SFX only displays the full text link if the API provides a positive response. In addition, the retrieved URL increases the accuracy of links, especially if there are more than one article published on the same page. SFX uses a plug-in to retrieve the response from EBSCO full text targets, based on information in the OpenURL. Specifically it helps with the following:
    • Metadata mismatches between OpenURL sources and Ebsco targets
    • Incomplete coverage in some Ebsco targets (only some articles are available in Ebsco in full text, not the complete issue)
    The use of the EBSCO API is optional. Refer to Plug-in Details for conditions and limitation of its use.
    To configure the Ebsco plug-in in your local SFX instance:
    1. Select On for the Ebsco targetURL API (SFX Admin Center > Configuration > Menu configuration > Proxy/CrossRef):
    ebsco_api.png
    Ebsco targetURL API
    1. Fill in the $$API_USER_ID linking parameter in the L/P area of the target service with the relevant value for your institution as received from the vendor. For more information about the $$API_USER_ID, see API_USER_ID Linking Parameter.
    This linking parameter needs to be requested from Ebsco and needs to be filled in before the Ebsco plug-in will work.
    1. If an institute specific activation exists for Ebsco target services, make sure that the threshold $obj‐>plugIn(Ebsco) exists also for the institute target service activation settings, as in the following image. For default activation, the plug‐in thresholds already exist for each Ebsco getFullTxt target service.
    ebsco_threshold.png
    Ebsco Threshold
    In SP 4.8.3, the default EBSCO plug‐in threshold $obj‐>plugIn(Ebsco) is automatically copied to all existing institute activation settings.
    1. Check the set-up using the following OpenURL (or an alternative article level OpenURL) to make sure that the linking to Ebsco targets in the SFX menu is working properly:

    <SFX base_url>?ctx_ver=Z39.88-2004&ctx_enc=info:ofi/enc:UTF-8&ctx_tim=2015-04-02--10:0948&url_ver=Z39.88-2004&url_ctx_fmt=infofi/fmt:kev:mtx:ctx&rft_val_fmt=info:ofi/fmt:kev:mtx:journal&rft.genre=article&rft.atitle=Effects%20of%20the%20Fitkids%20exercise%20therapy%20program%20on%20health-related%20fitness%2C%20walking%20capacity%2C%20and%20health-related%20quality%20of%20life&rft.jtitle=Physical%20Therapy&rft.aulast=Kotte&rft.auinit=E&rft.auinitm=M&rft.au=Kotte%2C%20Elles%20M.%20W.&rft.date=2014&rft.volume=94&rft.issue=9&rft.spage=1306&rft.epage=1318&rft.pages=1306-1318&rft.issn=00319023&rft.eissn=15386724&rft_id=info:doi/10.2522/ptj.20130315

    For more information on the limitations of the Ebsco plug-in, refer to Ebsco Plug-in Limitations.

    API_USER_ID Linking Parameter

    The API_USER_ID is an EBSCO authentication string that is customer specific and consists of the following three parts, separated by periods:
    <custid>.<groupid>.<profileid>
    • where custid is the EBSCOadmin customer id
    • where groupid is the Group ID in EBSCOhost where the database resides
    • where profileid is the Profile ID in EBSCOhost where the database resides
    Example: s123456.main.eit
    The structure of this authentication string is identical to the target information for Z39.50 connections.
    Contact your EBSCO representative if you do not already have this information.
    Note that Ex Libris uses the EBSCOhost API (EIT) to retrieve the list of databases per customer. Therefore, the API_USER_ID should be the same profile used with EIT, and your EIT profile should include all the full text databases.

    Plug-in Details

    The Ebsco plug-in consists of:
    • A plug-in program: lib/Parsers/PlugIn/Ebsco.pm

      This program does the following:

      • Sends requests to Ebsco API
      • Stores article level links returned by the Ebsco API in CTXO so it can be used by the Ebsco target parser
      • Translates the response from Ebsco API as either 0 or 1 for the plug-in threshold $obj->plugIn(Ebsco)
    • A plug-in threshold added to all full text Ebsco target services:

      $obj->plugIn(Ebsco)

    Conditions for Using the Ebsco Plug-in

    • The Ebsco plug-in is used for one or more Ebsco targets that are active in the SFX instance if the following conditions are met:
    • The SFX Menu configuration option Ebsco targetURL API is set to On in SFX Admin Center > Configuration > Menu configuration > Proxy/CrossRef.
    • The linking parameter $$API_USER_ID has been be filled in for the Ebsco targets. More information about the linking parameter can be found in the SFX Target and Alma E-Collection Configuration Guide. Note that this linking parameter can be defined for DEFAULT or can be institute specific, if institutes have been defined in the SFX instance.
    • The Ebsco target service has threshold $obj->plugIn(Ebsco). In the SFX KnowledgeBase, a global threshold $obj->plugIn(Ebsco) exists for all Ebsco getFullTxt target services for which the Ebsco API can be used.
    • The link in the SFX menu for Ebsco is an article level link, and the following metadata elements exist in the ContextObject:

    (rft.issn or rft.jtitle or rft.title) AND (rft.date and rft.volume and rft.issue) AND (rft.spage or rft.au or rft.atitle)

    If the Ebsco API request cannot be sent because conditions are not met, the regular Ebsco target linking is used.
    If the conditions are met, the Ebsco plug-in is used and an API request is sent to Ebsco.
    If a URL is returned by the Ebsco API, it is used as a targetURL. If no URL is returned (and no server errors or time-outs occur), the Ebsco target is not displayed in the SFX menu – the Ebsco PlugIn returns 0 and threshold fails.

    Ebsco Plug-in Limitations

    The following limitations apply to the Ebsco plug-in:
    • The Ebsco plug-in cannot be used selectively for individual EBSCO targets. If activated, it is used for all EBSCO targets.
    • The Ebsco plug‐in requires an Ebsco API user_id, stored in the SFX KnowledgeBase as a linking parameter (L/P). Only one Ebsco API user_id should be used per SFX instance. An exception to this rule are consortia sites using either model 2 (Using a Shared Instance) or model 3 (Single SFX Instance ‐ Multiple Institutions Sharing the Same Instance):
      • In model 3 (Single SFX Instance ‐ Multiple Institutions Sharing the Same Instance), each consortium member should be represented via an institute. One Ebsco API user ID should be defined per institute and the Ebsco targets should be activated per institute (not for default).
      • In model 2 (using a shared instance), the Ebsco API is invoked only in the instance responsible for creating the SFX menu (in most cases this will be the local instance, not the shared instance). For Ebsco targets activated in the shared instance, the Ebso API user ID should be added in the corresponding local instances (even if they are inactive).
    • If the Ebsco plug-in is used, only one Ebsco package of the same type is displayed in the SFX menu. For example, if you have a subscription to both Ebsco Academic search Complete and Ebsco Academic search Elite, only the Ebsco Academic search Elite target is displayed in the SFX menu. The link returned by the Ebsco API is to the one with the lowest database code alphabetically. In case of a subscription to different types of Ebsco packages (for example, Academic search Elite and Business Source Premier), this restriction does not apply. Both packages are displayed in the SFX menu.
    • For some Ebsco portfolios, the year information in different SFX sources varies, making it problematic to do a pre-check via the EBSCO API. For these portfolios, an exception was added to not use EBSCO API to check EBSCO targets before it is displayed in the SFX menu – based on a flag in the Object Portfolio: parse_param: exception=no_date.
    View article in the Exlibris Knowledge Center
    1. Back to top
      • DOI/CrossRef and NCBI Pubmed Setup
      • Institute Feature
    • Was this article helpful?

    Recommended articles

    1. Article type
      Topic
      Content Type
      Documentation
      Language
      English
      Product
      SFX
    2. Tags
      This page has no tags.
    1. © Copyright 2025 Ex Libris Knowledge Center
    2. Powered by CXone Expert ®
    • Term of Use
    • Privacy Policy
    • Contact Us
    2025 Ex Libris. All rights reserved