Los metadatos de los ítems de DSpace pueden contener cualquier número de identificadores u otros valores de campo que participan en sistemas de información en red. Por ejemplo, un ítem puede incluir un DOI, que es un identificador controlado en el registro DOI. Existen muchos servicios web para aprovechar estos valores, usándolos como 'claves' para recuperar otros datos útiles. En el caso del DOI, por ejemplo, CrossRef proporciona muchos servicios que, dado un DOI, devolverán listas de autores, citas, etc. La tarea MetadataWebService permite el uso de dichos servicios y le permite obtener y (opcionalmente) agregar a los metadatos de DSpace los resultados de cualquier llamada a un servicio web de cualquier proveedor de servicios. Simplemente necesita describir qué servicio desea invocar y qué hacer con los resultados. Utilizando el código de tarea ([taskcode]), puede crear tantas tareas distintas como servicios desee llamar.
Cada descripción de tarea reside en un archivo de configuración en 'config/modules' (o en su local.cfg), y es un archivo de propiedades simple, como todos los demás archivos de configuración de DSpace (consulte Configuration Reference). Todas las configuraciones asociadas con una tarea determinada deben ir precedidas por el nombre de la tarea (tal como se asignó en config/modules/curate.cfg). Por ejemplo, si el nombre de la tarea es issn2pubname en curate.cfg, entonces todas las configuraciones deben comenzar con "issn2pubname.". Sus configuraciones pueden establecerse en su local.cfg, o en un nuevo archivo de configuración que se incluya (include = path/to/new/file.cfg) ya sea en su local.cfg o en el dspace.cfg. Consulte la Configuration Reference para ver ejemplos sobre cómo incluir archivos de configuración o modificar su local.cfg
Hay algunas propiedades obligatorias que debe configurar para cualquier servicio y, para ciertos servicios, algunas adicionales. Un ejemplo lo ilustrará mejor.
De ISSN a Nombre de la Editorial (ISSN to Publisher Name)
Supongamos que los ítems (que contienen artículos de revistas) incluyen 'dc.identifier.issn' cuando está disponible. También podríamos querer catalogar el nombre de la editorial (en 'dc.publisher'). El catalogador podría buscar el nombre a partir del ISSN en varias fuentes, pero esta 'investigación' es tediosa, costosa y propensa a errores. Hay muchos servicios web gratuitos y de buena calidad que pueden proporcionar esta información. Así que configuraremos una tarea MetadataWebService para llamar a un servicio y luego asignar automáticamente el nombre de la editorial a los metadatos del ítem. Como se indicó anteriormente, todo lo que se necesita es una descripción del servicio y qué hacer con los resultados. Cree un nuevo archivo en 'config/modules' llamado 'issn2pubname.cfg' (o lo que le resulte útil mnemotécnicamente). La primera propiedad en este archivo describe el servicio en una 'plantilla' (template). La plantilla es simplemente la URL para llamar al servicio web, con parámetros para sustituir valores. Aquí usaremos el servicio 'Sherpa/Romeo':
[taskcode].template=http://www.sherpa.ac.uk/romeo/api29.php?issn={dc.identifier.issn}
Cuando se ejecute la tarea, reemplazará '{dc.identifier.issn}' con el valor de ese campo en el ítem. Si el campo tiene múltiples valores, se utilizará el primero. Como servicio web, la llamada a la URL anterior devolverá un documento XML que contiene información (incluido el nombre de la editorial) sobre ese ISSN. Necesitamos describir qué hacer con este documento de respuesta, es decir, qué elementos queremos extraer y qué hacer con el contenido extraído. Esta descripción se codifica en una propiedad llamada mapa de datos ('datamap'). Utilizando el servicio de ejemplo anterior, podríamos tener:
[taskcode].datamap=//publisher/name=>dc.publisher,//romeocolor
Cada instrucción independiente está separada por una coma, por lo que hay 2 instrucciones en este mapa. La primera instrucción esencialmente dice: encuentre el elemento XML 'publisher name' y asigne el valor o valores de este elemento al campo 'dc.publisher' del ítem. La segunda instrucción dice: encuentre el elemento XML 'romeocolor', pero no lo agregue a los metadatos del ítem de DSpace, simplemente agréguelo a la cadena de resultado de la tarea (para que pueda ser visto por la persona que ejecuta la tarea). Puede tener tantas instrucciones como desee en un mapa de datos (datamap), lo que significa que puede recuperar múltiples valores de una sola llamada de servicio web. De manera un poco más formal, cada instrucción consta de una a tres partes. La primera parte (obligatoria) identifica los datos deseados en el documento de respuesta. La sintaxis (aquí '//publisher/name') es una expresión XPath 1.0, que es el lenguaje estándar para navegar por árboles XML. Si el valor se va a asignar a los metadatos del ítem de DSpace, entonces se necesitan otras 2 partes. La primera es el 'símbolo de mapeo' (aquí '=>'), que se utiliza para determinar cómo se debe realizar la asignación. Hay 3 posibles símbolos de mapeo, que se muestran aquí con sus significados:
'->' mapping will add to any existing value(s) in the item field '=>' mapping will replace any existing value(s) in the item field '~>' mapping will add *only if* item field has no existing value(s)
La tercera parte (aquí 'dc.publisher') es simplemente el nombre del campo de metadatos que se actualizará. Estas dos propiedades obligatorias (plantilla y mapa de datos) son suficientes para describir una gran cantidad de servicios web. Todo lo que se requiere para habilitar esta tarea es editar 'config/modules/curate.cfg' (o su local.cfg) y agregar 'issn2pubname' a la lista de tareas:
plugin.named.org.dspace.curate.CurationTask = org.dspace.ctask.general.MetadataWebService = issn2pubname plugin.named.org.dspace.curate.CurationTask = org.dspace.ctask.general.MetadataWebService = doi2crossref
Si desea que la tarea esté disponible en la interfaz de usuario de administración (Admin UI), consulte la documentación Invocación desde la interfaz de usuario de administración (arriba) sobre cómo configurarla. Las siguientes secciones describen algunas necesidades más especializadas utilizando la tarea MetadataWebService.
Encabezados HTTP (HTTP Headers)
Para algunos servicios web, el protocolo y otra información no se expresan en la URL del servicio, sino en los encabezados HTTP. Algunos ejemplos podrían ser los tokens de autenticación básica HTTP o las solicitudes para un tipo de medio (media type) de respuesta en particular. En estos casos, simplemente agregue una propiedad al archivo de configuración (nuestro ejemplo fue 'issn2pubname.cfg') que contenga todos los encabezados que desea transmitir al servicio:
[taskcode].headers=Accept: application/xml||Cache-Control: no-cache
Puede especificar cualquier número de encabezados, simplemente sepárelos con una 'doble barra vertical' ('||'). Asegúrese de que las comas en los valores estén escapadas (con barra invertida y coma, es decir, '\,').
Transformaciones (Transformations)
Un problema potencial con las sustituciones simples de parámetros realizadas por la tarea es que el servicio podría esperar un formato o expresión de un valor diferente a la forma en que se almacena en los metadatos del ítem. Por ejemplo, un servicio DOI podría esperar una notación simple de prefijo/sufijo ('10.000/12345'), mientras que el campo de metadatos de DSpace podría tener una representación URI ('http://dx.doi.org/10.000/12345'). En estos casos, se puede declarar una 'transformación' de un valor en la plantilla. Por ejemplo:
[taskcode].template=http://www.crossref.org/openurl/?id={doi:dc.relation.isversionof}&format=unixref
El 'doi:' antepuesto al nombre del campo de metadatos declara que el valor del campo 'dc.relation.isversionof' debe transformarse antes de la sustitución en la plantilla utilizando una transformación llamada 'doi'. La transformación se define en el mismo archivo de configuración de la siguiente manera:
[taskcode].transform.doi=match 10. trunc 60
Esto se leería como: excluya la cadena de valor hasta la aparición de '10.', luego trunque cualquier carácter después de la longitud 60. Puede definir tantas transformaciones como desee en cualquier tarea, aunque generalmente 1 o 2 serán suficientes. Las palabras clave 'match', 'trunc', etc., son nombres de 'funciones' que se aplicarán (en el orden en que se ingresaron). Las funciones disponibles actualmente son:
'cut' <number> = remove number leading characters 'trunc' <number> = remove trailing characters after number length 'match' <pattern> = start match at pattern 'text' <characters> = append literal characters (enclose in ' ' when whitespace needed)
Cuando se ejecuta la tarea, si la transformación resulta en un estado inválido (por ejemplo, cortar más caracteres de los que hay en el valor), se utilizará el valor sin transformar y la condición quedará registrada en el log. Las transformaciones también se pueden aplicar a los valores devueltos por el servicio web. Es decir, se puede aplicar la transformación a un valor antes de asignarlo a un campo de metadatos. En este caso, la declaración se produce en la propiedad de mapa de datos (datamap), no en la plantilla:
[taskcode].datamap=//publisher/name=>shorten:dc.publisher,//romeocolor
Aquí la tarea aplicará la transformación 'shorten' (que debe estar definida en el mismo archivo de configuración) antes de asignar el valor a 'dc.publisher'.
Uso Programático de la Cadena de Resultado
Normalmente, una cadena de resultado de tarea aparece en una ventana en la interfaz de usuario de administración después de haber sido invocada. La tarea MetadataWebService concatenará todos los valores declarados en la propiedad 'datamap' y los colocará en la cadena de resultado usando el formato: 'nombre:valor nombre:valor' para tantos valores como se hayan declarado. En el ejemplo anterior, obtendríamos una cadena como 'publisher: Nature romeocolor: green'. Este formato está bien para propósitos de visualización simples, pero puede resultar complicado si los valores contienen espacios. Puede reemplazar el separador de espacios utilizando una propiedad opcional 'separator' (colocada en el archivo de configuración, junto con todas las demás propiedades). Si utiliza:
[taskcode].separator=||
por ejemplo, resulta fácil analizar (parsear) la cadena de resultado y conservar los espacios en los valores. Este uso de la cadena de resultado puede ser muy poderoso, ya que esencialmente está creando un mapa de valores devueltos, que luego puede usarse para poblar una interfaz de usuario, o de cualquier otra manera que desee aprovechar los datos (impulsar un flujo de trabajo, etc.).
Límites y Uso
Se deben tener en cuenta algunas limitaciones. En primer lugar, dado que el análisis de la respuesta utiliza XPath, el servicio solo puede operar sobre documentos de respuesta XML (no JSON). La mayoría de los servicios web pueden proporcionar ambos, por lo que esto no debería ser un obstáculo importante. MetadataWebService se puede utilizar de muchas maneras: mostrando a un administrador un valor en la cadena de resultado en una interfaz de usuario, ejecutándose por lotes para actualizar un conjunto de ítems, etc. Una configuración excelente es integrar estas tareas en el flujo de trabajo de envío (submission workflow), de modo que se pueda realizar la 'catalogación automática' de muchos campos durante la ingesta.
