Cómo interpretar el resultado de tu backup

Cuando finaliza el backup de tu cuenta, recibes un conjunto de archivos JSON y tus archivos adjuntos originales, empaquetados en archivos ZIP (divididos y cifrados opcionalmente según tu configuración). Este artículo explica qué contiene ese paquete, cómo se organizan los datos y cómo leerlos.

Si aún no has ejecutado un backup, empieza por Descripción general del backup de datos, donde se explican las opciones de almacenamiento disponibles.

Cómo se empaqueta el backup

Tu backup refleja las categorías de datos que seleccionaste durante la configuración. Después de descomprimir el paquete, verás un archivo para los datos de usuarios y grupos, una carpeta para los datos transaccionales y otra para los logs de auditoría, además de un índice de flujos y un archivo readme:

A grandes rasgos, esta es la función de cada parte:

Debes tener en cuenta lo siguiente:

• Tus registros se almacenan como archivos JSON (texto sin formato), excepto los archivos adjuntos, que se conservan como sus archivos originales (PNG, PDF, XLSX, etc.). El paquete también incluye un par de archivos auxiliares en otros formatos: un índice de flujos en CSV y un archivo Readme.txt, ambos descritos más adelante.
• La mayoría de los archivos JSON contienen una única matriz de registros. Los logs de auditoría son la excepción: utilizan JSON Lines (un objeto por línea). Lo indicamos nuevamente en la sección de auditoría porque esto cambia la forma de abrir esos archivos.
• El sufijo -0000 es un número de lote. Las cuentas grandes dividen sus datos transaccionales en varias carpetas de lotes (TransactionalData-0000, TransactionalData-0001, etc.). La mayoría de los flujos se encuentran completamente en un solo lote, pero los datos de un flujo muy grande pueden distribuirse en varios. Usa el índice de flujos para encontrar la ubicación principal de un flujo; si un flujo es grande, revisa también las demás carpetas de lotes para localizar el mismo Flow ID. Los datos de usuarios y grupos siempre se encuentran en un solo archivo, sin sufijo de lote.
• El backup es una exportación de datos, no una base de datos restaurable. Está diseñado para leer, archivar y analizar datos, no para volver a importarlos en Kissflow.

Cómo usar los datos de tu backup

Como todo está en formato JSON abierto, puedes trabajar con los datos en la herramienta que prefieras. Estos son algunos usos habituales:

• Auditoría y cumplimiento: lee los logs de auditoría para generar un registro de la actividad de la cuenta durante un período de revisión. Agrupa los eventos relacionados mediante BatchID.
• Informes y análisis: carga el archivo <Flow ID>.json de un flujo en una hoja de cálculo, una herramienta de BI o un script para analizar tus registros fuera de Kissflow.
• Archivado: conserva el paquete como una copia a largo plazo y sin conexión de los datos de tu cuenta, independiente de la plataforma.
• Volver a conectar las partes: relaciona los registros con las personas mediante el _id de UserAndGroup.json, y los registros con los archivos adjuntos mediante los nombres de las carpetas de ID de registro que se encuentran en Attachments.

Ejemplos prácticos

Estas breves explicaciones muestran cómo los ID conectan los archivos.

¿Quién eliminó un grupo? Encuentras un grupo con _is_deleted: true en UserAndGroup.json (por ejemplo, _id: "Gr5f_Tu24tkp", el grupo Operations Department). Consulta el bloque _modified_by de esa misma entrada. En él aparece el autor de la acción, por ejemplo _id: "Us4YeHqN_4jb". Busca ese ID en otra parte de UserAndGroup.json para confirmar que se trata de Steve Rogers, el administrador que lo eliminó.

¿Quién está detrás de una entrada del log de auditoría? El campo Object de una línea de auditoría tiene el formato id -- name (por ejemplo, Us7OHZJLfP2E -- Jane Doe). Toma el ID que aparece antes de --, búscalo en UserAndGroup.json y obtendrás el perfil completo: su estado, departamento y tipo.

¿Quién envió un registro? Abre el registro en el archivo <Flow ID>.json del flujo (no en el archivo _Users.json, que solo indica quién tenía acceso). Lee el objeto _created_by del registro, toma su _id y búscalo en UserAndGroup.json para revelar la identidad completa, incluido su UserType.

Aspectos importantes

• Esta exportación sirve para leer y archivar, no para volver a importar datos en Kissflow.
• Si elegiste Email como modo de almacenamiento, recibirás tu backup mediante un enlace de descarga. Descárgalo en un plazo de siete días, ya que el enlace caduca después de ese período y tendrás que ejecutar un nuevo backup para obtener otra copia.
• Es posible que las claves de los campos no coincidan con las etiquetas de la aplicación, y no existe ningún archivo de esquema. Cuando una clave no sea clara, comprueba la aplicación activa.
• Los logs de auditoría abarcan únicamente aproximadamente el último año.

Si tienes alguna pregunta sobre los datos de tu backup, contacta con el equipo de soporte.

Abrir un backup cifrado

Si estableciste una frase de contraseña, tus archivos llegarán como archivos ZIP cifrados (.aes256cbc), uno por módulo, con nombres como TransactionalData-0000.aes256cbc. Debes descifrar cada uno antes de poder leerlo.

1. Instala OpenSSL en tu equipo si aún no lo has hecho.

2. Para cada archivo cifrado, ejecuta:

   openssl enc -aes-256-cbc -d -salt -iter 10 -in "<encrypted-file>" -out "<output-file>.zip" -k "<passphrase>"

   Por ejemplo:

   openssl enc -aes-256-cbc -d -salt -iter 10 -in "TransactionalData-0000.aes256cbc" -out "TransactionalData-0000.zip" -k "SamplePhrase"

3. Descomprime los archivos .zip resultantes para obtener las carpetas y los archivos JSON descritos en el resto de este artículo.

Datos de usuarios y grupos

Archivo: UserAndGroup.json

Una única matriz JSON que contiene todas las identidades de tu cuenta: usuarios, usuarios externos, cuentas de servicio, roles y grupos. Cada entrada es un objeto, y el campo Kind indica de qué tipo es.

Tipos de identidad (el campo Kind)

Campos útiles de un usuario

Encontrar un flujo: el índice de flujos

Tu backup incluye un índice de flujos, un archivo CSV (por ejemplo, flows.csv) que muestra todos los flujos de tu cuenta. Es la forma más rápida de localizar los datos de un flujo específico, especialmente cuando tus datos transaccionales abarcan varias carpetas de lotes.

Cada fila tiene cinco columnas:

Para encontrar los datos de un flujo, busca su nombre en el índice y abre <File location>/<Flow type>/<Flow ID>/. Por ejemplo, un Process llamado «Leave Management», con Flow ID Leave_Management y ubicado en TransactionalData-0001, se encuentra en TransactionalData-0001/Process/Leave_Management/.

Datos transaccionales

Carpeta: TransactionalData-0000/ (y -0001, -0002, etc. para cuentas grandes)

Esta es la parte más grande de tu backup. Contiene los registros reales (elementos) de tus flujos, junto con sus comentarios y archivos adjuntos. Los datos se organizan primero por tipo de flujo y después por flujo. Los cinco tipos de flujo son Process, Board, Dataset, Form y Project.

Cada carpeta de flujo recibe como nombre su Flow ID (el valor que aparece en el índice de flujos) y es independiente. Abre <Flow ID>.json para leer los registros, <Flow ID>_Users.json para ver quién tenía acceso y las subcarpetas Comment y Attachments para consultar los elementos adjuntos a esos registros.

Qué contiene el archivo de registros

<Flow ID>.json es una matriz de registros. Todos los registros comparten un conjunto común de campos del sistema y, después, incluyen los campos específicos de ese flujo.

Campos del sistema que encontrarás en casi todos los registros:

Los campos restantes contienen tus datos y varían según el módulo. Esto es lo que puedes esperar de cada uno.

Registros de Process

Los registros de Process contienen el estado completo del flujo de trabajo, no solo los valores del formulario. Además de los campos del formulario, encontrarás:

• ProcessInstance y ActivityInstance: objetos anidados que describen la ejecución del flujo de trabajo, la actividad actual y el historial.
• _status: estado del elemento (por ejemplo, Completed).
• _stage, _current_step, _current_assigned_to, _last_completed_step: posición del elemento en el flujo y persona que lo tiene asignado.
• _request_number: número de solicitud legible para las personas.
• _submitted_at, _completed_at: marcas de tiempo del proceso.

Registros de Board

Los registros de Board (casos) describen una tarjeta y su posición en el board:

• CaseWorkflowInstance: objeto de flujo de trabajo del caso.
• _status_id / _status_name: columna en la que se encuentra la tarjeta.
• _priority_name, _priority_sequence: prioridad.
• ItemType, _category, _is_draft: clasificación y estado de borrador.

Registros de Dataset

Los Dataset son los más sencillos. Cada registro es una fila plana con tus campos y los campos del sistema:

• _order: posición de la fila en el dataset.
• Name y las columnas de tus propios campos.

No contienen datos de flujo de trabajo porque los dataset almacenan datos de referencia y no pasan por un flujo de trabajo.

Registros de Form

Los registros de Form también son filas planas de valores de campos. Es posible que veas claves de campos con un sufijo numérico (por ejemplo, Status_1, Use_case_1), que es la forma en que se almacenan los campos de formulario repetibles. Un campo _visited indica si se abrió el formulario.

Registros de Project (obsoleto)

Los registros de Project se parecen a los registros de Process, pero utilizan objetos de flujo de trabajo específicos de los proyectos:

• ProjectFlowInstance y StepInstance: el flujo de trabajo del proyecto y sus pasos.
• _current_step_name, _current_step_id, _entered_at: posición actual.
• _counter, _item_id: identificadores.

Comentarios

Archivo: <Flow ID>/Comment/Comment.json

Los comentarios realizados en los registros se almacenan aquí, separados de los propios registros. Cada comentario incluye:

• Content: el comentario como un árbol estructurado de texto enriquecido, con un campo RawContent que proporciona la versión de texto sin formato.
• AtMention y las menciones dentro de Content: personas etiquetadas en el comentario, con su _id y Name.
• Reactions, Status, AssignedTo, _created_by, _created_at: reacciones, estado abierto o cerrado, asignación y autoría.

Comment.json se organiza por registro: el _id de cada objeto de nivel superior coincide con el _id del registro al que pertenecen los comentarios, por lo que así puedes volver a vincular un hilo de comentarios con su registro. Dentro de un comentario, EntityType y EntityId indican dónde está anclado el comentario en el elemento (por ejemplo, una actividad o un paso específicos), no el registro en sí.

Archivos adjuntos

Carpeta: <Flow ID>/Attachments/

Los archivos adjuntos se conservan como sus archivos originales y con sus nombres originales, dentro de carpetas cuyos nombres son ID internos para que cada archivo pueda vincularse con el registro del que procede. La estructura suele ser la siguiente:

Attachments/
└── <record ID>/
    └── <instance ID>/
        └── <attachment ID>/
            └── original_file.png

El nombre de la carpeta superior es el _id del registro. Para saber a qué registro pertenece un archivo adjunto, compara el nombre de esa carpeta con el _id de <Flow ID>.json. Las carpetas internas son referencias internas que Kissflow utiliza para mantener la unicidad de cada archivo; no las necesitas para localizar el registro.

Datos del log de auditoría

Carpeta: AuditLogs-0000/

Los logs de auditoría se dividen en numerosos archivos numerados (AuditLog_000000000000.json, AuditLog_000000000001.json, etc.). Estos archivos utilizan el formato JSON Lines: un objeto JSON por línea, no una única matriz. Léelos línea por línea en lugar de analizar todo el archivo como un solo objeto.

Cada línea representa un evento:

Interpretar los nombres y valores de los campos

Esto es lo más importante que debes entender antes de empezar a trabajar con tus datos.

Las claves de tus registros son ID internos de campos y no siempre coinciden con las etiquetas que ves en la aplicación. La mayoría coincide con la etiqueta (por ejemplo, Advance_Amount), pero algunas no:

• Un campo al que nunca cambiaste el nombre puede aparecer como Untitled_Field o Untitled_field.
• Un campo cuyo nombre cambiaste conserva su clave interna original. Si cambiaste el nombre de «Description» después de crearlo, los datos podrían seguir utilizando una clave como _1643035136_Description.
• Los campos repetibles llevan sufijos numéricos (Status_1).

El backup no incluye un esquema ni un diccionario de datos. No existe ningún archivo que asigne cada clave de campo a su etiqueta, tipo o sección de formulario actuales. Por eso, si una clave no es clara, la forma más fiable de identificarla es comparar el registro con el mismo elemento en la aplicación activa.

Esto puede añadir cierta dificultad, así que conviene saberlo antes de que las claves te sorprendan.

Formatos de valores habituales

Hay un par de estructuras de valores que se repiten en todas partes, por lo que vale la pena aprenderlas una vez.

Las fechas son objetos, no cadenas de texto simples:

"_created_at": {
  "v": { "$date": "2022-01-11T07:09:09.857Z" },
  "dv": "2022-01-11T07:09:09Z",
  "tz": "GMT",
  "td": ""
}

Usa dv para obtener un valor de visualización limpio, o $date dentro de v cuando necesites una precisión exacta. No son idénticos: v.$date conserva los milisegundos (...09.857Z), mientras que dv los omite (...09Z); por eso, usa v.$date para trabajos de coincidencia exacta o deduplicación. Ambos están en UTC; los campos tz y td describen la zona horaria original y normalmente pueden ignorarse. Si analizas los datos en Power BI o SQL, dirige tu función a la cadena $date interna.

Las personas (usuarios y grupos) aparecen como objetos:

"_created_by": { "_id": "UsJ35GmWEn3zP", "Name": "Tony Stark", "Kind": "User" }

El _id coincide con una entrada de UserAndGroup.json, por lo que siempre puedes resolver una referencia y obtener el registro completo de un usuario o grupo.

Qué hacer a continuación

• Descripción general del backup de datos
• Cumplimiento e historial del backup
• Roles y permisos de usuario