Importación y exportación de ítems mediante el formato de archivo simple (Simple Archive Format)

Importador y Exportador de Ítems

DSpace cuenta con un conjunto de herramientas de línea de comandos para importar y exportar ítems en lote, utilizando el Formato de Archivo Simple de DSpace (Simple Archive Format). Además de la funcionalidad que ofrecen, estas herramientas sirven como ejemplo para los usuarios que deseen implementar su propio importador de ítems.

Formato de Archivo Simple de DSpace

El concepto básico detrás del Formato de Archivo Simple de DSpace es crear un archivo estructurado como un directorio que contiene un subdirectorio por cada ítem. Cada subdirectorio de ítem incluye un archivo con los metadatos descriptivos del ítem, así como los archivos que lo componen.

archive_directory/
    item_000/
        dublin_core.xml         -- qualified Dublin Core metadata for metadata fields belonging to the 'dc' schema.
        metadata_[prefix].xml   -- metadata in another schema.  The prefix is the name of the schema as registered with the metadata registry.
        contents                -- text file containing one line per filename.
		collections				-- (Optional) text file that contains the handles of the collections the item will belong to. Each handle in a row.
								-- Collection in first line will be the owning collection.
		handle					-- contains the handle assigned/to be assigned to this resource
        relationships           -- (Optional) If importing Entities, you can specify one or more relationships to create on import
        file_1.doc              -- files to be added as bitstreams to the item.
        file_2.pdf
    item_001/
        dublin_core.xml
        contents
        file_1.png
        ...

dublin_core.xml o metadata_[prefix].xml

El archivo dublin_core.xml o metadata_[prefix].xml tiene el siguiente formato, donde cada elemento de metadatos tiene su propia entrada dentro del conjunto de etiquetas <dcvalue>. Actualmente, hay tres atributos disponibles en la etiqueta <dcvalue>:

• element - el elemento de Dublin Core
• qualifier - el calificador del elemento

• language - (opcional) código de idioma ISO para el elemento

  <dublin_core>
      <dcvalue element="title" qualifier="none">A Tale of Two Cities</dcvalue>
      <dcvalue element="date" qualifier="issued">1990</dcvalue>
      <dcvalue element="title" qualifier="alternative" language="fr">J'aime les Printemps</dcvalue>
  </dublin_core>
  

  (Nota el atributo de etiqueta de idioma opcional, que indica al sistema que el título opcional está en francés).

Al proporcionar URLs como valores para campos que contienen el símbolo de ampersand (&), los ampersands en dichas URLs deben codificarse como  &

Cada campo de metadatos utilizado debe estar registrado previamente en el registro de metadatos (metadata registry) de la instancia de DSpace. Consulta las secciones sobre el Registro de Metadatos y el Registro de Formatos de Bitstream Metadata and Bitstream Format Registries.

Archivo contents

El archivo contents simplemente enumera, una por línea, los nombres de archivo de los bitstreams. Consulta el siguiente ejemplo:

file_1.doc
file_2.pdf
license

Ten en cuenta que la license es opcional, y si deseas incluir una, puedes colocar el archivo en el directorio .../item_001/, por ejemplo.

El nombre del bitstream puede ir seguido, opcionalmente, de cualquiera de los siguientes elementos:

• \tbundle:BUNDLENAME
• \tpermissions:PERMISSIONS
• \tdescription:DESCRIPTION
• \tprimary:true

Donde '\t' representa el carácter de tabulación.

'BUNDLENAME' es el nombre del bundle al que debe añadirse el bitstream. Si no se especifica un bundle, los ítems se colocarán en el bundle predeterminado, ORIGINAL.

'PERMISSIONS' es un texto con el siguiente formato: -[r|w] 'nombre del grupo'

'DESCRIPTION' es un texto que describe el archivo.

Primary se utiliza para especificar el bitstream principal.

Para ítems con IIIF habilitado, el nombre del bitstream puede ir seguido, opcionalmente, de cualquiera de los siguientes elementos:

• \tiiif-label:IIIFLABEL
• \tiiif-toc:IIIFTOC
• \tiiif-width:IIIFWIDTH
• \tiiif-height:IIIFHEIGHT

Donde:

'IIIFLABEL' es la etiqueta que se utilizará para la imagen en el visor.

'IIIFTOC' es la etiqueta que se utilizará para una entrada en la tabla de contenido del visor.

'IIIFWIDTH' es el ancho de la imagen que se utilizará para el lienzo (canvas) IIIF.

'IIIFHEIGHT' es la altura de la imagen que se utilizará para el lienzo (canvas) IIIF.

Archivo relationships

El archivo opcional relationships enumera las relaciones de esta Entidad con otras Entidades (ya sea que existan en el sistema o que también estén incluidas en tu lote de importación SAF). Esto permite vincular entidades a otras nuevas o existentes durante la importación. Las entidades pueden vincularse a otras dentro de este mismo conjunto de importación haciendo referencia al nombre de su subcarpeta de importación. Dado que las relaciones solo pueden crearse entre Entidades, este archivo solo puede utilizarse al importar Configurable Entities.

Cada línea del archivo contiene una clave de tipo de relación y un identificador de ítem con el siguiente formato:

relation.<relation_key> <handle|uuid|folderName:import_item_folder|schema.element[.qualifier]:value>

El input_item_folder debe hacer referencia al nombre de la carpeta de otro ítem dentro de este lote de importación. Ejemplo:

relation.isAuthorOfPublication 5dace143-1238-4b4f-affb-ed559f9254bb
relation.isAuthorOfPublication 123456789/1123
relation.isOrgUnitOfPublication folderName:item_001
relation.isProjectOfPublication project.identifier.id:123
relation.isProjectOfPublication project.identifier.name:A Name with Spaces

Durante la importación inicial, los ítems nuevos se almacenan en un mapa utilizando como clave el nombre de la carpeta del ítem. Una vez completada la importación inicial, se realiza una segunda pasada que verifica si existe un archivo 'relationships' en cada carpeta y crea una relación del tipo especificado con el ítem indicado.

<dublin_core schema="dspace">
  <dcvalue element="entity" qualifier="type">Publication</dcvalue>
</dublin_core>

<dublin_core schema="relation">
  <dcvalue element="isAuthorOfPublication">5dace143-1238-4b4f-affb-ed559f9254bb</dcvalue>
</dublin_core>

Configuración de metadata_[prefix].xml para un Esquema Diferente

Es posible utilizar otros esquemas como EAD, VRA Core, etc. Asegúrate de haber definido el nuevo esquema en el Registro de Esquemas de Metadatos de DSpace.

1. Crea un archivo separado para el otro esquema con el nombre metadata_[prefix].xml, donde [prefix] se reemplaza con el prefijo del esquema.
2. Dentro del archivo XML, utiliza la misma sintaxis de Dublin Core, pero en el elemento <dublin_core> incluye el atributo schema=[prefix].

3. Aquí tienes un ejemplo para metadatos ETD, que estarían en el archivo metadata_etd.xml:

   <dublin_core schema="etd">
        <dcvalue element="degree" qualifier="department">Computer Science</dcvalue>
        <dcvalue element="degree" qualifier="level">Masters</dcvalue>
        <dcvalue element="degree" qualifier="grantor">Michigan Institute of Technology</dcvalue>
   </dublin_core>

Importación de Ítems

Antes de ejecutar el importador de ítems sobre ítems previamente exportados desde una instancia de DSpace, consulta primero la sección Transferencia de Ítems entre Instancias de DSpace.

‡ Estos son mutuamente excluyentes.

El importador de ítems permite importar en lote una cantidad ilimitada de ítems para una colección específica, utilizando un comando de línea de comandos (CLI) muy simple y sus respectivos 'argumentos'.

Agregar Ítems a una Colección desde un Directorio

Para agregar ítems a una colección, debes reunir la siguiente información:

• eperson
• ID de la colección (ya sea Handle —por ejemplo, 123456789/14— o UUID)
• Directorio de origen donde se encuentran los ítems
• Archivo de mapeo (mapfile). Como aún no tienes uno, debes decidir dónde se ubicará (por ejemplo, /Import/Col_14/mapfile)
  En la línea de comandos:

[dspace]/bin/dspace import --add --eperson=joe@user.com --collection=CollectionID --source=items_dir --mapfile=mapfile

o utilizando la forma corta:

[dspace]/bin/dspace import -a -e joe@user.com -c CollectionID -s items_dir -m mapfile

El comando anterior recorrerá los ítems del directorio de archivo, los importará y luego generará un archivo de mapeo que almacena la relación entre los directorios de ítems y sus handles. GUARDA ESTE ARCHIVO DE MAPEADO. Puedes utilizarlo para reemplazar o eliminar (deshacer la importación de) los ítems mapeados.

Prueba. Puedes agregar --validate (o -v) al comando para simular todo el proceso de importación sin realizar realmente la importación. Esto es extremadamente útil para verificar tus archivos de importación antes de ejecutar la importación real.

Agregar Ítems a una Colección desde un Archivo ZIP

Para agregar ítems a una colección, debes reunir la siguiente información:

• eperson
• ID de la colección (ya sea Handle —por ejemplo, 123456789/14— o ID de base de datos —por ejemplo, 2)
• Directorio de origen donde se encuentra el archivo zip que contiene los ítems
• Archivo zip
• Archivo de mapeo (mapfile). Como aún no tienes uno, debes decidir dónde se ubicará (por ejemplo, /Import/Col_14/mapfile)
  En la línea de comandos:

[dspace]/bin/dspace import --add --eperson=joe@user.com --collection=CollectionID --source=zipfile_dir --zip=filename.zip --mapfile=mapfile

o utilizando la forma abreviada:

[dspace]/bin/dspace import -a -e joe@user.com -c CollectionID -s zipfile_dir -z filename.zip -m mapfile

El comando anterior descomprimirá el archivo zip, recorrerá los ítems del directorio de archivo, los importará y luego generará un archivo de mapeo que almacena la relación entre los directorios de ítems y sus handles. GUARDA ESTE ARCHIVO DE MAPEADO. Puedes utilizarlo para reemplazar o eliminar (deshacer la importación de) los ítems mapeados.

Prueba. Puedes agregar --validate (o -v) al comando para simular todo el proceso de importación sin realizar realmente la importación. Esto es extremadamente útil para verificar tus archivos de importación antes de ejecutar la importación real.

Reemplazar Ítems en una Colección

Reemplazar ítems existentes es relativamente sencillo. ¿Recuerdas el archivo de mapeo que guardaste anteriormente? Ahora lo vas a utilizar. El comando (en forma abreviada):

[dspace]/bin/dspace import -r -e joe@user.com -c collectionID -s items_dir -m mapfile

Forma extendida:

[dspace]/bin/dspace import --replace --eperson=joe@user.com --collection=collectionID --source=items_dire --mapfile=mapfile

Si deseas reemplazar contenido utilizando un archivo zip, eso también es posible.  El comando es similar. Pero, en este caso, "-s" se refiere al directorio donde se encuentra el archivo zip, y "-z" indica el nombre del archivo zip:

[dspace]/bin/dspace import -r -e joe@user.com -c collectionID -s zipfile_dir -z filename.zip -m mapfile

Eliminar o Deshacer la Importación de Ítems en una Colección

Puedes deshacer la importación o eliminar ítems siempre que tengas el archivo de mapeo (mapfile). ¿Recuerdas el archivo de mapeo que guardaste anteriormente? El comando es (en forma abreviada):

[dspace]/bin/dspace import -e joe@user.com -d -m mapfile

En forma extendida:

[dspace]/bin/dspace import --eperson=joe@user.com --delete --mapfile mapfile

Otras Opciones

• Flujo de trabajo. El importador normalmente omite cualquier flujo de trabajo asignado a una colección. Pero si agregas el argumento --workflow (-w), los ítems importados pasarán por el sistema de flujo de trabajo.

• Plantillas. Si tienes plantillas con datos constantes y deseas aplicar esos datos durante la importación por lotes, agrega el argumento --template (-p).

• Reanudar. Si durante la importación ocurre un error y esta se interrumpe, puedes usar la opción --resume (-R) para reanudar la importación desde donde quedó una vez que hayas corregido el error.
  
  

• Especificar la colección propietaria por ítem desde la herramienta de administración por línea de comandos

  Si omites la opción -c (que normalmente es obligatoria), el ItemImporter buscará un archivo llamado "collections" en cada directorio de ítem. Este archivo debe contener una lista de colecciones, una por línea, especificadas ya sea por su handle o por su ID interna en la base de datos. Luego, el ItemImporter agregará el ítem a cada una de las colecciones especificadas. La colección propietaria será la que esté especificada en la primera línea del archivo collections.

  Si se especifica tanto la opción -c como el archivo collections en el directorio del ítem, el ItemImporter ignorará el archivo collections y colocará el ítem en la colección indicada mediante la línea de comandos.

  Dado que el archivo collections puede variar entre los distintos directorios de ítems, esto te brinda un control más detallado sobre el proceso de agregar ítems por lotes a diferentes colecciones.

Importación por Lotes desde la Interfaz de Usuario (UI)

La importación por lotes también puede realizarse a través de la interfaz de usuario del Administrador. Los pasos a seguir son:

A.  Preparar los datos

1. Los ítems, es decir, los metadatos y sus bitstreams, deben estar en el Formato de Archivo Simple descrito anteriormente en este capítulo. Por lo tanto, para cada ítem debe existir un directorio separado que contenga los archivos correspondientes a ese ítem específico.
2. Además, en cada directorio de ítem puede haber otro archivo que describa la colección o las colecciones a las que se añadirá ese ítem. El nombre de este archivo debe ser "collections" y es opcional. Tiene el siguiente formato:
   
   
   Cada línea contiene el handle de una colección. La colección en la primera línea es la colección propietaria, mientras que las demás son colecciones adicionales a las que debe pertenecer el ítem.
3. Comprime los directorios de ítems en un archivo ZIP. Ten en cuenta que debes comprimir directamente los directorios de ítems, y no solo el directorio que los contiene. Es decir, el archivo ZIP final debe contener directamente los directorios de ítems.
   
   

B.  Importar los ítems a través de la interfaz de usuario (UI)

1. Inicia sesión como Administrador.
2. En el menú lateral, selecciona "Importar" → "Importación por lotes (ZIP)"                                                      
   
   
3. Desde la página "Importar por lotes": 
   1. Selecciona la colección en la que deseas importar.
   2. Arrastra y suelta el archivo ZIP en el área de carga (o búscalo en tu sistema de archivos).
   3. Elige si deseas realizar solo una "Validación" o no. 
      1. Cuando está seleccionada, DSpace probará el proceso de importación por lotes, pero no se importará contenido. Esto te permite validar los resultados del proceso antes de realizar la importación real. 
      2. Cuando está desmarcada, DSpace ejecutará la importación por lotes.
   
   

4. Al hacer clic en "Proceder", se iniciará la importación por lotes. Esto creará un nuevo "Proceso" que comenzará la carga del lote.  Dependiendo del tamaño del lote, este proceso puede tardar un tiempo en completarse.  Puedes actualizar la página para ver el estado actual, o volver a la lista de procesos (menú "Procesos" en la barra lateral) para verificar su estado. Una vez que el proceso esté COMPLETADO, verás un registro de los resultados y un archivo de mapeo (mapfile), que puede usarse para realizar actualizaciones posteriores.

5. Todas las importaciones previas se listarán en el menú "Procesos", hasta que se elimine su entrada correspondiente. Una vez que estés satisfecho con la importación y no necesites consultar los registros ni el archivo de mapeo, podrías considerar eliminar esa entrada de proceso para liberar espacio de almacenamiento (ya que el archivo ZIP que subiste se conservará en DSpace hasta que se elimine el proceso). También se puede iniciar un script llamado "process-cleaner" desde la página de Procesos, el cual permite eliminar procesos antiguos de forma masiva.

Exportación de Ítems

El exportador de ítems puede exportar un solo ítem o una colección de ítems, y crea un archivo en el formato de archivo simple de DSpace mencionado anteriormente para cada ítem exportado. Los ítems se exportan en un orden secuencial, según se recuperan de la base de datos. Como resultado, los números secuenciales de los subdirectorios de ítems (item_000, item_001, etc.) no están relacionados con el handle ni con el ID del ítem en DSpace.

Exportar una Colección

El comando CLI para exportar los ítems de una colección es:

[dspace]/bin/dspace export --type=COLLECTION --id=collectionID_or_handle --dest=/path/to/destination --number=seq_num

Forma corta:

[dspace]/bin/dspace export -t COLLECTION -i collectionID_or_handle -d /path/to/destination -n seq_num

La palabra clave COLLECTION indica que deseas exportar una colección completa. El ID puede ser el ID de base de datos o el handle. El exportador comenzará a numerar los archivos simples con el número de secuencia que proporciones.

Exportar un Ítem Individual

Para exportar un solo ítem, usa la palabra clave ITEM y proporciona el ID del ítem como argumento:

[dspace]/bin/dspace export --type=ITEM --id=itemID_or_handle --dest=/path/to/destination --number=seq_num

Forma corta:

[dspace]/bin/dspace export -t ITEM -i itemID_or_handle -d /path/to/destination -n seq_num

Cada ítem exportado tendrá un archivo adicional en su directorio llamado "handle". Este contendrá el handle asignado al ítem, y será leído por el importador para que los ítems exportados e importados en otra máquina conserven el handle original del ítem.

El Argumento -m

Usar el argumento -m exportará el ítem o la colección y también realizará el paso de migración. Ejecutará el mismo proceso descrito en la siguiente sección Exchanging Content Between Repositories. Se recomienda leer esa sección en conjunto con el uso de esta opción.

El Argumento -x

Usar el argumento -x realizará una exportación estándar, excepto por los bitstreams, que no serán exportados. Si tienes un SAF completo sin bitstreams y cuentas con un archivo de bitstreams (que podría haber sido importado previamente en DSpace) ubicado en algún lugar cercano, puedes crear enlaces simbólicos (symlinks) desde los archivos originales hacia los directorios SAF y obtener así una colección exportada que prácticamente no ocupe espacio, pero que por lo demás sea idéntica a la colección exportada (es decir, que se pueda importar nuevamente en DSpace). En el caso de colecciones muy grandes, el modo -x podría ser considerablemente más rápido que una exportación completa.

Exportación por Lotes desde la Interfaz de Usuario (UI)

La exportación por lotes también puede realizarse a través de la interfaz de usuario del Administrador. El límite de tamaño de archivo para la carga por defecto es de 512 MB, y se configura en el archivo application.properties de Spring Boot.

Los pasos a seguir son:

1. Inicia sesión como Administrador.
2. En el menú lateral, selecciona "Importar" → "Exportación por lotes (ZIP)"
   
3. Desde la página "Importar por lotes":
   1. Selecciona la colección en la que deseas importar.
   2. Arrastra y suelta el archivo ZIP en el área de carga (o búscalo en tu sistema de archivos).
   3. Elige si deseas realizar solo una "Validación" o no.
      1. Cuando está seleccionada, DSpace probará el proceso de importación por lotes, pero no se importará contenido. Esto te permite validar los resultados del proceso antes de realizar la importación real.
      2. Cuando está desmarcada, DSpace ejecutará la importación por lotes.
   
   
4. Al hacer clic en "Exportar", se iniciará la exportación por lotes. Esto creará un nuevo "Proceso" que comenzará la exportación.  Dependiendo del tamaño de la exportación, este proceso puede tardar algún tiempo en completarse.  Puedes actualizar la página para ver el estado actual o volver a la lista de procesos (menú "Procesos" en la barra lateral) para verificar su estado. Una vez que el proceso esté COMPLETADO, verás un registro de los resultados y un archivo ZIP exportado que podrás descargar.
5. Todas las exportaciones anteriores se mostrarán en el menú "Procesos" hasta que se elimine su entrada correspondiente. Una vez que estés satisfecho con la exportación y hayas descargado el archivo ZIP, puedes optar por eliminar esa entrada de proceso para liberar espacio de almacenamiento (ya que el archivo ZIP exportado se conservará en DSpace hasta que el proceso sea eliminado). También puedes iniciar un script llamado "process-cleaner" desde la página de Procesos, que permite eliminar en bloque procesos antiguos.