Adaptador JSON para el SDK del Conector Jitterbit

La interfaz de usuario del Estudio de Integración para un conector creado con el SDK del Conector Jitterbit se define mediante un archivo JSON incluido en el archivo JAR que empaqueta el conector. Por convención y de forma predeterminada, este archivo se llama adapter.json.

El nombre de este archivo puede ser diferente, ya que el nombre utilizado es el especificado en la entrada Jitterbit-Connector-UI del archivo MANIFEST-MF:

Jitterbit-Connector-UI: adapter.json

Consulta Registro de conectores: Manifiesto del conector para obtener detalles sobre el archivo MANIFEST.MF.

Archivo JSON del adaptador

El desarrollador de un conector define todos los componentes de la interfaz de usuario en el archivo adapter.json. Estos componentes se muestran cuando el usuario configura el conector y sus actividades, y los valores ingresados pueden ser recuperados por el código del conector.

Estructura del archivo JSON del adaptador

Aquí hay un esquema general del archivo JSON que define una interfaz de usuario de conector, con valores de marcador de posición mostrados como "<name>". Los términos utilizados y sus significados se discuten después de este ejemplo:

{
  "name": "<name>",
  "version": "1.0.0",
  "sandbox": true,
  "defaultActivityIcon": "<path-to-SVG-file>",
  "endpoint": {
    "displayName": "<display-name>",
    "icon": "<path-to-SVG-file>",
    "properties": [ "<properties>" ]
  },
  "activities": {
    "activity-1": {
      "displayName": "<display-name-1>",
      "icon": "<path-to-SVG-file>",
      "properties": [ "<properties>" ]
    },
    "activity-2": {
      "displayName": "<display-name-2>",
      "properties": [ "<properties>" ]
    },
    . . .
  }
}

En este esquema, se ha definido un conector con propiedades para el punto final y sus dos primeras actividades. Se pueden agregar actividades adicionales según sea necesario.

Para la conexión (que es lo que aparece cuando un usuario final configura por primera vez el conector en la interfaz de usuario del Estudio de Integración), se puede definir un conjunto de propiedades que se utilizarán para generar uno o más pasos que el usuario final completa para configurar la conexión al punto final.

Ten en cuenta que el name y el version utilizados deben ser el mismo nombre y versión bajo los cuales el conector está registrado (consulta Registro de conectores).

La propiedad sandbox puede establecerse en true o false. Establecerla en true significa que el conector está en desarrollo y no será almacenado en caché por Harmony. En su lugar, cada invocación volverá a cargar el conector desde el agente privado de Jitterbit. Una vez que tengas una versión de producción, puedes establecer esto en false para que se pueda utilizar la caché y acelerar el uso.

Un conjunto de propiedades se define para cada actividad, generando pasos para configurar la actividad después de que se añade a una operación en Integration Studio.

Iconos de endpoint

Como se puede ver en el esquema anterior, se pueden definir iconos para la conexión y cada una de las actividades (denominadas en conjunto como un endpoint). Los iconos se definen utilizando SVG y se proporcionan como una ruta a un archivo SVG.

Estas claves se pueden proporcionar en el adapter.json:

En el ejemplo esquemático anterior, se ha definido un icono predeterminado, con la conexión y la primera actividad utilizando otros—quizás diferentes—iconos. La segunda actividad no tiene un icono definido y, en su lugar, utiliza el icono predeterminado.

Esta captura de pantalla del conector de Dropbox muestra cómo se pueden usar diferentes iconos:

Un icono (una carpeta) se utiliza para la conexión con un icono diferente utilizado para las actividades. Es posible tener un icono diferente para cada actividad, aunque se aconseja mantener un tema común de colores y formas para un endpoint. Tenga en cuenta que el texto que describe la actividad se superpone al icono. Es mejor dejar la mitad inferior del icono de un color sólido para que el texto blanco tenga un fondo contra el cual aparecer.

Para obtener detalles sobre cómo crear los archivos SVG, incluidos plantillas y un recorrido, consulte Iconos de endpoint de SDK de conector.

Orden de actividades e iconos

El orden de los íconos en la interfaz de usuario debe seguir el orden de las actividades en el JSON. Si el número de actividades excede tres, se añaden filas adicionales de actividades en la interfaz de usuario debajo de la fila original.

Nuestra recomendación para el orden de las actividades es seguir estos patrones comunes:

• Leer, Escribir
• Consultar (o Buscar), Crear, Actualizar, Upsert, Eliminar
• Obtener, Publicar, Poner, Eliminar
• Solicitar, Responder
• Descargar, Subir

Si hay actividades personalizadas, especiales o específicas de la entidad fuera de los ejemplos anteriores (como Obtener Lista), colócalas hacia el principio del orden si están destinadas a proporcionar datos como fuente en una operación, y hacia el final si están destinadas a recibir datos como objetivo en una operación.

Paginación

Para la conexión y cada actividad, se definen propiedades en una estructura JSON. Estas crean los pasos de configuración (páginas) que un usuario final debe seguir para configurar la conexión y cada una de las actividades particulares que elija usar.

Paginación predeterminada

Las conexiones no tienen paginación por defecto. Para las conexiones, a menudo hay solo un paso, aunque el desarrollador puede agregar tantos como sea necesario.

Para las actividades, hay al menos dos pasos: una página inicial con un campo de nombre y una página final que muestra los esquemas de datos para revisión. Ambas páginas son creadas automáticamente por la infraestructura y no están incluidas ni definidas en el archivo JSON.

En este ejemplo hay pasos inicial (página 1) y final (página 2):

Página única

Si la conexión o actividad se puede configurar en una sola página y no se requiere paginación, se puede usar una estructura simple:

. . .
"properties": [
  {
    "name": "<name-1>",
    "displayName": "<display-name-1>",
    "type": "string",
    "validators": [
      {
        "name": "required"
      }
    ]
  },
  {
    "name": "<name-2>",
    "displayName": "<display-name-2>",
    "type": "string",
    "validators": [
      {
        "name": "required"
      }
    ]
  }
]
. . .

Múltiples páginas

Sin embargo, si la configuración es más larga, con múltiples valores que deben establecerse o revisarse, se recomienda la paginación para mantener las vistas más pequeñas en profundidad:

. . .
"properties": [
  {
    "name": "page1",
    "displayName": "<display-name-page-1>",
    "type": "pagination",
    "children": [
      {
        "name": "<name-1-1>",
        "displayName": "<display-name-1-1>",
        . . .
      },
      . . .
    ]
  },
  {
    "name": "page2",
    "displayName": "<display-name-page-2>",
    "type": "pagination",
    "children": [
      {
        "name": "<name-2-1>",
        "displayName": "<display-name-2-1>",
        . . .
      },
      . . .
    ]
  }
]
. . .