Tutorial del conector de Dropbox para el SDK de Conectores de Jitterbit

Introducción

Este tutorial cubre el conector de Dropbox, un conector completo construido con el SDK de Conectores de Jitterbit. Aunque está completamente funcional, este conector no está destinado para uso en producción. Se pretende que sea un punto de partida para el desarrollo de conectores, ya que no cuenta con todas las pruebas y el manejo de errores que se esperarían en un conector de producción.

Siempre que hayas cumplido con los requisitos previos, puedes descargar el ejemplo, construirlo y empaquetarlo, instalarlo en un agente privado de Jitterbit y usarlo en un proyecto para conectarte a Dropbox y mover archivos.

El tutorial asume que estás familiarizado tanto con Jitterbit como con Jitterbit Integration Studio. Si no estás familiarizado con Integration Studio, revisa nuestra documentación de Integration Studio, en particular la guía de inicio rápido de Integration Studio.

Obtener el conector de Dropbox de ejemplo

Si aún no lo has hecho, el primer paso es clonar el conector de Dropbox del repositorio de GitHub. Puedes hacerlo desde el sitio web de GitHub o ejecutando estos comandos:

git clone https://github.com/jitterbit/dropbox-connector.git
cd dropbox-connector

Registra tu conector de Dropbox de ejemplo

Necesitarás cierta información antes de poder construir y empaquetar el conector: un inicio de sesión y una aplicación de Dropbox, un nombre de usuario y contraseña de cuenta de Harmony, y valores de registro del conector de Jitterbit. Los valores obtenidos del registro del conector se utilizan en el manifiesto antes de construir y empaquetar el conector.

Dropbox

El primer paso es en Dropbox mismo. Dado que el conector será una aplicación que interactúa con Dropbox, necesitarás registrarte en Dropbox como desarrollador y crear una aplicación de Dropbox utilizando la API de Dropbox. La aplicación puede tener cualquier nombre y configuración. Esto se puede hacer con una cuenta gratuita de Dropbox. En el sitio web de Dropbox, crea una aplicación:

Desde la página web de tu nueva aplicación, obtén su clave de aplicación y genera un token de acceso. Esta imagen muestra (marcado en rojo) dónde se pueden obtener en la página web:

En este ejemplo, se ha creado una aplicación llamada "Jitterbit Connector SDK Testing". La clave de aplicación se muestra como "xxxxxxxxxxxxxxx". El token de acceso se mostrará una vez que se haya utilizado el botón Generar debajo de la etiqueta Token de acceso generado.

Haz clic en el botón Generar para generar el token de acceso, copia tanto la clave de aplicación como el token de acceso, y guárdalos de forma segura donde puedas recuperarlos al configurar el conector.

Nota la configuración del Nombre de carpeta de la aplicación (marcado en azul). En este ejemplo, esta es la carpeta raíz en Dropbox desde donde se originarán los archivos que pongas o recuperes con el conector.

Harmony

Si aún no has obtenido un nombre de usuario y una contraseña de Harmony, necesitarás uno antes de continuar. (Una licencia de prueba es suficiente: ve a https://jitterbit.com y haz clic en el botón Solicitar prueba para registrarte.)

Registro del conector de Jitterbit

Todos los conectores de Jitterbit requieren registro, lo que implica usar una API de Jitterbit para registrar el conector utilizando tus credenciales de Harmony.

Para registrar el conector y obtener los valores de registro, utiliza la colección de Postman incluida en el conector de Dropbox como postman/JitterbitConnectorManagerAPI.collection.json.

Antes de ejecutar la API REST, importa las variables de entorno desde postman/jitterbit-env-variable-postman.json en Postman y asócialas con la colección.

Edita el entorno e ingresa el host (según lo definido por tu región; consulta Encontrar mi región), correo electrónico (tu-nombre-de-usuario-jitterbit-harmony@example.com), contraseña (tu contraseña de Harmony) y el nombre del conector variables de entorno apropiadamente:

El nombre bajo el cual se registra el conector debe coincidir con el valor en el archivo adapter.json utilizado para describir la interfaz de usuario. Para este tutorial, el name del conector proporcionado en el archivo adapter.json de Dropbox es Dropbox. Para más detalles sobre el archivo de la interfaz de usuario, consulta Implementación del conector y Componentes de la interfaz de usuario del SDK de conectores.

Ahora, desde Postman, ejecuta estas dos APIs en orden:

Log In User
Register a Connector

(Las otras APIs en la colección se pueden usar para listar y eliminar conectores existentes que hayas registrado previamente, y para confirmar la validez de la clave y el secreto de un conector.)

La respuesta devuelta por la API Register Connector contiene las claves y valores que se necesitan para que el manifiesto del conector complete el registro del conector. Deberías recibir una respuesta como:

{
  "status": true,
  "operation": "Register a connector",
  "id": "3691",
  "key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "secret": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "endpointEntityId": "20101",
  "functionEntityStartId": "20102",
  "functionEntityEndId": "20200"
}

Como se puede ver en este ejemplo, se ha registrado un conector, tiene un ID de entidad de punto final de 20101, y puede tener IDs de entidad de actividad de función que van desde 20102 hasta 20200.

API de Registro de Conector	Claves del Archivo Manifiesto
`key`	`Jitterbit-Connector-Key`
`secret`	`Jitterbit-Connector-Secret`
`endpointEntityId`	`Jitterbit-Connector-Endpoint-EntityTypeId`
`functionEntityStartId`	`Jitterbit-Activity-EntityTypeId-<first_activity>`
`functionEntityEndId`	`Jitterbit-Activity-EntityTypeId-<last_activity>`

La clave y el secreto devueltos se convertirán, siguiendo la tabla anterior, en Jitterbit-Connector-Key y Jitterbit-Connector-Secret en el manifiesto para el conector.

El conector ha sido asignado un ID de punto final y un rango de IDs de puntos finales de actividad (función), desde el primero hasta el último. En el caso del conector de Dropbox, que tiene cuatro actividades (Obtener Archivo, Obtener Archivo, Procesar Archivo y Poner Archivo), se deben asignar IDs individuales a cada actividad de manera que caigan dentro del rango asignado. Se puede asignar un máximo de 99 actividades a un conector individual.

Completar el archivo de manifiesto

Con la información obtenida, ahora puedes establecer los valores en el archivo de manifiesto MANIFEST.MF ubicado en el repositorio de GitHub clonado del conector de Dropbox en src/main/resources/META-INF:

Author: Jitterbit
Version: 1.0.0
Jitterbit-Connector-Key: <key>
Jitterbit-Connector-Secret: <secret>
Jitterbit-Connector-Endpoint-EntityTypeId: <endpoint_type_id>
Jitterbit-Activity-EntityTypeId-fetch: <id-1>
Jitterbit-Activity-EntityTypeId-put: <id-2>
Jitterbit-Activity-EntityTypeId-process: <id-3>
Jitterbit-Activity-EntityTypeId-get: <id-4>
Jitterbit-Connector-UI: adapter.json
Class-Path: lib/dropbox-core-sdk-3.0.6.jar

La clave, el secreto y los IDs fueron devueltos de la registración del conector. Dado que el conector de Dropbox tiene cuatro actividades, puedes usar el ID inicial para Jitterbit-Activity-EntityTypeId-fetch (la actividad Obtener Archivo) y luego incrementar los IDs para las otras tres actividades. La última actividad debe ser menor o igual al functionEntityEndId. Completa estos valores antes de construir el conector. Ten en cuenta que debe haber un espacio entre los dos puntos de la etiqueta y el valor en cada línea del archivo de manifiesto.

Advertencia

Si estás construyendo el conector en Windows, ten en cuenta que el archivo de manifiesto debe tener un retorno de carro/fin de línea al final; de lo contrario, la última entrada (Class-Path) se omitirá y no se incluirá en el archivo de manifiesto incluido en el archivo JAR de salida.

Construir el conector de Dropbox

Habiendo editado y guardado las entradas del manifiesto, ahora estás listo para construir el conector. Ejecuta estos comandos dentro del directorio dropbox-connector que contiene el repositorio clonado con el manifiesto editado:

export APP_KEY=<dropbox-app-key>
export ACCESS_TOKEN=<dropbox-access-token>
mvn jaxb2:xjc compile install

Nota

Si tu variable de entorno JAVA_HOME no está configurada para Java SE Development Kit 8, puedes configurarla temporalmente para una sola construcción de Maven con el siguiente comando:

JAVA_HOME="/Path/to/JDK/jdk-1.8.jdk/Contents/Home" mvn jaxb2:xjc compile install

Esto compilará, probará, construirá, empaquetará e instalará el conector. El archivo JAR completado estará en:

dropbox-connector/target/jitterbit-connector-dropbox-1.0.0.jar

Instalar el conector

El conector completado ahora se puede instalar en un agente privado. (Para detalles sobre la instalación de agentes, consulte Requisitos del sistema para agentes privados).

Para que el agente encuentre el conector, el JAR del conector debe colocarse en el directorio de conectores del agente. Típicamente, se encuentra en:

Linux: /opt/jitterbit/Connectors
Windows: C:\Program Files (x86)\Jitterbit Agent\Connectors (se requieren privilegios de administrador)
Docker: el directorio mapeado a /opt/jitterbit/Connectors en el comando de Docker, como --volume "$(pwd)/dropbox-connector:/opt/jitterbit/Connectors"

Si está utilizando la imagen de agente privado de Docker Harmony, permite montar un directorio del host en un directorio del contenedor como /connectors. Dentro del contenedor de Docker, el agente escaneará el directorio /opt/jitterbit/Connectors en busca de archivos JAR que contengan una implementación de conector (solo se permite una implementación de conector en cada archivo JAR). Para desplegar el JAR del conector de Dropbox después de que se haya construido, mientras se ejecuta el agente como un contenedor de Docker, copie el archivo JAR del directorio target de construcción al directorio montado como el directorio de conectores y reinicie el contenedor. Cuando el contenedor de Docker se inicie, copia el contenido del directorio montado al directorio /opt/jitterbit/Connectors.

En todos los casos, no utilice el directorio de construcción de Maven como el directorio de conectores, ya que el escaneo del directorio se confundirá al encontrarse con las etapas intermedias del proceso de construcción de Maven. En su lugar, copie el JAR completado al directorio de conectores cuando el proceso de construcción haya finalizado. Esto se puede realizar manualmente o incorporarse como un paso después de una construcción exitosa.

El agente escanea continuamente el directorio de conectores en busca de cambios y recarga automáticamente cualquier JAR de conector que encuentre que sea nuevo o que haya sido modificado. Esto significa que, a medida que desarrollas tu conector, simplemente copia cada nueva compilación en el directorio de conectores para que sea recargada automáticamente por el agente.

Ejemplo de Docker

Por ejemplo, en un sistema Linux que ejecuta un agente privado de Docker, ejecutar este comando en el directorio padre del dropbox-connector iniciará un agente de Docker con el directorio target mapeado al directorio /opt/jitterbit/Connectors del agente:

docker run --interactive --tty --name=jitterbit-agent --publish 3000:3000 \
           --volume "$(pwd)/dropbox-connector/target:/opt/jitterbit/Connectors" \
           --env-file "$(pwd)/private-agent.env" \
           jitterbit/agent

donde private-agent.env contiene las variables de entorno utilizadas para conectarse a Harmony.

El archivo private-agent.env se vería así; sustituye los valores apropiados:

HARMONY_USERNAME="<email_address>"
HARMONY_PASSWORD="<password>"
HARMONY_ORG="<your_organization_name>"
HARMONY_AGENT_GROUP="<your_agent_group_name>"
HARMONY_AGENT="<your_agent_name>"

En un símbolo del sistema diferente (o PowerShell, para Windows OS) puedes verificar que el contenedor de Docker esté activo usando:

docker ps -a

CONTAINER ID IMAGE                  COMMAND                CREATED       STATUS       PORTS                                              NAMES
xxxxxxxxxxxx jitterbit/agent:latest "/entrypoint.sh /ag…" 2 minutes ago Up 2 minutes 46908-46909/tcp, 0.0.0.0:3000->3000/tcp, 46912/tcp jitterbit-agent

Nota

Una vez que el contenedor esté activo y pase la verificación de salud, puedes iniciar sesión en el portal de Harmony e ir a la Consola de Administración Agentes para verificar si el agente ha sido registrado y está en funcionamiento.

En un símbolo del sistema diferente (o PowerShell, para Windows OS), puedes acceder al contenedor usando un comando para abrir una terminal en el contenedor de Docker:

docker exec -ti jitterbit-agent /bin/bash

root@b3160de34840:/opt/jitterbit#

En este punto, tienes acceso completo al contenedor del agente. Puedes detener y reiniciar el agente usando la utilidad /opt/jitterbit/bin/jitterbit. Para un mensaje de ayuda, desde dentro del contenedor usa:

/opt/jitterbit/bin/jitterbit help

Desde dentro del contenedor, sigue los registros de Tomcat para verificar los registros del conector:

tail -f tomcat/logs/catalina.out

. . .
2018-04-26 13:28:48,957 INFO com.jitterbit.integration.server.api.ws.connectorframework.ConnectorLoader:63 - Loading connectors...
. . .
2018-04-26 13:28:49,185 WARN com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:96 - Could not load Jitterbit Connector via manifest.mf; no Main-Class or Jitterbit-Connector-Factory-Class attributes defined.
2018-04-26 13:28:49,186 WARN com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:97 - Falling back to annotation system
2018-04-26 13:28:49,187 INFO com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:440 - Temporary Directory for undeploying connectors bundle: /opt/jitterbit/tomcat/temp
2018-04-26 13:28:49,517 INFO com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:377 - Loading annotated class java.lang.Class
2018-04-26 13:28:49,527 INFO com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:395 - Register Activity Factory with id: 200500 name: put factory: org.jitterbit.connector.dropbox.activities.PutFileActivity$PutFileActivityFactory
2018-04-26 13:28:49,530 INFO com.jitterbit.integration.server.api.ws.connectorframework.ConnectorClassLoader:395 - Register Activity Factory with id: 200402 name: fetch factory: org.jitterbit.connector.dropbox.activities.FetchFileActivity$FetchFileActivityFactory
. . .
26-Apr-2018 13:29:22.615 INFO [pool-1-thread-1] org.jitterbit.connector.ConnectorRegistry.registerConnector Connector Name: Dropbox Author: Jitterbit Connector Key: 929f90...52562 Endpoint Entity Type Id: 200401 Internal Connector: false Activities Id: {fetch=200402, put=200500}
26-Apr-2018 13:29:22.617 INFO [pool-1-thread-1] org.jitterbit.connector.sdk.BaseJitterbitConnector.onInit onInit() connector name: Dropbox
. . .

Si ves mensajes similares a estos en los registros, significa que el conector de Dropbox se ha cargado y comenzado con éxito. Ahora puedes iniciar sesión en el portal de Harmony y acceder a Integration Studio para comenzar a usar el conector.

En un proyecto dentro del entorno asociado con el agente privado, deberías ver el conector de Dropbox en la paleta de componentes de diseño. Luego puedes configurar el endpoint como lo harías con cualquier otro conector en Cloud Studio.

Usar el conector de Dropbox

Ahora deberías ver el conector en proyectos que utilizan el entorno asociado con tu agente privado y el conector. Debería aparecer en la paleta de componentes de diseño en la pestaña Conectividad cuando el menú desplegable Mostrar esté configurado para filtrar por Conectores o Todo:

Si no es así, consulta la sección de solución de problemas al final de este documento para obtener sugerencias antes de continuar.

Configurar una conexión de Dropbox

La primera tarea es usar el conector de Dropbox para configurar una conexión de Dropbox y establecer conectividad con el endpoint. En la paleta de componentes, asegurándote de que el menú desplegable Mostrar esté configurado para filtrar por Conectores o Todo, haz clic en el conector de Dropbox para abrir la configuración de la conexión. Asigna un nombre a la conexión (como "Dropbox") e ingresa la Clave de la App de Dropbox y el Token de Acceso de Dropbox que guardaste previamente:

Haz clic en el botón Probar para confirmar que la conexión es exitosa, y luego haz clic en el botón Guardar Cambios para guardar la configuración y regresar al flujo de trabajo.

Ahora deberías ver cuatro actividades bajo la conexión de Dropbox configurada en la paleta de componentes: Procesar Archivo, Obtener Archivo, Conseguir Archivo y Poner Archivo. Estas actividades ahora pueden ser añadidas a operaciones en el lienzo de diseño y configuradas como fuentes o destinos en una operación. Juntas, una conexión específica y sus actividades se conocen como un endpoint:

Escenarios del tutorial

Estos escenarios de tutorial demuestran cada uno una actividad diferente del conector:

Escenario 1: Obtener Archivo: Obtener un archivo de texto de Dropbox y escribirlo como un archivo XML en un servidor FTP.
Escenario 2: Obtener Archivo: Obtener un archivo de texto de Dropbox y escribirlo como un archivo de texto en un servidor FTP.
Escenario 3: Colocar Archivo: Leer un archivo de texto de un servidor FTP y colocarlo en Dropbox como un archivo de texto.
Escenario 4: Procesar Archivo: Obtener un archivo XML de Dropbox, procesarlo y escribirlo como un archivo JSON en un servidor FTP.
Escenario 5: Obtener Archivo: Obtener un archivo de Dropbox y escribirlo en un servidor FTP.

Para completar los escenarios del tutorial, necesitarás credenciales (host, nombre de usuario y contraseña) para un servidor FTP. Si recientemente completaste la capacitación de Jitterbit University y tienes credenciales válidas, puedes usar el servidor FTP de ese curso. Configura un punto final FTP, ingresando el host, nombre de usuario y contraseña. En estos tutoriales, el punto final FTP se nombra utilizando el nombre "FTP":

Solución de Problemas

Si no puedes cargar el conector o verlo en Integration Studio, consulta los consejos en la página de solución de problemas del SDK de Conectores.