├── CatalogLookup.nsi ├── CatalogLookup.xlam ├── LICENSE ├── README.md ├── customUI ├── customUI.xml └── images │ └── library.jpg ├── img ├── baseurl.jpg ├── dialog-data.jpg ├── dialog.jpg ├── example1.jpg ├── example2.jpg ├── example3.jpg ├── example4.jpg ├── example5.jpg ├── large-librarysymbol.jpg └── ribbon.jpg ├── libxml2x64.dll ├── libxml2x86.dll ├── libxsltx64.dll ├── libxsltx86.dll ├── src.vba ├── AdditionalFieldsDialog.frm ├── Catalog.vba ├── LookupDialog.frm ├── OtherSourcesDialog.frm ├── SearchingDialog.frm └── UserPassForm.frm ├── yaz5x64.dll └── yaz5x86.dll /CatalogLookup.nsi: -------------------------------------------------------------------------------- 1 | ; NSIS Excel Add-In Installer Script 2 | 3 | RequestExecutionLevel user 4 | !include MUI.nsh 5 | !include LogicLib.nsh 6 | 7 | ; General 8 | !define filename "CatalogLookup.xlam" 9 | !define yazdllx86 "yaz5x86.dll" 10 | !define yazdllx64 "yaz5x64.dll" 11 | !define yazdll "yaz5.dll" 12 | !define libxml2x86 "libxml2x86.dll" 13 | !define libxsltx86 "libxsltx86.dll" 14 | !define libxml2x64 "libxml2x64.dll" 15 | !define libxsltx64 "libxsltx64.dll" 16 | !define libxml2 "libxml2.dll" 17 | !define libxslt "libxslt.dll" 18 | !define displayname "Excel Local Catalog Lookup" 19 | 20 | Name "${displayname}" 21 | OutFile "CatalogLookupInstaller.exe" 22 | InstallDir "$APPDATA\${displayname}" 23 | InstallDirRegKey HKCU "Software\${displayname}" "InstallDir" ; 24 | 25 | !insertmacro MUI_PAGE_WELCOME 26 | !insertmacro MUI_PAGE_DIRECTORY 27 | !insertmacro MUI_PAGE_INSTFILES 28 | !insertmacro MUI_PAGE_FINISH 29 | 30 | !insertmacro MUI_UNPAGE_WELCOME 31 | !insertmacro MUI_UNPAGE_CONFIRM 32 | !insertmacro MUI_UNPAGE_INSTFILES 33 | !insertmacro MUI_UNPAGE_FINISH 34 | 35 | !insertmacro MUI_LANGUAGE "English" 36 | 37 | ; Interface Settings 38 | !define MUI_ABORTWARNING 39 | 40 | 41 | ;Prerequisites section 42 | 43 | Section "-Prerequisites" 44 | SectionEnd 45 | 46 | SetOverwrite On 47 | 48 | Var /GLOBAL xlVerReg 49 | Var /GLOBAL xlVerNo 50 | Var /GLOBAL i 51 | Var /GLOBAL keyname 52 | Var /GLOBAL keyname2 53 | Var /GLOBAL keyprefix 54 | Var /GLOBAL openpath 55 | Var /GLOBAL openname 56 | Var /GLOBAL removeold 57 | Var /GLOBAL namelen 58 | Var /GLOBAL lastblankkey 59 | 60 | ; Installer Section 61 | Section "-Install" 62 | SetOutPath $INSTDIR 63 | 64 | ClearErrors 65 | FileOpen $R0 $INSTDIR\tmp.dat w 66 | FileClose $R0 67 | Delete $INSTDIR\tmp.dat 68 | ${If} ${Errors} 69 | Abort "User does not have permission to write to the output directory." 70 | ${EndIf} 71 | 72 | ClearErrors 73 | FileOpen $R0 "$INSTDIR\${filename}" a 74 | FileClose $R0 75 | ${If} ${Errors} 76 | Abort "Excel is open. Please close Excel before trying to install." 77 | ${EndIf} 78 | 79 | ; Check Installed Excel Version 80 | ReadRegStr $xlVerReg HKCR "Excel.Application\CurVer" "" 81 | 82 | ${If} $xlVerReg == 'Excel.Application.12' ; Excel 2007 83 | StrCpy $xlVerNo "12.0" 84 | ${ElseIf} $xlVerReg == 'Excel.Application.14' ; Excel 2010 85 | StrCpy $xlVerNo "14.0" 86 | ${ElseIf} $xlVerReg == 'Excel.Application.15' ; Excel 2013 87 | StrCpy $xlVerNo "15.0" 88 | ${ElseIf} $xlVerReg == 'Excel.Application.16' ; Excel 2016 89 | StrCpy $xlVerNo "16.0" 90 | ${Else} 91 | Abort "An appropriate version of Excel is not installed. $\n${displayname} setup will be canceled." 92 | ${EndIf} 93 | 94 | 95 | StrCpy $removeold "false" 96 | StrLen $namelen "${filename}" 97 | IntOp $namelen $namelen * -1 98 | IntOp $namelen $namelen - 1 99 | StrCpy $i 0 100 | loop: 101 | EnumRegValue $keyname HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" $i 102 | StrCmp $keyname "" done 103 | StrCpy $keyprefix $keyname 4 104 | ${If} $keyprefix == "OPEN" 105 | ReadRegStr $openpath HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" $keyname 106 | StrCpy $openname $openpath "" $namelen 107 | StrCpy $openname $openname -1 108 | StrCpy $openpath $openpath $namelen 109 | StrCpy $openpath $openpath "" 1 110 | ${If} "$openname" == "${filename}" 111 | ${If} $removeold == "false" 112 | MessageBox MB_YESNO "This plugin is already installed. Replace existing version?" IDYES 0 IDNO abort 113 | StrCpy $removeold "true" 114 | ${EndIf} 115 | Delete "$openpath\x86\*" 116 | RMDir "$openpath\x86" 117 | Delete "$openpath\x64\*" 118 | RMDir "$openpath\x64" 119 | Delete "$openpath\*" 120 | RMDir "$openpath" 121 | DeleteRegValue HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" $keyname 122 | DeleteRegValue HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Add-in Manager" "$openpath\${filename}" 123 | 124 | EnumRegValue $keyname2 HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" $i 125 | ${If} $keyname == $keyname2 126 | ${Else} 127 | IntOp $i $i - 1 128 | ${EndIf} 129 | ${EndIf} 130 | ${EndIf} 131 | IntOp $i $i + 1 132 | Goto loop 133 | done: 134 | Goto writekeys 135 | abort: 136 | Abort 137 | 138 | writekeys: 139 | ; Find available "OPEN" key 140 | Var /GLOBAL keyvalue 141 | StrCpy $i "" 142 | loop2: 143 | ReadRegStr $keyvalue HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" "OPEN$i" 144 | ${If} $keyvalue == "" 145 | ; Available OPEN key found 146 | WriteRegStr HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" "OPEN$i" '"$INSTDIR\${filename}"' 147 | ${Else} 148 | IntOp $i $i + 1 149 | Goto loop2 150 | ${EndIf} 151 | 152 | ;Remove any other gaps 153 | StrCpy $i "" 154 | StrCpy $lastblankkey "" 155 | loop3: 156 | ReadRegStr $keyvalue HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" "OPEN$i" 157 | ${If} $keyvalue == "" 158 | ${If} $lastblankkey == "" 159 | StrCpy $lastblankkey "OPEN$i" 160 | ${EndIf} 161 | ${Else} 162 | ${If} $lastblankkey == "" 163 | ${Else} 164 | WriteRegStr HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" $lastblankkey $keyvalue 165 | DeleteRegValue HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" "OPEN$i" 166 | StrCpy $lastblankkey "OPEN$i" 167 | ${EndIf} 168 | ${EndIf} 169 | IntOp $i $i + 1 170 | ${If} $i < 1000 171 | Goto loop3 172 | ${EndIf} 173 | 174 | 175 | ; Write install data to registry 176 | WriteRegStr HKCU "Software\${displayname}" "InstallDir" $INSTDIR 177 | ; Install Directory 178 | WriteRegStr HKCU "Software\${displayname}" "ExcelCurVer" $xlVerNo 179 | ; Current Excel Version 180 | 181 | CreateDirectory $INSTDIR\x86 182 | CreateDirectory $INSTDIR\x64 183 | ; ADD FILES HERE 184 | File "${filename}" 185 | File "${yazdllx86}" 186 | Rename "${yazdllx86}" "x86\${yazdll}" 187 | File "${yazdllx64}" 188 | Rename "${yazdllx64}" "x64\${yazdll}" 189 | File "${libxml2x86}" 190 | Rename "${libxml2x86}" "x86\${libxml2}" 191 | File "${libxsltx86}" 192 | Rename "${libxsltx86}" "x86\${libxslt}" 193 | File "${libxml2x64}" 194 | Rename "${libxml2x64}" "x64\${libxml2}" 195 | File "${libxsltx64}" 196 | Rename "${libxsltx64}" "x64\${libxslt}" 197 | 198 | ; Write keys to uninstall 199 | WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${displayname}" "DisplayName" "${displayname}" 200 | WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${displayname}" "UninstallString" '"$INSTDIR\uninstall.exe"' 201 | WriteRegDWORD HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${displayname}" "NoModify" 1 202 | WriteRegDWORD HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${displayname}" "NoRepair" 1 203 | 204 | ; Create uninstaller 205 | WriteUninstaller "$INSTDIR\Uninstall.exe" 206 | SectionEnd 207 | 208 | 209 | ; Uninstaller Section 210 | Section "Uninstall" 211 | 212 | ; Find AddIn Manager Key and Delete 213 | ; AddIn Manager key name and location may have changed since installation depending on actions taken by user in AddIn Manager. 214 | ; Need to search for the target AddIn key and delete if found. 215 | ReadRegStr $xlVerNo HKCU "Software\${displayname}" "ExcelCurVer" 216 | 217 | StrLen $namelen "${filename}" 218 | IntOp $namelen $namelen * -1 219 | IntOp $namelen $namelen - 1 220 | 221 | StrCpy $i 0 222 | loop: 223 | EnumRegValue $keyname HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" $i 224 | StrCmp $keyname "" done 225 | StrCpy $keyprefix $keyname 4 226 | ${If} $keyprefix == "OPEN" 227 | ReadRegStr $openpath HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" $keyname 228 | StrCpy $openname $openpath "" $namelen 229 | StrCpy $openname $openname -1 230 | StrCpy $openpath $openpath $namelen 231 | StrCpy $openpath $openpath "" 1 232 | ${If} "$openname" == "${filename}" 233 | Delete "$openpath\x86\*" 234 | RMDir "$openpath\x86" 235 | Delete "$openpath\x64\*" 236 | RMDir "$openpath\x64" 237 | Delete "$openpath\*" 238 | RMDir "$openpath" 239 | DeleteRegValue HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" $keyname 240 | DeleteRegValue HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Add-in Manager" "$openpath\${filename}" 241 | 242 | EnumRegValue $keyname2 HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" $i 243 | ${If} $keyname == $keyname2 244 | ${Else} 245 | IntOp $i $i - 1 246 | ${EndIf} 247 | ${EndIf} 248 | ${EndIf} 249 | IntOp $i $i + 1 250 | Goto loop 251 | done: 252 | 253 | ;Remove any other gaps 254 | StrCpy $i "" 255 | StrCpy $lastblankkey "" 256 | loop3: 257 | ReadRegStr $keyvalue HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" "OPEN$i" 258 | ${If} $keyvalue == "" 259 | ${If} $lastblankkey == "" 260 | StrCpy $lastblankkey "OPEN$i" 261 | ${EndIf} 262 | ${Else} 263 | ${If} $lastblankkey == "" 264 | ${Else} 265 | WriteRegStr HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" $lastblankkey $keyvalue 266 | DeleteRegValue HKCU "Software\Microsoft\Office\$xlVerNo\Excel\Options" "OPEN$i" 267 | StrCpy $lastblankkey "OPEN$i" 268 | ${EndIf} 269 | ${EndIf} 270 | IntOp $i $i + 1 271 | ${If} $i < 1000 272 | Goto loop3 273 | ${EndIf} 274 | 275 | 276 | DeleteRegKey HKCU "Software\${displayname}" 277 | DeleteRegKey HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${displayname}" 278 | SectionEnd -------------------------------------------------------------------------------- /CatalogLookup.xlam: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pulibrary/ExcelAlmaLookup/d0af8d841cd22325ca015f5fec649056ddcfa593/CatalogLookup.xlam -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | ########################################################################## 2 | # Copyright 2024 Princeton University Library 3 | # Additional copyright may be held by others, as reflected in the commit log 4 | # 5 | # Licensed under the Apache License, Version 2.0 (the "License"); 6 | # you may not use this file except in compliance with the License. 7 | # You may obtain a copy of the License at 8 | # 9 | # http://www.apache.org/licenses/LICENSE-2.0 10 | # 11 | # Unless required by applicable law or agreed to in writing, software 12 | # distributed under the License is distributed on an "AS IS" BASIS, 13 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 | # See the License for the specific language governing permissions and 15 | # limitations under the License. 16 | # 17 | # This software includes the YAZ toolkit (Copyright © 1995-2018 Index Data), 18 | # which is distributed under the following license: 19 | # 20 | # https://www.indexdata.com/resources/licenses/ 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Excel Alma Lookup 2 | An Alma batch-search plugin designed to be used within Excel. When integrated with your local Alma instance, the tool can perform searches by keyword, call number, title, ISBN, ISSN, MMS ID and many other fields based on the spreadsheet data. Selected non-Alma catalogs can also be searched, such as WorldCat, Library of Congress, ReCAP, and BorrowDirect. 3 | 4 | **NEW!** We are interested in suggestions for what features to develop next for this tool. Please let us know your thoughts in the [discussion forum](https://github.com/pulibrary/ExcelAlmaLookup/discussions). 5 | 6 | ## System Requirements 7 | - Microsoft Windows version 7 or higher 8 | - Microsoft Excel version 2007 or higher 9 | 10 | ## Installation 11 | 12 | Download the installer here: 13 | 14 | CatalogLookupInstaller.exe 15 | 16 | Simply run the installer (and be sure to quit Excel before doing so). After the plugin is installed, a new tab “Library Tools” will appear in the Excel ribbon. This tab will contain a button labeled “Look Up in Catalog”. 17 | 18 | (Note: Depending on your computer's security settings, trying to run the installer may pop up a warning that "Windows protected Your PC". If you receive this warning, you can proceed with the installation by clicking "More info" and then "Run anyway".) 19 | 20 | 21 | 22 | The plugin will only be installed under the current user's profile. While it is not possible to automatically install the plugin for all users on a computer, you can specify a custom installation directory. If this directory is accessible to other users on the computer, then they can enable the plugin without having to download and install it themselves. To do so: 23 | 24 | 1. In Excel, go to the "File" tab, and click "Options" in the left sidebar. 25 | 2. In the options window, click "Add-ins" in the left sidebar. 26 | 3. On the bottom of the window, next to "Manage", select "Excel Add-Ins", and click "Go...". 27 | 4. In the dialog that appears, click "Browse...". Navigate to the installation directory, and select the file "CatalogLookup.xlam". Then click "OK". 28 | 5. Click "OK" again in the Add-ins dialog, and close the options window. The "Library Tools" tab and "Look up in Catalog" button should appear, as shown above. 29 | 30 | ## Configuration 31 | Your local Alma instance must have an "SRU Server Type Integration Profile" enabled. Many institutions already have this feature turned on in Alma. If yours does not, you can ask your catalog administrator to enable it, as described in the following documentation: 32 | 33 | https://knowledge.exlibrisgroup.com/Alma/Product_Documentation/010Alma_Online_Help_(English)/090Integrations_with_External_Systems/030Resource_Management/190SRU_SRW_Search 34 | 35 | In order to access certain holdings fields (such as location or call number), the "Add Availability" option must be enabled for the SRU profile. Also, in order to retrieve barcodes and other item-specific fields, "Holdings Options (ISO 20775)" must be set to "Active". However, even without these settings enabled, the tool can retrieve any bibliographic field (and search for many types of holdings and item-related fields, including barcodes). 36 | 37 | The first time you run the tool, you will need to enter your institution's "Base URL for Alma SRU". You can contact your catalog administrator to find out this URL. It typically has the form "https://[myinstitution].alma.exlibrisgroup.com/view/sru/[INSTITUTION_CODE]". For example, the screenshot below shows the Base URL for Princeton's catalog: 38 | 39 | 40 | 41 | After entering the URL, click “Add URL to List” to save the URL for future use. One can save multiple URLs and switch between them in order to search different catalogs. If multiple URLs are saved, these can be viewed in a drop-down menu by clicking the triangular button to the right of the URL. After selecting a URL, you can click “Remove URL from List” to remove it from the drop-down. 42 | 43 | To search a non-Alma catalog (such as WorldCat), click the "Non-Alma Sources" button. A list of available sources will appear. After selecting a source, it will appear in the drop-down menu along with your Alma URLs. 44 | 45 | If your SRU integration requires a username and password, you will be prompted for these. (These are likely different than the personal credentials you use to log into Alma. Check with your catalog administrator.) If searching WorldCat, you will be prompted to enter your authorization number and password. You can save these credentials by checking the "Remember these credentials" box in the login prompt, or delete the saved credentials by clicking the "Clear Credentials" button while the URL is selected. 46 | 47 | ## Setting Up the Query 48 | Open an Excel spreadsheet and highlight the cells containing the data you want to search for in Alma. You can highlight an entire column, or just specific cells, but all the values should be contained in the same column. After highlighting the desired cells, click the “Look Up in Local Catalog” button. The following dialog box will appear: 49 | 50 | 51 | 52 | Below is an explanation of the fields in this dialog: 53 | 54 | **Base URL for Alma SRU**: See the "Configuration" section above. 55 | 56 | **Select a range of cells to look up**: This field indicates which cells contain the values you want to search for. If you selected a range of cells before clicking the button, then this field will already contain the appropriate value. However, it is possible to select a new range of cells by clicking the button to the right of this field. Please note that hidden cells in the indicated range will not be included in the search. 57 | 58 | **Ignore First Row (Header)**: If checked, the first cell in the selected range will not be searched. You should check this if the first row is a header. 59 | 60 | **Generate header row from result types**: This option is available if the "Ignore First Row" option is checked. For each result column, the header row will be populated with the corresponding label from the "Result Types" list. 61 | 62 | **Validate and search equivalent ISBN/SNs**: If checked, and if “Field to search” is set to “ISBN” or “ISSN”, then each ISBN/SN will be validated. If invalid, the value "INVALID" will be output in the result column(s). For ISBNs, the search will be done on both the 10-digit and 13-digit forms, regardless of which form is found in the spreadsheet. 63 | 64 | **Include suppressed records**: If checked, then suppressed records will be included in the search results. 65 | 66 | **Leftmost result column**: The column that will be populated with the first result type. If more than one result type is selected, the others will be put in consecutive columns to the right of the first. By default, the first empty column to the right of the visible spreadsheet data is selected. Use the arrow buttons to select a different column. If the selected column contains data, it will be overwritten (except for hidden cells). Search results will be placed in the same rows as the corresponding search values. 67 | 68 | **Field to search**: This indicates what kind of values are in the selected cells (e.g. ISBN, ISSN, Call Number, Title, or MMS ID). If an ISBN search is done, then spaces, dashes and parenthetical comments (e.g. “(paperback)”) are removed from the value before searching. Currently, the title search does not strip stopwords or do anything else to “clean up” the titles before searching. Thus, title searching will not be as accurate as the other search types. Also, please note that the search term will be treated as a phrase and enclosed in quotes, even if it contains multiple words. 69 | 70 | Besides the search keys in the drop-down list, you can enter any search index supported by the local Alma instance. Clicking the “Additional Fields” button will display a full list of such keys. Selecting an index from this list will enter the appropriate code in “Field to Search”. Note that for non-Alma sources, only a limited number of search types are available, and the "Additional Fields" button is not enabled. 71 | 72 | **Result types**: The type of data to retrieve from the records and output in the spreadsheet. Result types can be specified in a number of different ways: 73 | - Selecting “True/False” will populate the result column with TRUE and FALSE values based on whether the search values were found in the catalog. 74 | - Other result types, such as call numbers and location codes, may be selected from the dropdown list. Result types prefixed with a single asterisk are taken from the availability fields. Those with a double asterisk are from the ISO 20775 Holdings data. Your catalog may require special configuration to retrieve these fields. See the "Configuration" section above for more details. Also, because of limitations of the SRU output, the results may not be predictable for holdings with more than 100 item records attached. 75 | - If the search key is a barcode, any item-level result type (those prefixed with a double asterisk) will be filtered to include only the item records corresponding to that barcode. For other search or result types, all matching fields in the retrieved bibliographic records are included. As noted above, this may not work as expected if a holdings has more than 100 items attached. 76 | - Besides the options in the menu, you can also retrieve any MARC field from the bibliographic record. To retrieve an entire MARC field, enter its 3-digit tag number (e.g. “245”). (For institutions that include availability information in their records, this can be retrieved using the “AVA”, “AVD” or “AVE” tags.) 77 | - By default, some text is removed from the field, such as indicators, subfield tags, and the contents of subfield 6 (linkage). To retain this information in the output, check the option "Include indicators, subfield codes, and linkage in results for full fields". 78 | - A subfield can be retrieved by appending “$” followed by the subfield code (e.g. “245$a”). 79 | - To retrieve the part of an 880 field corresponding to another field or subfield, append “-880” (e.g. “245-880” or “245-880$a”). 80 | - To retrieve a specific substring from a field, append "(X,Y)" where X is the starting position, and Y is the length. For example, 008(35,3) retrieves characters 35 through 37 of field 008 (aka the language code). Character positions are zero-based, (i.e. the first character is in position 0, the second in position 1, etc.). This is to conform with the MARC specifications for fixed fields. Characters can be extracted from the Leader field using "Leader(X,Y)" or "LDR(X,Y)". If Y is set to 0, then the result will include the entire remaining part of the field starting from position X. 81 | - To show only results containing specific text, append # followed by that text. For example “035$a#(OCoLC)” will only retrieve 035a fields containing the text “(OCoLC)” (i.e., OCLC numbers). 82 | - Multiple result types can be selected for output, in which case they will be placed in consecutive columns in the spreadsheet, starting with the one indicated in the “Leftmost result column” field. Use the “Add”, “Remove”, “Move Up” and “Move Down” button to edit or reorder the result types. 83 | - For some non-Alma sources, there are a limited number of result types available, and it is not possible enter a custom value in this field. However, some sources also include a "Holdings" result type in the drop-down, which will retrieve a list of holding institutions for the item in question. 84 | 85 | Note that this tool is designed for running queries on lists of specific titles and identifiers, rather than more general queries that might return a large number of results. Thus, to improve performance, a maximum of 25 records will be retrieved for each row. 86 | 87 | **Field Sets**: Sets of field tags can be saved so that they do not need to be entered manually each time the tool is run. After compiling a list of fields under “Result Types”, click the “New…” button to create and name a new set. The “Load” button will populate the “Result Types” list with the fields in an existing set. “Save” will update the fields in the selected set from the “Result types” list. “Delete” will delete the selected set. 88 | 89 | **Include indicators, subfield codes, and linkage in results for full fields**: If checked (and if a given result type is a full MARC field rather than a subfield), then values that are normally scrubbed out of the results are included. The indicators will appear at the beginning of the field (a blank indicator is represented by the underscore _ character). Each subfield will be prefixed by a dollar sign followed by the subfield code. Also, subfield 6 containing the linkage value will be included if it exists. Note that substrings of the full field can be specified as described above. For example, "245(0,2)" would extract the indicators (the first two characters) from field 245. 90 | 91 | ## Running the Query 92 | After selecting or confirming the range of cells to look up, the field to search, and the result type(s), click “OK” to begin the lookup process. You will see the tool populating the result column(s) with the retrieved values. Hidden rows will be skipped. If a record contains multiple instances of the desired result field/subfield (or, if a call number/location search is done and a record has multiple holdings/items), then all instances will be placed in the result cell, separated by “broken vertical bar” characters (¦). If multiple bibliographic records are retrieved by a single search value, the desired field from each record will be placed in the result cell, separated by solid vertical bars (|). 93 | 94 | A small dialog box will show the progress of the query. You can terminate it at any time by clicking the "Stop Searching" button. You do not have to keep the spreadsheet in the foreground while it is searching. However, you may find that Excel performs more slowly in general until the search is complete. 95 | 96 | ### Reporting Bugs and Making Suggestions 97 | 98 | You can use the [discussion forum](https://github.com/pulibrary/ExcelAlmaLookup/discussions) or open an [issue](https://github.com/pulibrary/ExcelAlmaLookup/issues) if you would like to request features, report bugs, or ask general questions. 99 | 100 | ### Troubleshooting/Known Issues 101 | - Some users have reported that WorldCat queries always return FALSE. If you experience this issue, please ask your IT department to configure your firewall to allow connections to zcat.oclc.org on port 210. 102 | 103 | ## Example 104 | This example illustrates a typical use case. The user starts with a title list containing ISBNs and romanized titles for a set of Chinese books. 105 | 106 | 107 | 108 | They would like to search the catalog to confirm which items are owned by their instituion, and retrieve additional data for those items. Since ISBNs are a more reliable search key than titles, the user highlights column A contianing the ISBNs, then clicks the "Look Up in Catalog" button in the "Library Tools" tab. This brings up the following dialog: 109 | 110 | 111 | 112 | The "Range of cells to lookup up" field already shows the cells that the user highlighted (in this case, the entire column A). So, it is not necessary to change this field. The user sets "Field to Search" to "ISBN". The leftmost result column is also already set to C, which is the first blank column to the right of the data. The user also sets 3 result types: 113 | - Call number - The asterisk indicates that this will be retrieved from the availability fields. (If the user wanted to retrieve the call number from a bibliographic field, they could enter a specific MARC field name, such as 050 or 084). 114 | - 035$a#(OCoLC) - This retrieves all instances of 035$a containing the text "(OCoLC)", i.e. OCLC numbers. 115 | - 245-880$a - This retrieves all instances of 880$a that are linked to the 245 field, i.e. the original-script version of the Chinese titles. 116 | 117 | The user then clicks OK. The screenshot below shows the resulting spreadsheet: 118 | 119 | 120 | 121 | For each row of the spreadsheet, the three data elements mentioned above are output in columns C, D, and E respectively. Since the user selected the option to generate column headers, these appear in the first row. Since the ISBN in row 9 was not found in the catalog, the value FALSE is output in each of these columns. 122 | 123 | The user is now interested in looking up the OCLC numbers that were just retrieved in order to check the WorldCat holdings for each record. They highlight column D, and click the "Look Up in Catalog" button again. 124 | 125 | 126 | 127 | This time, they use the "Non-Alma Sources" button to set the source to "source:worldcat". (If they have done this in the past, then it would already appear in the drop-down list of sources). They set "Field to Search" to "OCLC No." and "Result Types" to "WorldCat Holdings". (It is not necessary to click the "Add" button since there is only one result type.) Column F is automatically selected as the result column. 128 | 129 | When the user clicks the "OK" button, they will be prompted to enter their WorldCat authorization number and password (unless they have entered it before and selected the option to save the login). Then, the tool looks up each OCLC number in WorldCat, and populates column F with a list of holdings codes, separated by the broken bar character. 130 | 131 | 132 | 133 | Note that even though the OCLC numbers include the prefixes "(OCoLC)" and "ocn", these are stripped so that only the number is searched in WorldCat. 134 | -------------------------------------------------------------------------------- /customUI/customUI.xml: -------------------------------------------------------------------------------- 1 | 3 | 4 | 5 | 6 | 7 |