Custom XML Loader Documentation
Table of Contents
- Overview
- Mapping Through XSLT Transforms
- Built-In XSLT Transforms
- Creating Catalog Items with the Custom XML Loader
Overview
The Custom XML Loader enables InPort users to provide a translation mechanism for the load of any XML file format into InPort. This feature is intended for end users who have external metadata in an XML format and would like to import it as a new record into InPort.
At this time, the Custom XML Loader can only be used to create new records in InPort. If you have an interest in also updating existing records using the Custom XML Loader, please contact us.
Mapping through XSLT Transforms
XSLT stylesheets provide a standard method for transforming XML documents from one format to another. The Custom XML Loader makes use of user-supplied XSLT Transforms, which provides a means to convert from an external XML-based file format to InPort XML. After the custom XML format has been transformed into InPort XML, the transformed file is then loaded into the InPort XML Loader for processing.
The main advantage of this approach is in allowing support for a much greater variety of XML formats -- by leveraging the efforts and contributions of the InPort community as a whole to benefit the entire user base. In addition, by sharing XSLT Transforms across organizations, they can be downloaded, customized, and repurposed as new Transforms for specific organizational needs or situational workflows.
XSLT Transform Authoring Tips
Transforms used in InPort should use XSLT version 2 syntax, not version 1. In addition, InPort uses Saxon as its XSLT processor, and while this should be mostly compatible with other popular XSLT processors, there are slight differences in a handful of cases.
Ideally, transforms should be created and tested locally in your own environment before uploading to InPort. For security purposes, InPort cannot display detailed error information, so any syntax or XSLT usage errors will not be readily visible when using the transform on InPort.
Note also for custom XML uploads, the transform does not need to emit the
parent Catalog Item ID (<parent-cat-id>) where the new record will be
created.
This is automatically determined by the Custom Loader depending on what Catalog Item
the user performs the custom XML upload from.
Permissions and Approval Process
While any user can author an XSLT stylesheet on their own, only users with a Librarian role can upload a Transform into InPort. Please contact your Organization's Librarian to assist you with uploading your Transform if you do not have the necessary privileges.
In addition, once an XSLT Transform has been uploaded into the system, it must be reviewed and approved by an InPort Sys Admin before it is available as an option when using the Custom XML Loader. Please contact InPort Support when your XSLT Transform is ready for review.
Uploading an XSLT Transform to InPort
Only users with a Librarian role or higher can upload XSLT Transforms.
To upload an XSLT Transform, login and select XSLT Transforms under the Admin navigation menu. Click on the Add New Transform button to load a new Transform.
Please choose a descriptive name for the Transform, as this will appear for users who use the Custom XML Loader. Please also provide the Owner name (whether you, your group, or your organization, etc.) so that the Transform can be properly attributed. This will also appear when users select the Transform they wish to use.
XSLT Transform files must not exceed 1 MB in size, and must be in a valid XSLT format. The Transform can also be shared for use either only within a specific Organization, or with all Organizations across InPort.
Please note that the content of XSLT Transforms is visible to any Librarian in InPort, and by uploading the Transform, you are giving implicit permission for others in the InPort community to view, download, modify, distribute and re-use the Transform or any portion of it. Any code that may be considered proprietary should not be uploaded to InPort.
It is highly recommended to provide a link to documentation that describes the Transform and its mapping to InPort XML for the benefit of other users who may want to use the Transform.
Click the Add Transform button to load the Transform into InPort. Once it is successfully loaded, please contact InPort Support to have the Transform reviewed and approved. Unapproved Transforms will not appear as an option in the Custom XML Loader until they are approved.
Updating an XSLT Transform on InPort
If you would like to make changes to an existing Transform, login and go to the XSLT Transforms page under the Admin menu. Click on the XSLT Transform that you would like to update.
If you would like to update the Transform file itself, click on the Update File button. Please note that updating a Transform will reset it back to an Unapproved state, and it will need to be reviewed and re-approved to be used again in InPort. Please contact InPort Support once you have successfully updated your Transform file to have it reviewed.
Updating a Transform file will completely replace the previous one. InPort does not store past versions of Transforms, therefore it is highly recommended to keep backups of your files and/or store them in a version control system.
To update any information about the XSLT Transform (such as the Transform Name, Owner, Share Level, etc.), click on the Edit button under the Transform Information section. Modifying any of the Transform information will not affect its Approval status.
Built-In XSLT Transforms
In the initial implementation of the Custom XML Loader, the InPort Team has created a Transform to support the load of ISO 19115-2 XML files. This Transform is available for use by all Organizations in InPort.
Additional Transforms may be created in the future by the InPort Team for other popular formats, according to end users' requests. If there is a specific format that you would like to see implemented, or which would you feel would be of value to the wider InPort community, please contact InPort Support with your suggestion.
Creating Catalog Items with the Custom XML Loader
Custom XML files which have an appropriate XSLT Transform (to map from the format into InPort XML) can be direclty loaded into InPort. If you need to load a custom XML format into InPort which is not currently supported, you can work with your Librarian or InPort Support on what options may be available to have the format implemented.
To create a new Catalog Item from a supported custom XML format, first navigate to the parent Catalog Item under which you would like to create the new Item. On that Catalog Item record, go to the Item submenu and select Add Child Item From File.
On the next page, for the dropdown file labeled Create Child From, select the "Custom XML File" option.
Browse your computer to select the custom XML file for upload. Then select the appropriate XSLT Transform that will be applied to your custom XML file to transform it into InPort XML and load it into the system.
You can also optionally select a specific Workflow State that the new Catalog Item will be created as. In most cases, it is recommended to leave this to the default setting of Draft, so that the Catalog Item can be reviewed and modified before publication.
When you are finished, click the Create button to proceed.
The next page will show the results of the Custom XML Load, along with a detailed listing of any errors or warnings encountered. Keep in mind that the errors and warnings listings are in reference to the transformed InPort XML file, NOT the original Custom XML file that was loaded.
The File Load Details section contains a link to view the transformed InPort XML file for your convenience.