= Metadata editor suggestion =

|| '''Date''' || 2011/01/27 ||
|| '''Contact(s)''' || Francois ||
|| '''Last edited''' || ||
|| '''Status''' || complete ||
|| '''Assigned to release''' || 2.7.0 ||
|| '''Resources''' || Available ||
|| '''Ticket''' || #443 ||

== Overview ==

This proposal aims to '''improve metadata quality and help metadata editor make better metadata records'''. The main principle is to provide a set of suggestions based on metadata records analysis. A suggestion checks for one or more conditions and provide a mechanism to fix or improved the metadata record on a particular point.

Suggestions are defined on a schema basis and could be used on any kind of schema (iso19139 and others).

Suggestions analysis is made on a metadata record (not supposed to be applied by massive actions).

The suggestion mechanism is based on the 3 main action steps:
 1) (Optional) list registered processes for a schema

 2) Analyze a metadata record according to a set of suggestions|processes

 3) Trigger a particular process to apply the suggestion solutions (require metadata editor agreement)


Some examples of suggestions:
 a) Explode keywords containing comma (ie. ',').

 b) Check if scale denominator contains '1/' or '1:' or ' ' characters and remove them once triggered.

 c) Compute extent if keyword of type place are available based on thesaurus analysis. (see http://trac.osgeo.org/geonetwork/wiki/BoundingBoxFromKeyword)

 d) Compute extent if a WMS and layer name is set in the online resource section.

 e) Add CRS if a WMS and layer name is set in the online resource section.

 f) If a metadata record contains an INSPIRE theme, add an evaluation section.


b) is already available since GeoNetwork 2.5.x but the "compute extent" button is available even if no keyword of type pace exists. Suggestion analysis phase allows to only suggests actions relevant to current metadata record in the editing session.


Metadata editor suggestion should help end users to create better metadata and more up-to-date content.


This proposal implements the suggestion service and configuration mechanism. The user interface to interact with this service will be part of a futur proposal. A draft GUI is described here http://trac.osgeo.org/geonetwork/wiki/proposals/MetadataEditorSuggestion#Sampleclientinterfaceformetadatasuggestion.



=== Proposal Type ===
 * '''Type''': Editor improvement
 * '''App''': !GeoNetwork

=== Links ===
 * '''Documents''':
 * '''Email discussions''':
 * '''Other wiki discussions''':

=== Voting History ===
 * Vote proposed by Francois on 2011/02/02, result was
  * +1 Jeroen, Emmanuele, Simon, Francois
----

== Proposal == 
A service '''metadata.suggestion''' is added and allowed for metadata editors.

Service parameters :
 * id or uuid : Mandatory metadata identifier.
 * action : The operation to run. 
  * "list" provide a list of registered processes (default). 
  * "analyze" will analyze the metadata record agains each process and return a message if the process is applicable.
 * process : Optional process identifier to analyze the metadata against.

A process is an XSL transformation like the one used by Xsl or !MassiveXslProcessing features.


=== Configuration of suggestion for a schema ===
 * Add a suggest.xsl file in the schema directory.
 * Register a new process.
{{{
  <!-- Register here the list of process for the schema-->
  <xsl:include href="process/keywords-comma-exploder.xsl"/>
  <xsl:include href="process/scale-denominator-formatter.xsl"/>
  <xsl:include href="process/add-extent-from-geokeywords.xsl"/>
  <xsl:variable name="processes">
    <p>keywords-comma-exploder</p>
    <p>scale-denominator-formatter</p>
    <p>add-extent-from-geokeywords</p>
  </xsl:variable>
  
}}}

=== Process definition ===

==== Main configuration ====

In order to be visible in schema suggestion, the process :
 * MUST be registered in suggest.xsl file for the schema.
 * MUST provide 2 templates named list-{processIdentifier} and analyze-{processIdentifier} (the main match="@*|node()" is used for processing). This 2 templates are called by suggest.xsl according to the action of the metadata.suggestion service.

The list-* template simply return the process identifier. eg.
{{{
    <xsl:template name="list-keywords-comma-exploder">
      <suggestion process="keywords-comma-exploder"/>
    </xsl:template>
}}}

The analyze-* template check if the metadata record meets the condition of the processes and return useful information to the end user: 
 * a human readable message to be displayed (TODO : i18n)
 * an optional params element to return required parameters definition to run the process
eg.
{{{
<!-- Analyze the metadata record and return available suggestion
      for that process -->
    <xsl:template name="analyze-keywords-comma-exploder">
      <xsl:param name="root"/>
      <xsl:variable name="keywordWithComma"
        select="$root//gmd:keyword[contains(gco:CharacterString, ',')]"/><!-- TODO : PT_FreeText -->
      
      <xsl:if test="$keywordWithComma">
        <suggestion process="keywords-comma-exploder" category="keyword" target="keyword">
          <name xml:lang="en">Keyword field contains "," (ie. 
            <xsl:value-of select="string-join($keywordWithComma, ' and ')"/>
            ). Run this task to explode
                that keywords.</name>
        </suggestion>
      </xsl:if>
    </xsl:template>
}}}

A process could be available for Xsl or !MassiveXslProcessing and not be available for metadata editor suggestions.

==== Add parameters to your process ====

A process may require some parameters to run successfully. For example, the compute extent from keywords need geonetwork URL, the current language (only keyword in GUI language are searched for) and an extra parameter to replace or not the existing extent elements.

The parameters definition is the following:
{{{
<params>{
		gurl:{type:'string', defaultValue:'<xsl:value-of select="$gurl"/>'},
          	lang:{type:'string', defaultValue:'<xsl:value-of select="$lang"/>'},
	        replace:{type:'boolean', defaultValue:'<xsl:value-of select="$replace"/>'}
}</params>
}}}
(Basically JSON based in order to be easily processed by a JS client to generate a form).

"gurl" and "lang" could be considered as reserved parameter's name and the client should automatically set these value to geonetwork http url (eg. http://localhost:8080) and lang to the current GUI language (and optionnaly hide them from end user). Default values are provided using XSL param default values. eg.
{{{
  <xsl:param name="lang" select="'en'"/>
}}}

The client is in charge of settings correct labels for parameters.



=== Sample client interface for metadata suggestion ===

A suggestion manager could use '''metadata.suggestion?id=currentMetadataId&action=list''' to retrieve the list of processes registered for the metadata schema. It could then check if processes have suggestions for the metadata record using '''metadata.suggestion?id=currentMetadataId&action=analyze''' to analyze for all known processes or
using '''metadata.suggestion?id=currentMetadataId&action=analyze&process=keywords-comma-exploder''' to analyze for only one process.

The result could be displayed as a list of elements: 

[[Image(suggestion-manager.png)]]



Suggestion depends on metadata content, running it on our "Physiographic Map of North and Central Eurasia (Sample record, please remove!)" famous ISO19139 sample, the result is:

[[Image(suggestion-analysis.png)]]

Proccessing is made using metadata.processing service call while in edit mode.
After processing the metadata record is updated:

[[Image(suggestion-analysis-after-processing.png)]]


Metadata editor suggestion should be updated on any save action.

Optionnaly a process may require some extra parameter that need to be defined by end user:

[[Image(suggestion-processing-with-parameter.png)]]



=== Backwards Compatibility Issues ===
None.

=== New libraries added ===
None.


== Participants ==
 * Francois