Spanish translation of the User Guide

Esta guía de usuario cubre el uso de la interfaz web de CKAN para organizar, publicar y encontrar datos. CKAN también cuenta con una robusta API (del inglés Application Programming Interface), que facilita el desarrollo de extensiones y enlaces con otros sistemas informáticos. Para mayor información revisa la documentación de la API.

Cierta funcionalidad de la interfaz web relacionada con la administración del sitio está disponible solamente para usuarios con rol de administradores del sistema, y se encuentran documentados en una guía por separado.

CKAN es una herramienta para publicar portales de datos abiertos. Se puede comparar con sistemas de gestión de contenido (CMS, del inglés Content management system) como WordPress, pero con el enfoque en datos, en lugar de páginas y publicaciones de blog. En pocas palabras, permite administrar y publicar colecciones de datos. CKAN es usado por gobiernos locales y nacionales, institutos de investigación, y otras organizaciones que recopilan datos.

Una vez que los datos son publicados, los usuarios pueden explorar y encontrar los datos que necesitan, e inclusive pre-visualizarlos en mapas, gráficas y tablas, independientemente de si sean desarrolladores, periodistas, investigadores, organizaciones de la sociedad civil, ciudadanos, o tu propio equipo.

En CKAN los datos son publicados en unidades llamadas “datasets” o conjuntos de datos, p. ej. las estadísticas de crimen en una región, los montos de gasto de un departamento o agencia de gobierno, o lecturas de temperatura de diferentes estaciones meteorológicas. Cuando los usuarios busquen datos los resultados serán estos datasets.

Un dataset contiene principalmente dos elementos:

• Metadatos o información acerca de los datos, p. ej. el título, el publicador, la fecha, los formatos disponibles, licencia de uso, etc.
• Recursos que contienen los datos. Un recurso puede ser un archivo de cualquier formato, como CSV, hojas de cálculo de Excel, XML, PDF, imágenes, datos enlazados (Linked Data en inglés) en formato RDF, etc. CKAN puede almacenar el recurso internamente o simplemente como un enlace a otra parte. Un dataset puede contener cualquier número de recursos, p. ej. diversos recursos pueden contener datos para diferentes años, o contener los mismos pero en diferentes formatos.

Los usuarios de CKAN pueden registrar cuentas y entrar al sistema. Comúnmente (dependiendo de la configuración del sitio), el registro no es necesario para buscar y descargar datos, pero sí es requisito para las tareas de publicación, es decir, con los permisos apropiados un usuario puede crear y administrar datasets.

Generalmente, cada dataset es publicado por una Organización, y una instancia de CKAN puede tener cualquier número de organizaciones registradas. Por ejemplo, si CKAN es utilizado como portal de datos de un gobierno nacional, las organizaciones podrían ser las diferentes dependencias, departamentos o agencias de dicho gobierno. Estas organizaciones pueden definir su flujo y mecanismos de autorización para administrar su propio proceso de publicación.

Los administradores de una organización pueden sumar usuarios a su organización con diferentes roles, dependiendo del nivel de autorización requerida, y de esta manera los usuarios pueden crear datasets bajo dicha organización.

Normalmente los datasets no pueden ser creados fuera de una organización, sin embargo, es posible configurar CKAN para autorizar el manejo de datasets fuera de una organización y de esta manera permitir la edición a cualquier usuario registrado en el sistema, creando un portal de datos que sigue la filosofía Wiki.

Esta guía cubre la funcionalidad principal de la interfaz de usuario, pero es posible que en diferentes configuraciones de CKAN algunas de estas funcionalidades no se encuentren disponibles o sean diferentes. Por ejemplo, en una instancia oficial de CKAN, el administrador del sitio podría deshabilitar la creación de organizaciones vía la interfaz de usuario. Todas las funcionalidades descritas se puden probar en http://demo.ckan.org.

El registro es necesario para la mayoría de las funciones de publicación y personalización, como seguir la actividad de datasets, pero no es requisito para buscar o descargar datos.

Para crear un identificador de usuario, utiliza el enlace "Registro" en la parte superior de cualquier página. CKAN pedirá la siguiente información:

• Nombre de usuario: selecciona un nombre utilizando sólo letras, números y caracteres '-' y '_', p. ej. "rodowi" o "rod_1337".
• Nombre completo: que será mostrado en tu perfil de usuario.
• Dirección de correo electrónico: que no será visible a otros usuarios.
• Contraseña: ingresa la misma contraseña en el campo "Confirmar".

Si existe problema con algún campo, CKAN te notificará y permitirá corregirlo. Cuando todos los campos son completados correctamente, CKAN crea una cuenta de usuario y automáticamente ingresa al sistema.

Es perfectamente válido tener más de un usuario ligado a una misma cuenta de correo electrónico. Por esta razón, selecciona un nombre de usuario que puedas recordar, ya que será necesario para ingresar al sistema.

Es probable que para agregar y editar datasets necesites ser miembro de una Organización. Revisa la sección "Agregar una organización" para mayor información. En demo.ckan.org puedes agregar un dataset sin ser miembro de una organización, con la desventaja de que se pierde cierta funcionalidad.

Paso 1. Puedes ingresar a la vista de "Crear Conjunto de datos" de dos maneras.

1. Selecciona la liga "Conjuntos de datos" en la parte superior de cualquier página. Luego selecciona la liga "Añade un conjunto de datos" que se encuentra arriba de la barra de búsqueda.
2. Alternativamente, selecciona el enlace "Organizaciones" en la parte superior de una página. Selecciona la organización por la cual se publicará el dataset. Si eres miembro de la organización, ahora puedes seleccionar el botón "Añade un conjunto de datos" arriba de la barra de búsqueda.

Paso 2. CKAN pedirá la siguiente información sobre los datos.

• Título: este título será único a lo largo del sitio, sugerimos ser breve pero específico. P. ej. "Densidad poblacional de México por región" es preferible que "Datos de población".
• Descripción: en este espacio se puede agregar una explicación más completa sobre el dataset, incluyendo información que el usuario necesite al usar los datos, como el origen de éstos.
• Etiquetas: aquí se definen etiquetas que ayudarán a los usuarios a encontrar los datos y enlazarlos con otros relacionados. Ejemplos podrían ser "fondos", "desastres naturales", "Acapulco". Presiona la tecla de retorno entre etiquetas. Si ingresas una etiqueta incorrecta, puedes presionar la tecla de retroceso para eliminarla antes de guardar el dataset.
• Licencia: es muy importante incluir información acerca de la licencia para que los usuarios puedan entender cómo utilizar los datos. Si requieres utilizar una licencia diferente a las mostradas, contacta al administrador del sitio.
• Organización: si eres miembro de una organización, este menú permite seleccionar bajo que organización catalogar el dataset.

De manera predeterminada el único campo requerido en esta página es el título. Sin embargo, es una buena práctica incluir, al menos, una descripción y una licencia. Es importante asegurarse de que se seleccionó correctamente la organización ya que no se podrá modificar posteriormente. En cualquier otro momento se pueden agregar campos o editarlos.

Paso 3. Al finalizar el llenado de los campos, presiona el botón "Siguiente: Agregar Datos".

Paso 4. CKAN mostrará la vista de "Agregar datos".

Éste es el espacio donde se agregan uno o más "recursos" que contienen los datos de este dataset. Selecciona un archivo o liga a los datos escogiendo la opción correcta en la parte superior de esta vista:

• Si vas a compartir una liga o enlace a los datos, como http://ejemplo.com/los-datos.csv, selecciona entonces "Enlaza a un archivo" o "Enlace a una API". Si no estas familiarizado con el término API selecciona simplemente "Enlaza a un archivo".
• Si los datos que se subirán a CKAN están en archivos de tu computadora, selecciona "Sube un archivo". CKAN mostrará el navegador de archivos para seleccionar alguno.

Paso 5. Llena la otra información de esta página. Estos campos no son obligatorios pero es buena práctica llenarlos:

• Nombre: un nombre para este recurso, p. ej. "Atención a emergencias del año 2013". Otros recursos en este mismo dataset pueden tener diferentes nombres.
• Descripción: una descripción de este recurso.
• Formato: el formato de archivo de este recurso, p. ej. CSV (del inglés comma-separated value), XLS, JSON, etc.

Paso 6. Si deseas agregar al dataset más recursos (archivos o ligas), selecciona "Guardar y Agregar otro". Al finalizar presiona "Siguiente: Información adicional".

Paso 7. CKAN muestra la vista "Datos adicionales".

Todos los campos de esta pantalla son opcionales. Es considerado buena práctica asegurarse que el autor o el mantenedor es mencionado.

• Autor: el nombre de la persona u organización responsable de la producción de estos datos.
• Email del Autor: correo electrónico del autor, a donde se dirigen las consultas sobre los datos.
• Mantenedor / Email del Mantenedor: si es necesario, mencionar una segunda persona responsable
• Campo Personalizado: si se desea agregar campos adicionales, aquí se puede describir el nombre del campo y su valor, p. ej. "Año de publicación". Cabe recalcar que si se identifica un campo extra requerido en varios datasets, sería buena idea hablar con el administrador del sitio para agregarlo a la forma de manera predeterminada.
• Añadir grupo: los "grupos" son colecciones de datasets (ver sección sobre la creación de grupos). En este campo se puede agregar el dataset a un grupo existente.

Paso 8. Selecciona el botón "Terminar". CKAN crea el dataset y muestra el resultado. ¡Listo! ¡Terminaste!

En estos momentos debes poder encontrar tu dataset escribiendo el título o algún término relevante de la descripción en el campo de búsqueda de cualquier página de CKAN. Para mayor información sobre búsquedas, revisa la sección "Búsqueda de datos".

Puedes editar el dataset que creaste o cualquier otro publicado por alguna organización de la que seas miembro.

Paso 1. Ve a la página del dataset. Puedes encontrarlo escribiendo el título en la caja de búsqueda de cualquier página.

Paso 2. Presiona el botón “Editar” que encontrarás arriba del título del dataset.

Paso 3. CKAN muestra la vista “Editar Conjunto de datos”.

Puedes editar cualquiera de los campos (título, descripción, etc.), cambiar la visibilidad (Privado/Público), y agregar o eliminar etiquetas o campos personalizados. Para mayor detalle de estos campos, ver “Agregar un nuevo dataset”.

Paso 4. Al finalizar presiona el botón “Actualizar Conjunto de datos” para guardar los cambios.

Paso 1. Ve a la página de “Editar Conjunto de datos” (pasos 1 y 2 de la sección anterior).

Paso 2. En el panel izquierdo tenemos opciones para editar recursos. Puedes seleccionar un recurso existente (para editarlo o borrarlo), o seleccionar “Agregar Nuevo Recurso”.

Paso 3. Puedes editar la información acerca de un recurso o cambiar el archivo enlazado o almacenado. Para mayor detalle ver los pasos 4 y 5 de “Agregar un nuevo dataset”.

Paso 4. Al finalizar la edición, presiona el botón “Actualizar Recurso” (o “Añade” para un nuevo recurso) para almacenar los cambios. Alternativamente, para eliminar un recurso, presiona el botón “Borrar”.

Paso 1. Ve a la página “Editar Conjunto de datos” (revisar la sección correspondiente).

Paso 2. Presiona el botón “Borrar”.

Paso 3. CKAN mostrará una caja de diálogo de confirmación. Para completar el borrado del dataset selecciona “Confirmar”.

El dataset eliminado no se borra completamente, se esconde para que no sea localizado desde las búsquedas. SIn embargo, al visitar la URL de dicho dataset se puede ver por aquellos usuarios autorizados, con la etiqueta de “Eliminado”.

En general, cada dataset se publica bajo una organización. Cada organización agrupa ciertos usuarios, quienes pueden modificar los datasets y crear nuevos. Dentro de una organización se pueden asignar diferentes niveles de privilegios de acceso a los usuarios, p. ej. algunos usuarios podrán editar datasets mas no crear nuevos, o crear datasets pero no publicarlos. Cada organización tiene una página principal, donde los usuarios pueden encontrar información acerca de ésta y buscar dentro de los datasets de la organización. Esto permite a diferentes departamentos (o equipos) tener control de sus propias políticas de publicación de datos.

Para crear una organización:

Paso 1. Selecciona la liga “Organizaciones” en la parte superior de cualquier página.

Paso 2. Presiona el botón “Agregar Organización” que se encuentra debajo de la caja de búsqueda.

Paso 3. CKAN muestra la página “Crear una Organización”.

Paso 4. Ingresa el nombre de la organización, y opcionalmente, una descripción y liga a una imagen para la página principal de la organización.

Paso 5. Presiona “Crear Organización” y CKAN crea la organización y muestra su página principal. En un principio la organización no tendrá datasets.

Ahora puedes cambiar los privilegios de acceso de los usuarios de la organización. Revisar “Administrar una organización” en la siguiente sección. Puedes también crear datasets dentro de la organización; ver “Agregar un nuevo dataset”.

Dependiendo en como CKAN fue configurado, puede que no estés autorizado para crear organizaciones. En tal caso, contacta al administrador del sitio.

Al crear una organización, automáticamente CKAN te convierte en administrador de la organización. Desde la página de la organización deberás ver el botón “Administración del sitio” por arriba de la caja de búsqueda. Cuando seleccionas dicho botón, CKAN muestra la página administrativa de la organización. Esta página tiene las siguientes pestañas:

• Editar: aquí puedes actualizar la información de la organización (título, imagen, etc.).
• Conjuntos de datos
• Miembros: aquí puedes agregar, remover, y cambiar roles de acceso para diferentes usuarios dentro de la organización.

De manera predeterminada CKAN habilita a los miembros de las organizaciones con tres roles:

• Miembro: puede ver los datasets privados de la organización.
• Editor: puede editar y publicar datasets.
• Administración del sitio: puede agregar, remover y cambiar roles de los miembros.

Para encontrar datasets en CKAN teclea en la caja de búsqueda cualquier combinación de términos clave (p. ej. “remesas”, “licitaciones”) y se mostrarán los resultados. Las búsquedas se pueden filtrar por etiquetas, formatos, zona geográfica, y otros campos utilizando los filtros de la columna izquierda.

Los filtros pueden ser de gran ayuda cuando la búsqueda arroja un gran número de resultados, ya que se pueden agregar, remover, y combinar para hacer más efectiva la búsqueda.

Si deseas buscar datos publicados bajo alguna organización, puedes realizar la búsqueda desde la página principal de ésta.

Paso 1. Selecciona “Organizaciones” de la parte superior de cualquier página.

Paso 2. Selecciona la organización de interés.

Paso 3. Dentro de la página de la organización, teclea en la caja de búsqueda y CKAN regresará resultados de búsqueda limitados a los datasets publicados por dicha organización.

Si la organización es de tu interés puedes optar por recibir notificaciones de cambios utilizando el botón de “Seguir” en la página de ésta. Recibirás notificaciones cuando se publiquen nuevos datasets o existan modificaciones. Para mayor detalle ve la sección “Administración del canal de noticias” de esta guía. Para hacer uso de esta funcionalidad debes tener cuenta de usuario y haber ingresado con tu cuenta al sistema.

Cuando encuentras y seleccionas un dataset de interés, CKAN lo muestra en una página propia que incluye:

• el nombre, descripción, y otra información sobre el dataset
• enlaces a cada uno de los recursos con una breve descripción

Las descripciones de los recursos apuntan a páginas dedicadas a cada uno de los recursos. Esta página del recurso incluye información y permite la descarga. Una buena variedad de recursos pueden ser previsualizados en esta página. Archivos en formato .CSV y hojas de cálculo .XLS pueden ser visualizados en tabla, gráfica y mapa (si se tienen campos geográficos). De igual manera, si los recursos son formatos comunes como PDF o HTML, podrán ser cargados en una vista previa.

La página del dataset también cuenta con otras dos pestañas:

• Flujo de Actividad: revisa el historial de los cambios recientes al dataset.
• Relacionados: ve enlaces a páginas web relacionadas con el dataset.

Si el dataset es de tu interés puedes optar por recibir notificaciones de cambios utilizando el botón de “Seguir” en esta página. Para mayor detalle ve la sección “Administración del canal de noticias” de esta guía. Para hacer uso de esta funcionalidad debes tener cuenta de usuario y haber ingresado con tu cuenta al sistema.

CKAN ofrece funcionalidad para personalizar la experiencia de búsqueda y publicación de datos. Debes entrar al sistema con cuenta registrada para hacer uso de esta funcionalidad.

Para entrar al canal de noticias, selecciona el símbolo de la “Pizarra” que encontrarás en seguida de tu nombre en la parte superior de cualquier página. Aquí se mostrarán cambios a los datasets que sigues, y cualquier cambio o adición de datasets de las organizaciones de tu interés. El número del ícono de la pizarra indica las notificaciones sin revisar. Así como seguir datasets y organizaciones, es posible seguir usuarios para ser notificado de cualquier cambio que realizan a datasets.

Para dejar de seguir un dataset, organización o usuario, basta con ir a la página correspondiente de dicha entidad y presionar el botón de “Dejar de seguir”.

En cualquier momento puedes cambiar la información que CKAN tiene registrado de tí, incluyendo lo que los otros usuarios pueden ver de tu información. Para realizar modificaciones a esta configuración, selecciona el símbolo de “engrane” en la parte superior de cualquier página.

CKAN muestra la página de configuración de usuario, donde puedes actualizar:

• Nombre de usuario
• Nombre completo
• Dirección de correo electrónico
• Acerca de, que básicamente es un párrafo corto que describe al usuario
• Contraseña

Realiza los cambios necesarios y presiona el botón “Actualizar Perfil”.

Si realizas cambios a tu nombre de usuario, CKAN te sacará de tu cuenta y necesitarás entrar al sistema otra vez con tu nuevo nombre de usuario.