Integraciones

Cómo importar / exportar datos

Antes de empezar a importar datos en TicTAP, debes entender el modelo de datos. El modelo está compuesto por entities y definitions, que son totalmente dinámicos y pueden crearse o eliminarse en cualquier momento. Esto significa que el modelo de datos puede cambiar en cualquier momento.

Importación

Hay varias formas de importar o exportar datos en TicTAP. La más habitual es usar la API de integración. Esta API permite importar y exportar datos en formato json. También puedes importar y exportar datos en formato CSV de forma manual o automática.

Exportación

Modelo de datos

En TicTAP puedes crear un modelo de datos que se adapte a tus necesidades. El modelo de datos se compone de entities y definitions, que son totalmente dinámicos.

Entidades

TicTAP trabaja con entities. Cada entidad puede ser un activo o una taxonomía utilizada para categorizar activos, y dispone de un conjunto de campos que pueden rellenarse con datos.

Por ejemplo: una entidad puede ser una Pump (activo) con campos informados como el número de serie, el modelo, el fabricante, etc. O una entidad puede ser un Model con campos rellenados como el nombre, el fabricante, etc., y estar relacionada con una entidad bomba que contenga toda la información compartida entre todas las bombas de ese modelo.

Las entidades siempre tienen un name y una description que se consideran propios y están siempre presentes en cada entidad. Además, las entidades pueden tener opcionalmente un state para mantener su estado a lo largo del tiempo. Por ejemplo: si una entidad dinámica fuera una Task, el state podría ser "In progress", "Doing" o "Done".

Definiciones

Todos los campos que puede tener una entidad se describen en la definition. La definición describe el tipo de cada campo, el nombre del campo y otras propiedades. Además, una definición también define la estructura hija: qué entidades hijas pueden añadirse a la entidad.

Campos

Al editar campos en una definición, puedes definir las siguientes propiedades: cada campo tiene una propiedad name que lo identifica, una propiedad slug que es un identificador único para el campo y una propiedad type que identifica el tipo del campo. El tipo puede ser uno de los siguientes:

text: un campo de texto
email: un campo de correo electrónico
date: un campo de fecha
choice: un campo de elección con un conjunto predefinido de opciones
media: un campo multimedia que permite almacenar medios y que puede restringirse con file_type para permitir solo ciertos tipos de archivo, como image para restringir a imágenes o file para cualquier otro tipo de archivo.
media_collection: un campo de colección multimedia que permite almacenar una colección de medios.
address: un campo de dirección que permite almacenar una dirección como texto, además de latitud y longitud.
manifest_icon: es igual que un campo Media, pero se usa para almacenar el icono del manifiesto de la app.
dynamic_entity: este campo especial permite crear una relación unidireccional de muchos a uno desde la definición actual a otra definición. Por ejemplo: si nuestra definición "Asset" tiene un campo de entidad dinámica hacia la definición "Model", significa que muchos activos pueden relacionarse con un único modelo. Este campo es especial porque no es un campo que se rellene con datos, sino que permite crear una relación entre dos entidades.

API REST

La documentación de la API se encuentra en la página Api Docs.

Este artículo define los recursos disponibles en la API de integración de TicTAP. Si necesitas entender el modelo de datos que usa TicTAP, puedes leer el modelo de datos.

Token de acceso

Para acceder a la API es necesario disponer de un accessToken. Una vez lo tengas, debes incluirlo en cada petición como cabecera HTTP.

AccessToken: "AccessToken"

Si necesitas probar distintas llamadas a la API, puedes hacerlo desde la misma página de Api Docs usando el botón "authorize".

Definiciones

Al usar la API de integración, primero debes entender qué definiciones están disponibles y qué campos tiene cada una. Una vez tengas esa información, puedes usarla para crear o actualizar entidades con esas definiciones.

Listado de definiciones

Puedes obtener la lista de definiciones disponibles llamando al endpoint:

GET /api/integration/definitions

Este endpoint devuelve una lista de definiciones disponibles en tu Enterprise. Cada definición tiene una propiedad name que la identifica, una propiedad slug que es un identificador único y una propiedad fields que es una lista de campos.

Este es un ejemplo de respuesta:

{
  "pages": 11,
  "total": 51,
  "results": [
    {
      "name": "Fire extinguisher co2 5kg",
      "slug": "fire-extinguisher-co-2-5-kg"
    },
    {
      "name": "Ventilació extractors",
      "slug": "ventilacio-extractors"
    },
    {
      "name": "Facility",
      "slug": "facility"
    },
    {
      "name": "Bie",
      "slug": "bie"
    },
    {
      "name": "Pump",
      "slug": "pump"
    }
  ]
}

En el ejemplo anterior hay una lista de 51 definiciones, pero solo se devuelven 5. Esto se debe a que el endpoint devuelve las definiciones en páginas de limit elementos. Si quieres obtener la siguiente página puedes usar el parámetro page:

?page=1&limit=5

El número total de páginas siempre se devuelve en el parámetro pages.

Detalle de una definición

Para obtener la lista de campos que tiene una definición concreta, es necesario hacer una petición al detalle de su slug.

GET /api/integration/definitions/{slug}

Este es un ejemplo:

GET /api/integration/definitions/bie

// Response:
{
  "name": "Bie",
  "slug": "bie"
  "fields": [
    {
      "type": "text",
      "name": "Model",
      "required": false,
      "indexable": true,
      "slug": "model",
      "localized": false
    },
    {
      "type": "text",
      "name": "Product reference",
      "required": false,
      "indexable": true,
      "slug": "product-reference",
      "localized": false
    },
    {
      "type": "date",
      "name": "Date",
      "required": false,
      "indexable": false,
      "slug": "date",
      "localized": false
    },
    {
      "type": "text",
      "name": "Location",
      "required": false,
      "indexable": false,
      "slug": "location",
      "localized": false
    }
  ]
}

Cada campo tiene un slug, que lo identifica de forma única y se usará al crear o editar entidades de esa definición.

Cada campo también tiene un type que define el tipo de dato que se almacena en ese campo: text, choice, media, media_collection... Puedes encontrar una referencia de todos los tipos de campo en el modelo de datos.

Entidades

Crear una entidad

Una vez conocida la definición, podemos crear una entidad para esa definición:

POST /api/integration/definitions/{slug}/entities

Este es un ejemplo al crear una entidad para la definición bie:

POST /api/integration/definitions/bie/entities

// Request body:
{
    "name": "Bie 1",
    "values": { 
      "model": "Model 1",
      "product-reference": "Product reference 1",
      "date": "2020-01-01",
      "location": "Location 1"
    }
}

Cuando alguno de los campos es de tipo media o media_collection (por ejemplo documents), la petición debe usar el tipo de contenido multipart/form-data y el valor del campo debe ser un archivo.

En el siguiente ejemplo, el campo documents es de tipo media_collection y contiene una lista de archivos. El campo photo es de tipo media y es un único archivo.

POST /api/integration/definitions/bie/entities

AccessToken: {AccessToken}
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

------WebKitFormBoundary
Content-Disposition: form-data; name="name"

Bie 1
------WebKitFormBoundary
Content-Disposition: form-data; name="values[model]"

Model 1
------WebKitFormBoundary
Content-Disposition: form-data; name="values[photo]"
Content-Type: image/png

< /home/debian/pictures/photo.jpeg
------WebKitFormBoundary
Content-Disposition: form-data; name="values[documents][]"; filename="document1.png"
Content-Type: image/png

< /home/debian/documents/document1.pdf
------WebKitFormBoundary
Content-Disposition: form-data; name="values[documents][]"; filename="document2.pdf"
Content-Type: image/jpg

< /home/debian/documents/document2.pdf
------WebKitFormBoundary--

Actualizar una entidad

Al actualizar una entidad, la petición es la misma que al crearla, pero el método es PUT y el endpoint es:

PUT /api/integration/definitions/{slug}/entities/{id}

Los identificadores de las entidades son UUID. Este es un ejemplo al actualizar una entidad para la definición bie:

PUT /api/integration/definitions/bie/entities/a3f4509a-6060-4526-9bae-4a2cbd8f52b5

// Request body:
{
    "name": "Bie 1 updated",
    "values": { 
      "model": "Model 1 updated",
      "product-reference": "Product reference 1",
      "date": "2023-01-02",
      "location": "Location 1"
    }
}

Eliminar una entidad

Al eliminar una entidad, la petición es una petición DELETE al endpoint:

DELETE /api/integration/definitions/{slug}/entities/{id}

Referencia externa

Al crear o actualizar una entidad, es posible añadir una referencia externa a la entidad. Esto resulta útil cuando quieres vincular la entidad con un sistema externo. Por ejemplo, si tienes SAP y quieres vincular la entidad con un objeto concreto de SAP, puedes añadir el identificador de ese objeto como referencia externa.

La referencia externa es un string que debe ser único para la definición dada. Esto significa que si creas una entidad con una referencia externa, no puedes crear otra con la misma referencia externa.

La referencia externa se añade a la entidad en el campo external_reference. Por ejemplo:

POST /api/integration/definitions/bie/entities

// Request body:
{
    "name": "Bie 1",
    "external_reference": "SAP-1234",
    "values": { 
      "model": "Model 1",
      "product-reference": "Product reference 1",
      "date": "2020-01-01",
      "location": "Location 1"
    }
}

La referencia externa puede actualizarse al actualizar una entidad. Por ejemplo:

PUT /api/integration/definitions/bie/entities/a3f4509a-6060-4526-9bae-4a2cbd8f52b5

// Request body:
{
    "name": "Bie 1 updated",
    "external_reference": "SAP-UPDATED-1234",
    ...
}

IMPORTANTE: al actualizar una entidad y no informar external_reference, o si está vacío, la referencia externa actual se elimina de la entidad.

"Padre" de la entidad

Al crear o actualizar una entidad, es posible añadir un "parent" a la entidad. El padre se refiere a la entidad de nivel superior que contiene a la entidad. Por ejemplo, si tienes una definición facility y una definición room, la entidad room puede tener como padre una entidad facility. Para expresarlo a través de la API puedes añadir el campo parent_id a la entidad.

For example:

POST /api/integration/definitions/room/entities

// Request body:
{
    "name": "Room 1",
    "parent_id": "a3f4509a-6060-4526-9bae-4a2cbd8f52b5"
    ...
}

y también es posible usar la "external reference" de la entidad padre:

POST /api/integration/definitions/room/entities

// Request body:
{
    "name": "Room 1",
    "parent_id": "SAP-FACILITY-1234"
    ...
}

Esto también puede hacerse al actualizar una entidad, lo que provoca un "move" de la entidad a otro padre. Por ejemplo:

PUT /api/integration/definitions/room/entities/room-uuid

// Request body:
{
    "name": "Room 1",
    "parent_id": "SAP-ANOTHER-FACILITY"
    ...
}

IMPORTANTE: NO es posible dejar una entidad "orphan". Al actualizar una entidad y no informar parent_id, o si está vacío, el padre actual permanecerá sin cambios.

Importación de datos

Cómo importar datos a la plataforma

Importación manual con archivo CSV

En TicTAP puedes importar datos manualmente desde un archivo CSV. Esto es útil cuando quieres importar datos desde un sistema de terceros o desde una hoja de cálculo.

Importar desde la lista

El primer paso para importar datos desde un archivo CSV es ir a la lista de entidades de la definición cuyos datos quieres importar. Por ejemplo, si quieres importar datos para la definición bie, debes ir a la lista de entidades de la definición bie:

Una vez estés en la lista de entidades, debes hacer clic en el botón de importación:

Cuando haces clic en este botón, debes seleccionar un archivo CSV de tu ordenador. El archivo CSV debe tener una fila de cabecera con los nombres de los campos que quieres importar.

Mapear los campos

El sistema mostrará automáticamente un diálogo donde podrás asignar cada columna de tu archivo CSV a un campo de la definición. Si no asignas una columna, el sistema la ignorará.

Campos especiales

Hay algunos campos especiales que puedes asignar:

reference : este campo se usa para identificar la entidad. Si lo asignas, el sistema intentará encontrar una entidad con el mismo valor en el campo reference. Si el sistema encuentra una entidad con el mismo valor, la actualizará. Si no la encuentra, creará una entidad nueva.
parent entity: este campo permite importar la lista de entidades como un árbol. Si lo asignas, el sistema intentará encontrar un parent para cada una de las entidades importadas usando la reference del padre. Si encuentra una entidad padre con el mismo valor en el campo reference, la establecerá como padre de la entidad importada. Si no la encuentra, creará una nueva entidad sin padre.
Campos de medios: algunos campos del CSV pueden contener el nombre de un archivo. Si asignas un campo de tipo media, el sistema intentará encontrar un archivo con el mismo nombre en la biblioteca multimedia. Si lo encuentra, lo establecerá como valor del campo. Si no lo encuentra, devolverá un error de importación.

Importación de CSV mediante FTP

También puedes importar archivos CSV usando SFTP: para ello, el equipo de TicTAP creará una carpeta en el servidor FTP ( sftp://ftp.tictap.me ) con una carpeta inbox y otra outbox.

Antes de nada, el equipo de TicTAP debe crear una configuración de known mapping. Esta configuración permite al sistema saber qué columna de tu CSV corresponde a qué campo de la definición.

Uso de `.lock`

Para que el sistema sepa que has subido datos a la carpeta inbox, se usa un semáforo de la siguiente manera:

Debes subir un archivo llamado .lock. Este archivo se usa para evitar que el sistema procese el archivo mientras todavía lo estás subiendo.
Después subes un archivo llamado .csv. Este archivo es el CSV que quieres importar.
Si el archivo .csv tiene campos media, también debes subir los archivos multimedia a la carpeta inbox/media. Cada archivo multimedia debe tener el mismo nombre que el valor del campo media en el CSV.
Elimina el archivo .lock.

Cuando eliminas el archivo .lock, el sistema empezará a procesar el archivo .csv y los archivos multimedia. Primero subirá cada archivo multimedia a la biblioteca multimedia. Después importará el CSV.

Muchos archivos CSV

Es posible subir varios archivos relacionados entre sí. Por ejemplo, podríamos subir una lista de entidades bie y que cada una tuviera una relación con una entidad model. En ese caso, debemos subir los CSV en el siguiente orden:

Sube el archivo .lock.
Sube el archivo .csv con las entidades bie.
Sube el archivo .csv con las entidades model.
Sube los archivos multimedia.
Elimina el archivo .lock.

Uso de la carpeta de salida

Cuando el sistema termina de procesar el archivo CSV, registra el resultado en la carpeta outbox. El resultado será un archivo llamado {csv_file}.log con el mismo nombre que el CSV que subiste. Este archivo contendrá el resultado del proceso de importación. Si el proceso fue correcto, contendrá la lista de entidades creadas o actualizadas. Si falló, contendrá la lista de errores.

Además, también es posible configurar la creación de ciertos archivos .csv de salida en la carpeta outboux bajo determinados eventos. Por ejemplo, el sistema podría crear un archivo .csv cada vez que una entidad se haya edited o marcado como end of life, o cuando se haya created una nueva entidad, y muchos otros eventos compatibles, como reminder_created, state_changed, submission_received...

En la fase de integración, el equipo de TicTAP creará la configuración adecuada para decidir bajo qué events debe crearse la información en la carpeta outbox.

Importación del espacio de trabajo

La función de importación de TicTAP permite añadir activos dentro de un workspace importando una jerarquía estructurada desde un nodo específico y todos sus hijos (todo el árbol descendiente). También es posible importar directamente en el nodo raíz del workspace (nivel 0).

Paso 1: Exportar la estructura de ejemplo

Para entender la estructura requerida para la importación, primero exporta un archivo Excel de ejemplo desde un workspace existente. Al abrir el archivo exportado, puedes ver:

La jerarquía de nodos con sus nombres.
El nivel que ocupa cada nodo (0 para location, 1 para category, 2 para articles).
El tipo de activo asociado a cada nodo (por ejemplo, location, category, article).

Estructura de ejemplo en Excel:

Level 0	Level 1	Level 2	Type	Reference	State	Photo Reference	Photo	Quantity
Calabria			Location	123
Calabria	Material envíos TicTAP		Category	1234
Calabria	Material envíos TicTAP	Bolsas PE Autocierre 12x18	Article	12345	ok	87914	bolsas.JPG	49

Import preview showing nodes and number of items per category

Paso 2: Subir el archivo a importar

To start the import:

Select the node within which you want to import assets (e.g., the root node "Calabria" or any child node at level 1).
Use the option to import CSV or Excel file.
Select the exported or compatible structure file.

When loading the file, a window appears to select the CSV/XLSX file.

File selection screen for CSV / XLSX import

Paso 3: Vista previa de la importación

The system shows a preview with a summary tree:

Total number of detected items (e.g., 36 items).
Distribution by type (Location, Category, Article).
Ability to select which parts you want to import.

Summary of elements detected in the file before importing

Paso 4: Mapeo de campos

Next, map each column in the file to the system fields for each asset type.

For example, for the Article type, you can map:

Item level (Level 2)
Name / Reference
Last Used date
Photo (associated reference)
Quantity
Supplier
Minimum/maximum stock
Stock unit cost

Example of mapping CSV columns to asset fields for import

Notas clave

Para propiedades relacionadas con otros activos (foto, proveedor, etc.) usa la referencia para evitar duplicados.

El archivo debe tener datos planos sin fórmulas; se recomienda CSV para evitar problemas.

Admite la importación de URLs para imágenes y documentos PDF (fichas técnicas).

El sistema descarga y asigna estas URLs al activo durante la importación.

Exportación de datos

Cómo exportar datos desde la plataforma

Exportación manual de archivo CSV

Es posible exportar muchas listas en formato CSV. En TicTAP se pueden exportar las siguientes listas:

Entidades: esta lista contiene todas las entidades de un tipo concreto. Por ejemplo, todas las entidades bie.
Envíos de formularios: esta lista contiene todos los envíos de formularios enviados por los usuarios en un periodo de fechas.
Etiquetas: esta lista contiene todas las etiquetas, que pueden ser etiquetas NFC o códigos QR.

Exportar entidades

Para exportar entidades de una definición concreta, puedes hacerlo desde la lista de entidades. En la esquina superior derecha de la lista hay un botón para exportarla en formato CSV.

Cuando haces clic en el botón, el navegador descargará un archivo CSV con las entidades de la lista y todos sus campos. Estas son las columnas que encontrarás en el archivo CSV:

reference indica la referencia de la entidad. La referencia es un identificador único que se usa para referenciar la entidad desde sistemas externos.
name indica el nombre de la entidad. Si la entidad no tiene nombre, la columna estará vacía.
Campos localizados se exportarán en distintas columnas, una por cada idioma. Por ejemplo, si la entidad tiene un campo llamado job position y está localizado, el CSV tendrá una columna job position en y otra job position es (para inglés y español respectivamente).
tag codes indica las etiquetas NFC o códigos QR asociados a la entidad. Si la entidad no tiene una etiqueta NFC o un código QR asociado, la columna estará vacía.
tag skus indica las etiquetas NFC o los códigos QR SKU asociados a la entidad. Si la entidad no tiene una etiqueta NFC o un código QR asociado, la columna estará vacía.
parent indica la entidad padre de la entidad. Si la entidad no tiene padre, la columna estará vacía.
parent reference indica la referencia del padre de la entidad. Si la entidad no tiene padre, la columna estará vacía.
EOL significa "fin de vida útil" y es una fecha que indica cuándo se archivó la entidad. Si la entidad no está archivada, la columna estará vacía.
created indica cuándo se creó la entidad.
updated indica cuándo se actualizó la entidad.

Este es un ejemplo de un archivo CSV con las entidades de la definición bie:

Exportar envíos de formularios

Puedes exportar los envíos de formularios desde la página Analytics/Forms, haciendo clic en el enlace Download data. Los datos filtrados se descargarán en formato CSV.

El formato CSV de los envíos incluye cada etiqueta de bloque usada en las plantillas y los valores rellenados en cada envío. Cada fila del CSV incluirá:

__form : el nombre del formulario
__date : la fecha del envío
__frontUser : el nombre del usuario, cuando el formulario fue enviado por un usuario frontal. Si lo envió un usuario anónimo, el valor estará vacío.
__tagName : el SKU o código de la etiqueta, cuando el formulario se envió escaneando una etiqueta

Exportar etiquetas

También puedes exportar una lista de etiquetas desde la vista de etiquetas. En la esquina superior derecha de la lista hay un botón para exportar CSV.

Cuando haces clic en el botón, el navegador descargará un archivo CSV con las etiquetas de la lista y todos sus campos. El CSV tendrá las siguientes columnas:

name indica el nombre de la etiqueta.
sku indica el SKU de la etiqueta.
url indica la URL de la etiqueta.
description indica la descripción de la etiqueta.
registration date indica la fecha en que se registró la etiqueta.
registered by indica el usuario que registró la etiqueta.
labels indica las etiquetas asociadas.

Webhooks

Los webhooks permiten informar a aplicaciones de terceros cada vez que ocurre algo en TicTAP. Por ejemplo, cada vez que se envía un formulario, vence un recordatorio, un activo llega al fin de su vida útil o pasa de un estado a otro, etc.

Los webhooks aportan flexibilidad en los casos en los que se desea que se realice una acción cuando ocurren determinados eventos en TicTAP.

Exportar PDF

Exportar PDF desde un envío de formulario

Cuando un formulario está configurado como informe, es posible exportar el envío del formulario como un archivo PDF. Para hacerlo, debes

Ir a la lista de envíos del formulario
Pulsar el botón "Report" en el envío del formulario que quieras exportar

También puede hacerse desde la vista de detalle del envío del formulario, pulsando el botón "Report" en la esquina superior derecha de la página.

Cuando haces clic en el botón, el navegador descargará un archivo PDF con los datos del envío del formulario.

Informes de entidades

Desde la vista de espacio de trabajo, cuando hay informes configurados para una entidad, es posible exportar el informe de la entidad como PDF. Para hacerlo, debes:

Ir a la vista de detalle de la entidad
Pulsar el botón "Report" en la esquina superior derecha de la página
Configurar el rango de fechas para el informe: esto permitirá incluir todos los envíos de formularios enviados a una entidad concreta dentro de un rango de fechas.
Pulsar el botón "Generar informe"

Cuando haces clic en el botón, el navegador descargará un archivo PDF recién generado con el informe de la entidad.

Cómo importar / exportar datos

Importación​

Exportación​

Modelo de datos

Entidades​

Definiciones​

Campos​

API REST

Token de acceso​

Definiciones​

Listado de definiciones​

Detalle de una definición​

Entidades​

Crear una entidad​

Actualizar una entidad​

Eliminar una entidad​

Referencia externa​

"Padre" de la entidad​

Importación de datos

Importación manual con archivo CSV

Importar desde la lista​

Mapear los campos​

Campos especiales​

Importación de CSV mediante FTP

Uso de .lock​

Muchos archivos CSV​

Uso de la carpeta de salida​

Importación del espacio de trabajo

Paso 1: Exportar la estructura de ejemplo​

Paso 2: Subir el archivo a importar​

Paso 3: Vista previa de la importación​

Paso 4: Mapeo de campos​

Notas clave​

Exportación de datos

Exportación manual de archivo CSV

Exportar entidades​

Exportar envíos de formularios​

Exportar etiquetas​

Webhooks

Exportar PDF

Exportar PDF desde un envío de formulario​

Informes de entidades​

Importación

Exportación

Entidades

Definiciones

Campos

Token de acceso

Definiciones

Listado de definiciones

Detalle de una definición

Entidades

Crear una entidad

Actualizar una entidad

Eliminar una entidad

Referencia externa

"Padre" de la entidad

Importar desde la lista

Mapear los campos

Campos especiales

Uso de `.lock`

Muchos archivos CSV

Uso de la carpeta de salida

Paso 1: Exportar la estructura de ejemplo

Paso 2: Subir el archivo a importar

Paso 3: Vista previa de la importación

Paso 4: Mapeo de campos

Notas clave

Exportar entidades

Exportar envíos de formularios

Exportar etiquetas

Exportar PDF desde un envío de formulario

Informes de entidades