GUID Support

Almost all EMu modules are capable of making use of GUIDs. Exceptions include:

• Audit Trails (eaudit)
• Condition Checks (econdition)
• Field Help (efieldhelp)
• Gazetteer (egazetteer)
• Internal Movements (einternal)
• Scheduled Operations (eoperations)
• Registry (eregistry)
• Statistics (estatistics)
• Valuations (evaluations)

where the use of GUIDs is thought to be unnecessary. For all GUID capable modules a GUIDs table displays on the Admin tab, allowing GUIDs to be added, edited, displayed, searched and included in reports:

The GUIDs table comprises three columns:

Field	Value
Preferred	Yes / No. Only one GUID in the GUIDs table can be marked as preferred.
Type	Lookup List of GUID types.
GUID	The GUID itself. URLs If the GUID is a URL, the Document View button beside the GUIDs grid is enabled: Click the button to launch the associated application to view the document.

The GUIDs table can hold multiple internally generated and externally generated identifiers.

The GUID fields are also available for querying in Search mode:

EMu can auto-generate GUID values on record save. Currently, GUIDs are auto-generated in compliance with UUID Version 4.

By default, GUID auto-generation is disabled for all modules.

In order to enable auto-generation of GUIDs in a module (or system-wide), the two GUID Registry entries must be specified:

• GUID Enabled Registry entry must be set to true

  -AND-

• A GUID Auto Types Registry entry must specify which GUID type(s) to generate for a module (or system-wide). Currently only UUID4 is supported.

On record save EMu checks whether the GUIDs table includes an entry for each type specified in a GUID Auto Types Registry entry, and generates a GUID for each type that is missing.

Currently EMu will auto-generate a UUID Version 4 GUID if one has not already been added to the record's GUIDs table.

• Organizations may need to consider their policy for deleting records that contain locally generated GUIDs. Once a record is assigned a GUID, that record should generally never be deleted. Our preference has always been that records are Retired (using Record Level Security settings) rather than deleted. A Retired record is hidden from all users except for those authorized to view it.
• The merging of records that contain GUIDs is another case to be considered. Organizations may want to retain the old GUID(s) from the merged record(s) within the GUIDs table on the master record (i.e. the one into which the merge took place).

Phase 3 of EMu GUID support will provide local resolution of GUIDs in formats that EMu recognizes.

Without a resolving service the GUID is simply an identifier providing little or no indication of the associated metadata. Some GUID formats, such as UUID, are completely opaque and provide no indication of the data associated with the GUID. Some industry bodies stress opaque identifiers are desirable and best practice, whereas others are more comfortable with non-opaque identifiers.

A GUID that has a resolving service to find associated metadata is also often described as an actionable GUID.

Refer to:

https://www.idigbio.org/sites/default/files/iDigBioGuidGuideForProviders_v1.pdf

A local resolver web service will:

receive web requests specifying a GUID;

search for the GUID in EMu modules;

and, if a match is found:

return metadata associated with the GUID.

The local resolver web service would query each EMu table containing GUIDs (determined by configuration settings). Alternatively, for improved query efficiency we may consider automatically populating a local table with all local GUIDs.

We stress that the mechanism is purely a web service – presentation logic will not be provided. Requests will be made of the web service using the http GET or POST protocols.

If we are engaged by an EMu customer to extend core EMu support to encompass other GUID schemes, then part of this work will be to extend the web resolver service to handle requests of the new GUID type.

To enable the local resolver web service, customers will need:

To install on a web server some lightweight IMu PHP code that accepts resolver web service requests and passes parameters through to the EMu server. This is simple setup and configuration on an existing web server. The web server and EMu server do not need to be the same host.

An IMu enabled EMu back-end environment that will be used to satisfy resolver web service requests and provide matching metadata (essentially this is enabling the imuserver background process in the EMu back-end).

To allocate one or more EMu licence slots for use by the resolver web service.

The resolver web service will provide functionality to:

Retrieve institution metadata describing the institution.

Search for a GUID and return matching status information and, if a match is found, return metadata about the match.

Metadata will be returned in XML format by default but can also be requested to be returned in JSON format.

Following are web service request examples using the http GET protocol and assuming the base web address of:

http://examplEMuseum.org/imu/guidresolver.php?

Retrieve host metadata:

request=info

Find a UUID returning data in XML:

request=find&guid=urn:uuid:84b567d5-dbbd-468a-be12-770747ebc397

request=find&

guid=urn:uuid:84b567d5-dbbd-468a-be12-770747ebc397&

format=xml

Find a UUID returning data in JSON:

request=find&

guid=urn:uuid:84b567d5-dbbd-468a-be12-770747ebc397&

format=json

Example of metadata from an info request returned in XML and JSON:

<?xml version="1.0"?>

<response>

<status>ok</status>

<id>YPMNH</id>

<museum>Yale Peabody Museum of Natural History</museum>

</response>

{

"status": "ok",

"id": "YPMNH",

"museum": "Yale Peabody Museum of Natural History"

}

Example of metadata from an unsuccessful find request returned in XML and JSON:

<?xml version="1.0"?>

<response>

<status>fail</status>

<guid>urn:uuid:84b567d5-dbbd-468a-be12-770747ebc397</guid>

</response>

{

"status": "fail",

"guid": "urn:uuid:84b567d5-dbbd-468a-be12-770747ebc397"

}

Example of metadata from successful find request returned in XML and JSON:

<?xml version="1.0"?>

<response>

<status>ok</status>

<guid>urn:uuid:84b567d5-dbbd-468a-be12-770747ebc397</guid>

<count>1</count>

<object>

<module>ecatalogue</module>

<irn>12345></irn>

<SummaryData>N 9837 Macropus rufus, South Eastern Australia</SummaryData>

</object>

</response>

{

"status": "ok",

"guid": "urn:uuid:84b567d5-dbbd-468a-be12-770747ebc397",

"count": 1,

"objects":

[

{

"module": "ecatalogue",

"irn": "12345",

"SummaryData": "N 9837 Macropus rufus, South Eastern Australia"

}

]

}