Guía del capturador de CONTENTdm
Esta guía proporciona instrucciones para trabajar con el CONTENTdm Catcher. Catcher es un servicio web en su sitio de CONTENTdm que le permite agregar y editar metadatos mediante un método estándar basado en XML.
Descripción general
CONTENTdm Catcher es un servicio web que admite solicitudes por lotes para agregar registros de solo metadatos a una colección de CONTENTdm, editar campos de metadatos existentes en cualquier registro o eliminar un registro. Catcher no altera la URL de referencia de los documentos que usted edita.
Catcher es un servicio web SOAP (Protocolo Simple de Acceso a Objetos), destinado al usuario avanzado de CONTENTdm, que procesa los datos de CONTENTdm proporcionados en un formato XML. La interacción con este servicio web se realiza a través de un script que envía datos en XML proporcionados por el usuario. La versión inicial de Catcher admitirá solicitudes para agregar o editar metadatos en los documentos y solicitudes para eliminar documentos individuales.
Catcher no le permite agregar o eliminar colecciones, solo editar los metadatos de los documentos. Utilice la Administración de CONTENTdm para crear y administrar colecciones, incluyendo la definición de campos.
El siguiente diagrama ilustra la interacción entre los componentes:
- Un script forma un mensaje que el servicio web comprende.
- Un script empaqueta los datos en un mensaje y transmite el mensaje al servicio web utilizando el protocolo SOAP.
- El servicio web Catcher interpreta la solicitud y lleva a cabo la acción solicitada.
- El servicio web proporciona una respuesta al script.
Pasos recomendados para usar Catcher:
- Revise todos los requisitos y las mejores prácticas detalladas en esta guía.
- Organice todos los metadatos de los documentos que se agregarán
Nota: al editar documentos, asegúrese de que todos los campos con vocabulario controlado contengan términos aprobados.
- Si edita o elimina documentos de colecciones, identifique el ID del documento.
- Revise los guiones de muestra para aprender a escribir su propio guion.
- Escriba un script para las transacciones que se deben enviar.
- Ejecute su script.
- Verifique el estado inicial de las transacciones. Se devolverá un acuse de recibo con un ID de transacción único por cada solicitud válida para editar, agregar o eliminar un documento. Las solicitudes no válidas devolverán un mensaje de error apropiado.
- Aprobar documentos (se requiere aprobación solo para agregar documentos) y construir el índice en la Administration de CONTENTdm.
Requisitos
Un script que envía datos en formato XML canónico y recibe mensajes SOAP. El script puede escribirse en el lenguaje de programación que usted elija.
Las credenciales de usuario enviadas en el script deben tener los permisos adecuados para las transacciones que usted necesita (agregar, editar o eliminar). Para obtener más información sobre las credenciales de usuario en su script, consulte los comentarios detallados del código en los scripts de muestra. Para obtener más información sobre los permisos de usuario de CONTENTdm, consulte Usuarios.
Si está agregando nuevos documentos a una nueva colección, asegúrese de haber completado la configuración de sus colecciones. Para más información, consulte Administración de colecciones.
Mejores prácticas
Conserve las respuestas de ID de transacción de cada script como referencia para la acción realizada con cada documento. El ID de transacción es útil para solucionar cualquier problema.
Antes de procesar cualquier transacción de script, puede ser útil ejecutar la llamada getCONTENTdmHTTPTransferVersion para verificar la autenticación con su servidor CONTENTdm. Si la cadena esperada no se devuelve tal como se describe en el script de muestra, esto debe resolverse antes de procesar las solicitudes reales de agregar, editar o eliminar.
Las ediciones no tendrán éxito a menos que todos los campos con vocabulario controlado sean conformes. Si un campo de registro contiene vocabulario controlado, se proporcionará un mensaje de advertencia y se procederá con la solicitud de transacción. Usted puede revisar los términos de vocabulario controlado para un campo de colección ejecutando la llamada getCONTENTdmControlledVocabTerms identificada en cada script de muestra. Si desea revisar los campos con vocabulario controlado, hay una llamada getCONTENTdmCollectionConfig que puede ejecutarse, la cual contiene el elemento de vocabulario de cada campo.
Guionización
El servicio web Catcher requiere que usted escriba un script que envíe datos en formato XML canónico y reciba mensajes SOAP. El script puede escribirse en cualquier lenguaje de programación.
Querrá verificar que su script refleje la versión actual de WSDL. La versión de WSDL se identifica en la URL de la siguiente manera:
https://worldcat.org/webservices/contentdm/catcher/6.0/CatcherService.wsdl
Antes de escribir su guion, querrá recopilar esta información:
- URL del servidor de CONTENTdm – Localice esto usando la URL de su sitio web de CONTENTdm agregando /utils/diagnostics a la URL de su sitio web de CONTENTdm para mostrarlo. Por ejemplo, el sitio de CONTENTdm Sandbox
- https://sandbox.contentdm.oclc.org/utils/diagnostics muestra esta URL del servidor CONTENTdm
- http://server10010.contentdm.oclc.org:8888
Nota: Catcher solo opera en http hoy. No hay soporte para https.
- Nombre de usuario: un nombre de usuario que tenga permisos para trabajar con la colección que desea manipular.
- Contraseña: la contraseña para el nombre de usuario.
- Código de licencia de CONTENTdm: búsquelo en Administración de CONTENTdm, en la pestaña Servidor bajo Acerca de.
Se recomienda que cada script contenga un tiempo de espera mínimo de 5 minutos. Al procesar lotes más grandes de registros, puede ser útil para la resolución de problemas que el script capture detalles adicionales de errores y que se reintente cualquier transacción fallida debido a problemas de conectividad o relacionados con SOAP.
Los siguientes formatos de fecha son compatibles con Catcher y deben usarse en su script: aaaa-mm-dd, aaaa-mm y aaaa.
Para obtener más información sobre cómo escribir su script, revise los scripts de muestra con comentarios detallados del código:
Visualización del estado de la transacción
Cada transacción en su script devuelve un acuse de recibo del servicio web Catcher, indicando el estado inicial del proceso solicitado (editar, agregar o eliminar). Se asigna un ID de transacción por transacción; un ID para cada documento en su script. Este estado inicial solo indica la acción realizada por el servicio web y no proporciona un estado del resultado final de la transacción.
El éxito o el fracaso final de cada transacción está disponible mediante un informe en la Administración de CONTENTdm. Se accede a este informe de actividad de transacciones de Catcher desde la administración de CONTENTdm haciendo clic en la pestaña Colecciones y luego en Informes de WorldShare. Este informe descargable muestra el ID de cada transacción, la fecha y hora de procesamiento, el estado final, el tipo de solicitud y una breve descripción.
Preguntas Frecuentes
P: ¿Cómo puedo saber si las solicitudes de mi script están siendo procesadas por el servicio web?
A: Recibirá inmediatamente una indicación del estado inicial de cada transacción solicitada para un proceso de edición, adición o eliminación. A cada solicitud válida también se le asignará un ID de transacción único. Aquí tiene un ejemplo de lo que verá reportado por el servicio web:
ID de transacción: dcscatchws01dxdu:248:14078347143541 Se ha iniciado la eliminación.
P: ¿Qué acción debo tomar una vez que mi script haya completado el procesamiento?
A: Revise la cola de aprobación en CONTENTdm Administration para los documentos agregados a través del servicio web Catcher. Apruebe los documentos y construya el índice. Los documentos editados o eliminados a través del servicio web se aprueban automáticamente, así que simplemente construya el índice para actualizar su colección. Las transacciones de edición con documentos que contengan términos de vocabulario controlado no aprobados no se aprobarán automáticamente. Estos documentos requerirán revisión en la Administración de CONTENTdm.
P: ¿Dónde encuentro el ID del documento?
A: El ID del documento es parte de la URL del documento. En el ejemplo de URL de Sandbox, el ID del documento es 244.
https://sandbox.contentdm.oclc.org/digital/collection/textiles/id/244
El valor del ID del documento debe reflejarse como el valor del campo dmrecord para un documento en su script. La opción de exportación en la Administración de CONTENTdm es una forma adicional de localizar el número de CONTENTdm de un documento. Para más información, consulte Exportar metadatos.
P: ¿Cuál es el tiempo de transacción relativo esperado para cada tipo de solicitud?
Una solicitud de adición será la más lenta de procesar y una solicitud de eliminación será la más rápida. Lo más probable es que una solicitud de edición sea de duración media a corta para procesarse.