• Working Draft

    • Importing mappings in DCB Admin

    Owned by Casey Henderson
    Last updated: Oct 17, 2024 by Jag Goraya
    4 min read

    Introduction

    Users of DCB Admin with sufficient permissions can now import mappings through DCB Admin. These mapping files must be in TSV or CSV format, and should be split into two types: reference value mappings and numeric range mappings.

    Reference value mappings

    Must have the following headers :

    • fromContext

      • The values under this header should be either “DCB” or the code of your Host LMS.

    • fromCategory

      • This corresponds to “Category” in DCB Admin.

    • fromValue

    • toContext

      • The values under this header should be either “DCB” or the code of your Host LMS.

    • toCategory

    • toValue

    All libraries have these mappings, and they have the following categories:

    • ItemType

    • patronType

    • Location

    Numeric range mappings

    Must have the following headers :

    • context

      • The values under this header should be either “DCB” or the code of your Host LMS.

    • domain

      • This corresponds to the category of the mappings

    • lowerBound

    • upperBound

    • targetValue

    • targetContext

    Only Sierra and Polaris libraries have these mappings, and they have the following categories:

    • ItemType

    • patronType

    You will also notice that DCB Admin has an “all” option when importing: this is for when you want to import all of your reference value mappings OR your numeric range mappings, regardless of category.

    What you’ll need (File guidelines)

    • Your mappings file. This must be in CSV or TSV format, and must only contain reference value mappings or numeric range mappings.

      • Please check this file before you upload it to ensure the contents are what you expect.

      • The maximum file size is 1MB.

    • The code of the Host LMS you are uploading mappings for.

    • A user account with a sufficient role: ADMIN or CONSORTIUM_ADMIN.

    • A backup of any existing mappings - please ensure you have completed this before proceeding with the import. You can do this by going to either the numeric range or reference value mappings page, clicking export, and then clicking “Export as CSV” or “Export as TSV”.

    Step by step

    1. Navigate to DCB Admin, and ensure you are logged in as a user with the required role (either ADMIN or CONSORTIUM_ADMIN).

    2. Navigate to the “Mappings” page, and then “Numeric range mappings” or “Reference value mappings”, depending on the type of mappings file you wish to upload.

    3. Click the “Import” button. You will see a modal for importing mappings.

    4. Select a category and Host LMS from their respective drop-down menus, and then choose your file.

    5. Click “Import mappings”.

      1. If there are no existing mappings for your chosen Host LMS and category, the import will begin.

      2. However, if mappings already exist for your chosen Host LMS and category, you will see a subsequent screen warning you that <X> mappings already exist.

    If you haven’t already made a backup of your existing mappings, please do this now, as once you click ‘replace’ any existing mappings will be marked as deleted.

    If you’re happy to proceed, click “Replace mappings”, and the import will start.

    1. Assuming you have provided a valid file, the import will complete, and your mappings will now be in DCB.

    Common errors and situations

    CSV/TSV headers do not match the expected headers

    This error occurs because the headers of the CSV/TSV file do not match the headers DCB expects. If you see this error, please check the headers of your file against the ones on this page and ensure that they match.

    You will also get this error if you try and import a file of reference value mappings via the numeric range mapping import, or vice versa.

    The context does not match the Host LMS code you supplied. Please check your file and try again

    This error occurs when the Host LMS code you have selected in DCB Admin does not match the one in your mappings file. Please check that the entries under the fromContext or toContext headers (for reference value mappings) or domain header (for numeric range mappings) are either “DCB” or the Host LMS code you have selected.

    Mappings could not be uploaded

    Please refresh the page if you see this error: this normally occurs when authentication has failed for some reason. If this error persists, please log out and in again.

    My import has succeeded, but DCB Admin says that “X” mappings were ignored?

    This happens when you upload a file containing all of your reference value / numeric range mappings, but select one of the sub-categories (i.e. “ItemType”). DCB automatically scans your file to detect the ItemType mappings you want to import, and ensures no other mappings are imported other than the ones you want.

    “Ignored” mappings are just the ones that don’t match the category you selected. DCB Admin tells you about these just in case you’re seeing less mappings imported than you expected: if you’ve got loads of ‘ignored’ mappings, you likely selected the wrong category. Not to worry, though - you can run the import again with the right category and get back on track.

    How do I backup my mappings?

    You can backup your mappings through DCB Admin. Simply go to either the “reference value mappings” or “numeric range mappings” page, click “export” on the grid, and then select either “Export as CSV” or “Export as TSV”.

    You can narrow down what is included in this backup by using the standard grid filters - for example, filter by “fromContext” and “toContext” to limit the mappings backup to a certain Host LMS, and filter by “category” to limit the backup to a certain category of mapping.

     

     

    Operated as a Community Resource by the Open Library Foundation