The titleInstanceResolverService  (or TIRS) controls how resource data from external sources (added through external knowledge base integration, other system integrations or file upload). In mod-agreements v6.x.x a new title instance resolver service WorkSourceIdentifierTIRSImpl was added

From mod-agreements v6.x.x the application determines which titleInstanceResolverService is to be used through an environment variable: TIRS (before this release the title instance resolver service was hard coded in the source code).

The values available for TIRS can have the values:

  • IdFirst (Default and used is no TIRS environment variable is set)

  • WorkSourceIdentifier 

  • TitleFirst 




The Work Source Identifier title instance resolver service uses unique identifiers from an external source to identify works. Unlike the IdFirst and TitleFirst approaches, the WorkSourceIdentifier resolver will not try to ensure unique titles based on universally recognised identifiers (ISSN/ISBN) or title strings, but will rather trust the external source (e.g. GOKb) to provide accurate data.

This approach means that the external source is seen as the “source of truth” for all data it provides, and where incoming data from the source is different to the data currently stored in the local knowledge base, (KB) the local KB will be updated to match the incoming data. This means that the behaviour in the case of a single external source being used to populate the local KB is much more intuitive for the user, with the local KB data more accurately reflecting the external data (although due to differences in data modelling and rules for specific properties it is still possible that the local KB and external data source do not match completely).

However, this approach also means that if multiple sources are used to populate the Agreements local knowledgebase, with different ‘work source identifiers’, multiple works will be created for a title that would usually be seen as a single work. For example, if the title “Vivarium” (eISSN: 1568-5349) is loaded from GOKb (UUID: dd7e3be9-95d9-43b9-82c4-a88df10f5c13) and separately from a publisher derived KBART file (ID: viv, https://brill.com/fileasset/downloads_static/static_kbart_joba1.xlsx) then despite sharing an ISSN, these two sources would lead to the creation of two completely separate works in the local KB, one for each of the work source IDs. It is possible for the user loading data from a KBART file to avoid this duplication if they wish by adding the appropriate sourceIdentifier and sourceIdentifierNamespace information to the KBART file before upload (in this example, adding the GOKb UUIDs for each journal in a new sourceIdentifier column and the text GoKB in a new sourceIdentifierNamespace column)

The basic matching rules used by the local KB when using the Work Source Identifier resolver are simple (look for a matching work with the same source identifier in the same namespace), but the process is complicated by the potential historical use of other matching mechanisms which means that before mod-agreements v6.x.x no work source identifiers are present in the local KB.

The diagram below describes the logic used

TitleResolverServices - WorkSourceIdTIRS (Revised 7th Sept).png