Upgrade a custom collector


In order to make further development easier and to clean up old tech dept both lib-explorer and app-explorer have gotten new major releases. As such there are some breaking changes to the API’s.

This document explains what is needed to move from

  • lib-explorer-3.x.x to lib-explorer-4.x.x

  • app-explorer-1.5.x to app-explorer-2.x.x




lib-explorer-4.0.0 (and app-explorer-2.0.0) requires xpVersion=7.10.0


In build.gradle you have to bump lib-explorer version to 4.0.0.



Collectors are now supposed to provide their own documentTypes.



  • In lib-explorer-3.0.0/app-explorer-1.5.0 the register function would log a deprecation warning.

  • In lib-explorer-4.0.0/app-explorer-2.0.0 the register function will now throw a deprecation error.

The register function is deprecated and will throw an error!

Simply remove it from src/main/resources/main.ts


The unregister function is deprecated and will log a warning.

Simply remove it from src/main/resources/main.ts


React Component

The previous way to implement a Collector React Component was strongly hooked to semantic-ui-react-form, which had various complexity issues.

The new way uses React.forwardRef and React.useImperativeHandle in order for the (child) Collector component to provide callbacks that the (parent) Collection component can run when appropriate.

These are named afterReset and validate:

  • When the [Reset] button is clicked: the (parent) Collection component will reset it’s state, but whatever state is internal to the (child) Collector component needs to be handled inside it’s afterReset function.

  • When the [Save] button is clicked: the (parent) Collection component will validate it’s own input fields, but whatever inputs are provided by the (child) Collector component, should be handeled inside it’s own validate function.

These props are removed:

  • context object (sort of replaced by collectorConfig)

  • dispatch function (sort of replaced by setCollectorConfig)

  • isFirstRun ref (no longer needed)

  • path string (no longer needed)

These props are added:

  • collectorConfig (object)

  • setCollectorConfig (setState function)

  • setCollectorConfigErrorCount (setState function)

This prop is untouched:

  • explorer (object)



Task Descriptor XML

  • name has been replaced by collectionId.

  • language has been added.


collector.addSuccess() and collector.addError() no longer takes an uri parameter.



Since collectors now provide their own document-types, you also have to specify documentTypeName when persisting a document. Just make sure it matches a (lowercased and ascii folded) _name in the src/main/resources/documentTypes.json file.


Since uri is no longer a required parameter to persistDocument, there is no way for a collector instance to automatically figure out which document node to update. If you want to update a document, rather than creating endless new ones, you have to lookup and provide the document node _id in your collector task implementation.