Datahub- Información general

ℹ️ | Trabajar con una herramienta para la gestión de la relación con los clientes como Splio a menudo requiere el uso de grandes cantidades de datos. Estos datos se tienen que importar y mantener actualizados en el sistema.

Los usuarios con derechos de Administrador pueden importar nuevos contactos a Splio desde la interfaz, pero los contactos no son el único tipo de dato.

Para poder importar otro tipo de información, Splio ofrece una funcionalidad de importación automática llamada Datahub.

A través de Datahub, puedes alimentar a Splio con varios tipos de datos de una forma organizada. Todo lo que tienes que hacer es preparar los ficheros y subirlos a la carpeta FTP asignada, desde la cual una secuencia de comandos automática los cogerá e importará.

Requisitos previos

• Activación de la opción de Datahub por parte de tu Project Manager
• Posibilidad de abrir y guardar ficheros en formato CSV con codificación UTF-8 sin BOM

• Permiso para mover, copiar y renombrar ficheros localmente
• Acceso a conexión SFTP para cargar los ficheros de importación

Importación paso a paso

Sigue estos pasos para permitir que Splio importe tus ficheros de datos via Datahub.

• Prepara los ficheros CSV: sigue las indicaciones más abajo para crear y dar formato a los archivos que contienen tus datos.
• Sube los ficheros: conéctate al protocolo SFTP y carga los archivos. Tu Project Manager te proporcionará la información de conexión, si la necesitas.
• Comprueba el estado: Splio procesa los archivos de importación en tiempo real y envía alertas y resultados a las direcciones de email configuradas para este propósito. También puedes revisar los logs para obtener más información.

Reglas sobre los ficheros de datos

Sigue las siguientes pautas cuando prepares los ficheros para la carga:

• Cada fichero debe contener los datos pertenecientes a una única tabla
• Los archivos deben utilizar el formato CSV, sin datos multilínea
• Se debe utilizar codificación UTF-8 sin BOM
• Los nombres de los ficheros deben indicar el universo, la tabla, la subsecuencia y la fecha
• La prioridad de importación depende de las tablas y prevalece en establecer el orden de carga de los ficheros
• Se pueden utilizar identificadores opcionales para diferenciar los ficheros.

Estas reglas se explican con más detalle abajo.

💡 | Para facilitar el tratamiento, los ficheros de importación se pueden subir como archivos comprimidos.

Tablas y alcances

Cada fichero de importación debe pertenecer a un tipo de dato (tabla o alcance), que Splio pueda reconocer. Todos los nombres de tablas/alcances están predefinidos, en minúscula y son case sensitive.

Todas las tablas disponibles se enumeran a continuación, con pequeñas descripciones. Cada nombre de tabla lleva un enlace en el que puedes encontrar la documentación correspondiente.

• contacts (contactos): clientes o prospects de tu base de datos
• stores (tiendas): tanto tiendas físicas, como eCommerce
• products (productos): artículos del catálogo
• abandonedcarts (carritos abandonados): pedidos que nunca fueron finalizados
• orders (recibos): pedidos realizados por parte de los clientes
• ordersitems (líneas de recibo): productos contenidos en casa recibo o carrito abandonado.

Consulta la documentación para conocer qué campos de datos (columnas) necesitas y puedes incluir para cada tabla.

Borrado de Contactos

Splio permite la eliminación de contactos en la base de datos a través de importaciones automáticas. Si necesitas eliminar registros, consulta la documentación sobre el borrado. 

Alcances Loyalty

Hay unos alcances adicionales utilizados para importar datos para los programas de Loyalty. Siguiendo los enlaces puedes obtener más información sobre cada uno:

• cardcode (ID tarjetas Loyalty): para gestionar el alta al programa de fidelización de los contactos
• creditpoints (crédito de puntos): para asignar (credit) puntos a los miembros del programa de Loyalty
• masterreward, earnreward, and burnreward (master reward, asignación reward y canjeo reward): para crear rewards, asignarlos a los miembros del programa (earn), y canjearlos (burn)
• events (eventos): para asociar eventos a cada contacto

Formato de fichero

Los ficheros de importación utilizan el formato de “valores separados por coma” (Comma-Separated Values), normalmente denominados CSV o ficheros *.csv. Básicamente, los ficheros CSV son archivos de texto en los que el contenido está organizado en columnas y filas, como en una tabla. Las columnas están separadas por punto y coma (“;”) y cada línea del archivo es una fila. Es un formato popular, modificable con editores de texto, que también se puede guardar y exportar por la mayoría de software de base de datos y hojas de cálculo.

Codificación UTF-8

Todos los archivos de importación se deben guardar utilizando el formato de codificación UTF-8 sin BOM. Se trata de un sistema popular que permite que caracteres de diferentes idiomas, p. ej., francés y chino, coexistan en el mismo archivo.

Prácticamente todos los editores de archivo de texto modernos y software de hoja de cálculo pueden guardar archivos CSV con codificación UTF-8, que se ha convertido en el formato por defecto en muchos sistemas.

💡 | La marca de orden de byte (Byte Order Mark - BOM, por sus siglas en inglés) es un carácter especial añadido al principio del archivo. Asegúrate de no utilizarlo.

Cabecera

La cabecera es la primera línea del fichero CSV. Esta línea informa a Splio de cuántas columnas hay en el archivo de datos y de lo que representa cada columna.

El encabezado siempre debe indicar columnas apropiadas para el alcance del archivo y debe contener columnas obligatorias. Si pones un nombre de columna desconocido para la tabla u omites una columna obligatoria, el archivo no se importará.

Líneas de fichero

Todas las líneas del fichero deben contener el mismo número de columnas que la cabecera. Splio saltará todas las líneas que no cumplan este requisito.

Cada línea de fichero representa una unidad única dentro de la tabla. Los datos multilínea no son compatibles: Splio ignorará todas las líneas involucradas.

Tienes la opción de poner el valor de cada campo entre comillas dobles. Sin embargo, no las puedes usar para proporcionar valores que abarquen múltiples líneas.

Para representar números decimales, utiliza el punto (“.”) como separador decimal. No uses ningún separador para los miles. Utiliza “-” para marcar números negativos y no utilices ningún signo para los números positivos.

Ejemplo

Sandra Bellan recibió un fichero de contactos para importar. El archivo es pequeño y decide echarle un vistazo. Lo abre en su editor de texto y observa las dos primeras líneas.

email;firstname;lastname;cellphone;subscriptions 
"example7445@temporarymail.org";"Omar";"Martin";"34120202020";"-5" 

Sandra lee la cabecera, que contiene 5 columnas de contactos. Reconoce todas las columnas y puede decir que son correctas.

Ahora va a la segunda línea. Cuenta 5 columnas, lo que está bien. La primera es un valor de texto, entre comillas, y es una dirección de email correcta. La segunda es también texto entre comillas dobles, la tercera es texto sin comillas. Entonces llega a un valor numérico, el número de teléfono, y finalmente a un número negativo, que es normal para una columna de suscripción.

Uso de carpetas y ficheros comprimidos

Por conveniencia, puedes comprimir tus ficheros CSV para reducir el tamaño y disminuir la cantidad de archivos subidos. Splio es compatible con los siguientes tipos de ficheros, por extensión de nombre de archivo: .zip, .tar, .gz, .bz2. 

Sin embargo, todos los ficheros dentro de carpetas comprimidas deben estar organizados en categorías. Esto se hace añadiendo un prefijo especial al nombre de fichero, según las normas de orden de archivo descritas a continuación. Esto permite a Splio procesar los ficheros dentro de carpetas en un orden claro y predeterminado.

Ten en cuenta que grupos/secuencias son parte de las reglas de nomenclatura. Los ficheros de importación archivados también deben cumplir todas las normas de designación (a continuación), formato y codificación (anteriores). Por otra parte, no hay normas específicas para nombrar archivos. Splio los examinará y los descomprimirá, después procesará el contenido.

Reglas de nomenclatura de ficheros

Para recoger los ficheros para importar, Splio depende de unas convenciones de nomenclatura específicas. La manera de construir el nombre del fichero se tiene que seguir escrupulosamente, de lo contrario la importación no comenzará o fallará a mitad de camino. Por otra parte, es suficiente con cumplir las siguientes normas para garantizar que tus archivos sean procesados.

⚠️ | Si utilizas el mismo nombre de fichero para importaciones consecutivas, únicamente el último archivo se guardará en la carpeta de archivados (/archives). Esto quiere decir que, aunque los ficheros se importen, su contenido no se guardará en la carpeta de ficheros procesados y no se podrá proporcionar ninguna información sobre ellos. 

Nomenclatura básica de ficheros

Todos los ficheros deben ser nombrados según el siguiente esquema:

<universo>_<tabla>_<subsecuencia>_<fecha>.csv 

Los corchetes angulares que contienen cada palabra deben ser sustituidos juntos a la palabra por el valor correspondiente.

Hay cinco partes obligatorias, como se explica a continuación. Por favor, ten en cuenta que el nombre del fichero puede extenderse con información adicional al principio (prefijo) y directamente antes de la extensión «.csv» (sufijo). Los prefijos y los sufijos son opcionales y se analizarán más adelante.

• <universo> es el nombre de tu universo Splio. Todos los ficheros que quieras importar automáticamente deberán llevar su nombre.
• <tabla> es el nombre de la tabla a la cual quieres importar los datos, como explicado en la sección Tablas de arriba.
• <subsecuencia> es el nombre que identifica una importación o ajustes de importación específicos. Por ejemplo, puede ser el nombre de la fuente de datos o un valor que te permite decidir si actualizar los registros existentes o no. Tu Project Manager configura las direcciones de email para recibir alertas y resultados para cada apartado.
• <fecha> es la fecha del fichero, utilizada para determinar el orden cronológico de las importaciones dentro de cada tabla. La fecha debe cumplir uno de los dos formatos: AAAAMMDD (20180315) o AAAAMMDD_HHMMSS (20180315_134403).

Por ejemplo, en un universo Splio «miuniverso», un fichero de la tabla de contactos que contiene los clientes nuevos y modificados del día anterior se llamará miuniverso_contacts_clientes_20180315.csv. 

Recuerda que, para que los ficheros se importen, los nombres de las tablas y subsecuencias deben estar definidos en el fichero de configuración. Puedes configurarlo con la ayuda de tu Project Manager.

Orden de tratamiento de ficheros

Splio siempre sigue el mismo orden al importar los ficheros, una tabla a la vez, pasando a la siguiente tabla solo cuando todas las importaciones en la actual hayan finalizado. Los ficheros se recogen y procesan en el FTP/SFPT en el siguiente orden:

Si no utilizas Loyalty:

1. Grupos de archivos (ver más abajo) 
2. contactos
3. tiendas
4. productos
5. pedidos
6. carritos abandonados
7. líneas de recibo
8. batch

Si utilizas Loyalty, puedes añadir más tarde: 

1. 1. 1. cardcode
      2. earnreward
      3. burnreward
      4. creditpoints
      5. borrar contactos
      6. events
      7. cambio de nivel
      8. masterreward

Los ficheros pertenecientes a la misma tabla se ordenan por la fecha incluida en el nombre del archivo, desde la más antigua hasta la más reciente.

Nomenclatura avanzada de ficheros: secuencia de ficheros por grupos

Aunque el orden de importación por defecto es bastante claro, puede ser insuficiente. Tú y otros compañeros de tu empresa necesitaréis con frecuencia importar ficheros en un orden específico, p. ej., contactos o tiendas antes de los datos de ventas (recibos y líneas de recibos) que dependen de estos contactos. Si el fichero de recibos se cuelga en el repositorio antes del de contactos, Splio saltará todas las líneas que se refieran a los contactos que todavía no se hayan importado.

Sin embargo, este grave riesgo se puede evitar fácilmente utilizando los grupos.

Los grupos se crean añadiendo un prefijo especial <group_id>.YY-ZZ_ al principio del nombre de fichero. Este prefijo está formado por:

• un identificador de grupo, o <group_id>, seguido por
• un punto «.»,
• un número de 2 dígitos del fichero actual de la secuencia, representado como YY,
• un guion «-»,
• un número de 2 dígitos del último fichero de la secuencia, representado como ZZ, y
• un guion bajo «_»

El <id_grupo> es un string de caracteres que es el nombre del grupo. Los números YY y ZZ pueden tener valores entre 01 y 99. Los ficheros dentro de una secuencia deben recibir números subsecuentes empezando con 01 y hasta ZZ.

📗 | El valor ZZ le dice a Splio cuántos números hay. No omitas ningún número dentro de una secuencia, o Splio esperará el archivo que falta. 

Nombres de ficheros agrupados con ejemplos

El nombre de fichero completo se puede resumir como:

<id_grupo>.YY-ZZ_<universo>_<tabla>_<subsecuencia>_<fecha>.csv 

Como puedes ver, la parte que empieza por <universo> lleva el mismo nombre de fichero básico que ya conoces. Echa un vistazo a los siguientes ejemplos:

diario.01-03_miuniverso_contacts_clientes_20180315.csv 
diario.02-03_miuniverso_products_update_20180315.csv 
diario.03-03_miuniverso_orders_offline_20180315.csv 
semanal.02-02_miuniverso_stores_offline_20180315.csv 

Existen dos grupos: «diario» está completo, con 3 ficheros, «semanal» todavía está incompleto, esperando un archivo con el prefijo semanal.01-02_ para ser importado.

Secuencia de ficheros: cómo se procesan los grupos

Splio intenta importar todos los grupos (ficheros secuenciales) antes de importar cualquier fichero individual (no secuencial). El orden en el que se importan se puede encontrar más arriba.

Los grupos se procesan uno por uno, en orden alfabético según el <id_grupo>.

En primer lugar, Splio comprueba si el grupo está completo, es decir, si hay al menos un fichero en el grupo para cada número de 01 a ZZ. Si falta uno o más archivos, Splio pasa al siguiente grupo. Los ficheros que forman parte del grupo incompleto no se eliminan ni procesan: el script espera a que los ficheros que faltan en el grupo se importen.

Al trabajar con un grupo, Splio importa archivos uno a uno en el orden dictado por el número dentro del grupo (YY). Si se encuentra más de un archivo con el mismo número, el que tenga la <fecha> más antigua se importa en primer lugar. Esto permite que la importación automática continúe incluso con archivos entregados en varios intervalos de tiempo. Por ejemplo, se puede mantener el control sobre el orden de la importación incluso si uno de tus compañeros entrega ficheros tres veces a la semana y otro lo hace a diario.

⚠️ | Ten en cuenta que una vez empiece la importación del grupo, los archivos dentro del grupo son tratados de forma secuencial. Si algún archivo secuencial es rechazado (p. ej., falta una columna obligatoria o, contrariamente, hay una columna inexistente), Splio abortará la importación del grupo y pasará al siguiente. 

Nomenclatura avanzada de ficheros: identificador opcional

Al remontar múltiples ficheros a diario, puedes necesitar marcar de forma adicional algunos archivos: añadir un comentario, algún identificador o quizá un número. Con una gran cantidad de archivos con nombre similares, puede ser complicado distinguirlos de un vistazo y encontrarlos rápidamente.

Para resolver esta necesidad, Splio te ofrece el identificador opcional en forma de un sufijo _<id> añadido a los nombres de ficheros. Los sufijos siempre se añaden al final (inmediatamente antes de la parte .csv, al igual que los prefijos se añaden al principio). Este sufijo está compuesto por un guion bajo seguido de caracteres alfanuméricos (letras y dígitos). Un archivo que lo incluya se puede resumir de la siguiente forma:

<universo>_<tabla>_<subsecuencia>_<fecha>_<id>.csv 

Todos los demás componentes de este nombre de archivo están explicados más arriba en la sección de nomenclatura de ficheros básica. Los siguientes ejemplos muestran tres nombres de ficheros. Observa cómo te ayuda el sufijo opcional a diferenciarlos.

miuniverso_contacts_clientes_20180315_updates.csv
miuniverso_contacts_clientes_20180315_altas.csv
miuniverso_orders_online_20180228_diario.csv

El identificador opcional no es procesado por Splio, es decir, no se debe tomar ninguna acción especial ante él. Sin embargo, Splio mantendrá intacto este identificador al mover los archivos a otras carpetas. También marcará los logs correspondientes con él.

Repositorio SFTP/FTP en Splio

El repositorio que has visto en la gráfica al principio de este artículo se ha creado como parte de la configuración de tu universo Splio. Tu Project Manager te proporcionará la dirección de tu FTP, un nombre de usuario y una contraseña. Si no sabes cómo configurar un client FTP tú mismo, pregunta al departamento IT de tu empresa.

⚠️ | Si después de registrarte, descubres que tu repositorio está vacío, contacta con tu Project Manager o con el servicio de atención al cliente de Splio. Puede que el Datahub necesite ser activado. 

Estructura del directorio

El repositorio FTP contiene una estructura establecida de carpetas utilizada para la automatización de las importaciones.

Dentro del repositorio, encontrarás la carpeta /imports. Esta contiene todas las demás carpetas. Este directorio es la ubicación donde debes colocar tu fichero de configuración, así como todos los ficheros que deseas importar.

Una vez finalizada la importación, el fichero importado se elimina de la carpeta /imports y, según el resultado de la importación, se coloca en una de las subcarpetas. Después se envía un informe a las direcciones de email indicadas en el fichero de configuración.

• /archives es la ubicación por defecto para los ficheros procesados. Si tu importación se completa con éxito, tu archivo importado se moverá allí.
• /badlines es donde van los ficheros que contienen líneas rechazadas (p. ej., líneas de archivos de contactos que no tienen clave única, de tiendas sin store_id, etc.).

• /bogus es la carpeta a la cual Splio mueve los ficheros que considera incorrectos. Si se te olvidó incluir una columna obligatoria o insertaste una que no existe, tu archivo CSV se moverá aquí.
• /logs es la ubicación para los ficheros de texto que contienen datos de control relativos a tus importaciones (dichos archivos son llamados ficheros de log o logs). Consulta la sección de Logging abajo.
• /notprocessed es donde Splio coloca los ficheros que no procesó.

Logging

Cuando se realiza una importación automática, Splio prepara archivos especiales de control (llamados ficheros de log o logs, de forma resumida) que enumeran los errores y eventos que ocurrieron durante la importación. Por cada fichero importado se crea un fichero de logs en la subcarpeta /imports/logs.

La siguiente tabla enumera los mensajes que puedes encontrar en un archivo de log, con una breve descripción de cada mensaje y sugerencias en caso de errores, si están disponible. Los placeholders entre paréntesis se sustituirán por los nombres y datos actuales del log.

Mensaje de log	Descripción
can't find universe "<universe>"	El nombre de fichero o la entrada en el archivo de configuración hace referencia a un universo de Splio que no existe. Se debe crear el universo o deberás comprobar si has utilizado un nombre de universo correcto.
can't find import with id <importid>	La importación no se ha configurado todavía.
can't find ftp account with id <ftpaccountid>	Splio no puede coger ficheros del protocolo FTP <ftpaccountid>. La importación no se ha configurado correctamente o no se ha configurado todavía.
can't open working directory "<workdir>"	Falta el directorio <workdir> (p. ej., ha sido eliminado) o hay un error en el sistema.
can't open file "<workdir/filename>"	El fichero falta o está dañado: revisa el archivo de importación y vuelve a cargarlo. Este mensaje también puede indicar un error en el sistema.
invalid JSON in "<universe>_imports_config.json"	Si ves este error, informa al equipo de Splio.
no configuration available for <scope> imports	Aparentemente tu archivo de configuración no contiene ninguna configuración para esta tabla. Si ves este error, informa al equipo de Splio lo antes posible.
can't find config for scope import named "<name>"	Si ves este error, informa al equipo de Splio lo antes posible.
missing mandatory configuration value "<field>"	Si ves este error, informa al equipo de Splio lo antes posible.
wrong format for configuration value "<$field>"	Si ves este error, informa al equipo de Splio lo antes posible.
can't parse file header	Este error normalmente se debe a la codificación incorrecta del archivo de importación. Asegúrate de que tu fichero tenga el formato de codificación UTF-8 sin BOM y vuelve a cargarlo.
(<filename>:<line>) can't parse line	Indica un problema con una línea específica del fichero. Deberías poder abrir el archivo y comprobar la línea indicada.