Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 40 Current »

Visión general

La API v1 RESTful es la vía de comunicación de Athento para conectar con toda la funcionalidad del sistema. Provee un modelo unificado de llamadas para cualquier tipo de operación sobre el modelo documental ofreciendo flexibilidad y seguridad.

Cómo usar la API v1

La API v1 de Athento es una RESTful Web API que permite acceder a todas las funcionalidades del modelo documental de Athento.

Uso rápido

A continuación se listan los endpoints actuales de la API v1.

Modo

Endpoint

Descripción

Documento

POST

/api/v1/file/

Crea un nuevo documento.

GET

/api/v1/file/{uuid}/

Obtiene un documento en formato JSON indicando su uuid.

PUT

/api/v1/file/{uuid}/

Modificación un documento indicando su uuid.

DELETE

/api/v1/file/{uuid}/

Elimina un documento indicando su uuid.

GET

/api/v1/file/{uuid}/download/

Descarga el contenido de un documento.

POST

/api/v1/file/{uuid}/lifecycle/transition

Ejecuta una transición sobre el ciclo de vida de un documento.

Búsqueda

POST

/api/v1/search/query

Busca documentos ejecutando una query ATQL y obteniendo los documentos como entidad.

POST

/api/v1/search/resultset

Busca documentos ejecutando una query ATQL y obteniendo las columnas incluidas en la cláusula SELECT.

Usuario

POST

/api/v1/user/

Crea un nuevo usuario.

GET

/api/v1/user/{username}/

Obtiene un usuario en formato JSON indicando su username.

PUT

/api/v1/user/{username}/

Modifica un usuario existente.

POST

/api/v1/user/{username}/activate

Activa un usuario.

POST

/api/v1/user/{username}/deactivate

Desactiva un usuario.

Grupo

POST

/api/v1/group/

Crea un nuevo grupo.

GET

/api/v1/group/{name}/

Obtiene un grupo en formato JSON indicando su name.

Acceda a Athento Explorer

Use Athento Explorer para poder gestionar las llamadas a los endpoints de la API v1 en la ruta /api/v1/explorer de su instancia. Por ejemplo en https://demo.athento.com/api/v1/explorer.

Para usar Athento Explorer debe iniciar sesión.

 

Especificaciones generales

Formatos

Cabeceras

Nombre

Valores

Opcional

Content-Type

application/json

multipart/form-data

False

Fetch-Mode

default

extended

full

True

Descripción

  • Content-Type: es el tipo de contenido que se usará en las llamadas a la API v1.

  • Fetch-Mode: es el tipo modo de obtención de la entidad que se pretende consultar donde:

    • default: es la obtención por defecto, con la información mínima suficiente.

    • extended: obtención extendida de la entidad y sus relaciones, donde se informa de atributos más destacados de la misma.

    • full: obtención completa de la entidad y sus relaciones.

Petición

{
   "<KEY>": "<VALUE>",
   "<OBJECT>": {
       "<KEY>": "<VALUE>",       ...
   }
}

Respuesta

El formato de respuesta de la API v1 tendrá siempre un formato estándar representado con tipo de contenido JSON y con la siguiente estructura:

{
   "request-id": "<UUID>",
   "response": {
       "message": "<EXECUTION MESSAGE>",
       "code": <EXECUTION CODE>
   },
   "result": {
      "entity": "<ENTITY>",
       <REST OF JSON RESPONSE>
   }
}

Documento — Document Entity

El documento es la pieza fundamental de almacenamiento en Athento. La API v1 ofrece la posibilidad de operar con ellos para crear, modificar, eliminar y consultarlos.

A continuación se muestra la representación de un documento por defecto.

{
    "entity": "Document",
    "uuid": "a8b16f41-65a0-481c-bb1a-e094011fee14",
    "filename": "PDF-Athento.pdf",
    "creation_date": "2022-12-07T16:45:03.302424+01:00",
    "modified_date": "2022-12-07T16:45:06.048175+01:00",
    "state": "pending",
    "version": "0.0",
    "author": "benchmark",
    "serie": "my_space",
    "doctype": "my_form",
    "container": false,
    "file": {
        "url": "uploads/.../2d/9c/2d9c09cdb21fd0a56eefd627240d554f.pdf",
        "extension": ".pdf",
        "hash": "2d9c09cdb21fd0a56eefd627240d554f",
        "size": 34073,
        "content_type": "application/pdf"
    },
    "life_cycle_state": "started"
}

 

Cuando un documento tiene contenido binario, el atributo file aparece en la representación de la entidad. Otros elementos como el life_cycle_state, etc. se comportan del mismo modo.

Crear un documento

Llamada genérica de creación:

POST https://demo.athento.com/api/v1/file/

 

Crear documento

Un documento en Athento es una entidad de un cierto tipo documental, o también llamado formulario, que se aloja en un Espacio —también llamado Serie documental— concreto. Dicho documento, puede tener o no un contenido principal —archivo binario— asociado. En este caso, comenzamos con la creación de un documento de Athento, donde no se especifica un binario asociado.

POST /api/v1/file/

Content-Type: application/json

Petición:

{
    "filename": "My new document name",
    "doctype": "MyFormType",
    "serie": "MySerie",
    "metadata": {
        "metadata.contract_number": "12345"
    } 
}

 Respuesta:

{
    "request-id": "1f1ec0af-aa65-4d44-942f-48ae8eecb639",
    "response": {
        "message": "Execution success",
        "code": "ok"
    },
    "result": {
        "entity": "Document",
        "uuid": "f1f0d872-f32f-4585-8a47-a59f6ed02b0b",
        "filename": "My new document name",
        "creation_date": "2022-12-24T10:17:56.251169+01:00",
        "modified_date": "2022-12-24T10:17:56.835331+01:00",
        "state": "pending",
        "version": "0.0",
        "author": "admin",
        "serie": "MySerie",
        "doctype": "MyFormType",
        "container": false,
        "life_cycle_state": "Inicio"
    }
}

Crear documento con contenido

A continuación el servicio de creación de nuevo documento con un binario asociado.

POST /api/v1/file/

Content-Type: multipart/form-data

Petición:

{
  "filename": "My new document name",
  "serie": "MySerie",
  "doctype": "MyFormType",
  "metadatas": {
      "metadata.contract_number": "12345"
  }, 
  "file": <File> 
}

Respuesta:

{
    "request-id": "7d20a5e6-cb1b-4949-abcf-51ecf99939f9",
    "response": {
        "message": "Execution success",
        "code": "ok"
    },
    "result": {
        "entity": "Document",
        "uuid": "0bbc79ba-6b14-4074-8f8e-6701a4ec995a",
        "filename": "My new document name",
        "creation_date": "2022-12-26T20:00:02.448476+01:00",
        "modified_date": "2022-12-26T20:00:03.227150+01:00",
        "validation_date": null,
        "validator": null,
        "state": "pending",
        "version": "0.0",
        "author": "admin",
        "serie": "MySerie",
        "doctype": "MyFormType",
        "container": false,
        "file": {
            "url": "uploads/Athento_ysvozgijse/Contratos_msphd/2d/9c/2d9c09cdb21fd0a56eefd627240d554f_e2jQcGS.pdf",
            "extension": ".pdf",
            "hash": "2d9c09cdb21fd0a56eefd627240d554f",
            "size": 34073,
            "content_type": "application/pdf"
        },
        "life_cycle_state": "Inicio"
    }
}

Crear documento a partir de plantilla

Creación de un documento a partir de una plantilla. En primer (por defecto) o segundo plano.

POST /api/v1/file/

Content-Type: multipart/form-data

Nombre

Valores

Opcional

template

Nombre o UUID de la plantilla

True

background

Realizar la generación del binario en segundo plano
true|false

True

Petición:

{
  "filename": "My new document name",
  "serie": "MySerie",
  "doctype": "MyFormType",
  "template": "MyTemplate",
  "background": true|false,
  "metadata": {
        "metadata.contract_number": "12345"
    }
}

Respuesta:

{
    "request-id": "7d20a5e6-cb1b-4949-abcf-51ecf99939f9",
    "response": {
        "message": "Execution success",
        "code": "ok"
    },
    "result": {
        "entity": "Document",
        "uuid": "0bbc79ba-6b14-4074-8f8e-6701a4ec995a",
        "filename": "My new document name",
        "creation_date": "2022-12-26T20:00:02.448476+01:00",
        "modified_date": "2022-12-26T20:00:03.227150+01:00",
        "validation_date": null,
        "validator": null,
        "state": "pending",
        "version": "0.0",
        "author": "admin",
        "serie": "MySerie",
        "doctype": "MyFormType",
        "container": false,
}

Actualizar un documento

Llamada genérica de actualización:

PUT https://demo.athento.com/api/v1/file/{file-uuid}/?{rest—query}

 

Actualizar documento

Para actualizar un documento, se hace uso del identificador del mismo y los atributos o metadatos asociados que pretenden actualizarse.

PUT /api/v1/file/{file-uuid}/

Content-Type: application/json

Petición:

{
    "filename": "New name",
    "metadata": {
        "metadata.contract_number": "12345"
    }
}

Respuesta:

{
    "request-id": "ebcc21ca-893c-4f34-9e8b-90a3c87edb1d",
    "response": {
        "message": "Execution success",
        "code": "ok"
    },
    "result": {
        "entity": "Document",
        "uuid": "77bd8d16-66bb-45fd-ace4-638257f665b8",
        "filename": "New name",
        "creation_date": "2022-12-26T20:07:23.321660+01:00",
        "modified_date": "2022-12-26T20:07:24.017370+01:00",
        "validation_date": null,
        "validator": null,
        "state": "pending",
        "version": "0.0",
        "author": "admin",
        "serie": "MySerie",
        "doctype": "MyFormType",
        "container": false,
        "life_cycle_state": "Inicio"
    }
}

Actualizar contenido

La actualización del contenido de un documento, donde se le asociad un archivo binario.

Nombre

Valores

Opcional

Content-Type

multipart/form-data

False

 

PUT /api/v1/file/{file-uuid}/

Content-Type: multipart/form-data

Nombre

Valores

Opcional

file-uuid

Identificador del documento a modificar.

False

Petición:

"file": <File> 

Respuesta:

{
    "request-id": "23bbefc6-12da-452a-a061-bfda1dc359b5",
    "response": {
        "message": "Execution success",
        "code": "ok"
    },
    "result": {
        "entity": "Document",
        "uuid": "69d5b65b-212b-4a54-b995-c22007f9d6da",
        "filename": "My new document name",
        "creation_date": "2022-12-26T20:03:46.128262+01:00",
        "modified_date": "2022-12-26T20:03:46.205468+01:00",
        "validation_date": null,
        "validator": null,
        "state": "pending",
        "version": "0.0",
        "author": "admin",
        "serie": "MySerie",
        "doctype": "MyFormType",
        "container": true,
        "file": {
            "url": "uploads/Athento_ysvozgijse/Contratos_msphd/2d/9c/2d9c09cdb21fd0a56eefd627240d554f_Idc6YiZ.pdf",
            "extension": ".pdf",
            "hash": "2d9c09cdb21fd0a56eefd627240d554f",
            "size": 34073,
            "content_type": "application/pdf"
        },
        "life_cycle_state": "Inicio"
    }
}

Eliminar un documento

Llamada genérica de eliminación:

DELETE https://demo.athento.com/api/v1/file/{file-uuid}/

Eliminar documento

La eliminación de un documento siempre se hace de forma lógica, manteniendo la posibilidad de localizar, y/o recuperar su información. En la respuesta se obtiene el atributo removed con valor true.

DELETE /file/{file-uuid}/

 Respuesta:

{
    "request-id": "ebcc21ca-893c-4f34-9e8b-90a3c87edb1d",
    "response": {
        "message": "Execution success",
        "code": "ok"
    },
    "result": {
        "entity": "Document",
        "uuid": "77bd8d16-66bb-45fd-ace4-638257f665b8",
        "filename": "Mi documento3",
        "creation_date": "2022-12-26T20:07:23.321660+01:00",
        "modified_date": "2022-12-26T20:07:24.017370+01:00",
        "validation_date": null,
        "validator": null,
        "state": "pending",
        "version": "0.0",
        "author": "admin",
        "serie": "MySerie",
        "doctype": "MyFormType",
        "removed": true,
        "container": false,
        "life_cycle_state": "Inicio"
    }
}

Descargar el contenido de un documento

Llamada genérica de descarga:

GET https://demo.athento.com/api/v1/file/{file-uuid}/download/

Descarga del contenido

GET /file/{file-uuid}/download/

Ejecutar transición de estado para un documento

Llamada genérica de transición:

POST https://demo.athento.com/api/v1/file/{file-uuid}/lifecycle/transition/

Ejecución de la transición

Un documento puede tener un ciclo de vida asociado y, desde este servicio, es posible ejecutar una transición desde el estado donde se encuentre. Para ello, basta con informar del nombre de la transición que se quiere ejecutar (o el propio uuid).

Además, si el documento include varios ciclos de vida asociados (parallel lifecycles) es posible indicar sobre qué ciclo de vida será ejecutada la transición, informando del nombre (o del uuid) y del parámetro parallel con valor true.

POST /file/{file-uuid}/lifecycle/transition/

Content-Type: application/json

Petición:

{
  "transition": "Completar",
  "comment": "Finalización manual sobre ciclo de vida único."
}
{
  "transition": "Completar",
  "lifecycle": "Basico",
  "parallel": true,
  "comment": "Finalización manual sobre ciclo de vida paralelo."
}

Respuesta:

{
    "request-id": "23bbefc6-12da-452a-a061-bfda1dc359b5",
    "response": {
        "message": "Execution success",
        "code": "ok"
    },
    "result": {
        "entity": "Document",
        "uuid": "b3a35e9a-ebb2-475c-a43e-7d896eb6cee2",
        "filename": "My document with lifecycle",
        "creation_date": "2022-12-26T20:03:46.128262+01:00",
        "modified_date": "2022-12-26T20:03:46.205468+01:00",
        "validation_date": null,
        "validator": null,
        "state": "pending",
        "version": "0.0",
        "author": "admin",
        "serie": "MySerie",
        "doctype": "MyFormType",
        "container": true,
        "life_cycle_state": "Finalizado"
    }
}

Usuarios — User Entity

Athento permite la gestión de usuarios desde la API v1 para crear nuevos, consultar, editar y operaciones asociadas.

A continuación se muestra la representación de un usuario.

{
    "entity": "User",
    "uuid": "fe1d49d0-dd0f-44db-b436-7857545560bb",
    "username": "admin",
    "email": "vs@athento.com",
    "first_name": "Victor",
    "last_name": "Sánchez",
    "identification_number": "12345678X",
    "phone_number": "+34600123456",
    "job_title": "TI",
    "is_active": true,
    "teams": [{
        "name": "Athento_ysvozgijse",
        "label": "Athento"
    }],
    "date_joined": "2022-05-16T23:43:05.548400+02:00",
    "language": "es"
}

Crear un usuario

Llamada genérica de creación:

POST https://demo.athento.com/api/v1/user/ 

Crear usuario

POST /api/v1/user/

Content-Type: application/json

Nombre

Valores

Opcional

username

Nombre del usuario

False

email

Email del usuario

False

first_name

Nombre de la persona

True

last_name

Apellidos de la persona

True

job_title

Puesto

True

custom_fields

JSON con los atributos custom de la persona.

True

teams

Listado de Equipos a los que pertenecerá el usuario.

True

groups

Listado de Groups a los que pertenecerá la persona.

True

Petición:

{
    "username": "johnfoo",
    "email": "jf@athento.com",
    "first_name": "John",
    "last_name": "Foo",
    "job_title": "TI",
    "custom_fields": {
        "phone_number": "+34600123456",
        "zona_de_trabajo": "Este"
    },
    "teams": [
        "Athento_ysvozgijse"
    ],
    "groups": [
        "devops",
        "colaboradores"
    ]
}

 Respuesta:

{
    "request-id": "5ba3aa4a-170e-4d92-80d5-e69c05bfb529",
    "response": {
        "message": "Execution success",
        "code": "ok"
    },
    "result": {
      "entity": "User",
      "uuid": "8f165dd2-d8aa-4f0b-9a00-90ff60098e9b",
      "username": "johnfoo",
      "email": "jf@athento.com",
      "first_name": "John",
      "last_name": "Foo",
      "identification_number": "00000000X",
      "phone_number": "",
      "job_title": "TI"
      "teams": [{
        "name": "Athento_ysvozgijse",
        "label": "Athento"
      }],
      "is_active": true,
      "date_joined": "2023-01-01T12:12:12",
      "language": "en"
  }
}

Modificar usuario

PUT /api/v1/user/

Content-Type: application/json

Petición:

{
    "custom_fields": {
        "department": {
            "TI-Level2"
        },
        "groups": [
            "devops",
            "member"
        ]
    }
}

 Respuesta:

{
    "request-id": "2e0fed76-74a9-43fe-8427-f4508e99fcbe",
    "response": {
        "message": "Execution success",
        "code": "ok"
    },
    "result": {
      "entity": "User",
      "uuid": "8f165dd2-d8aa-4f0b-9a00-90ff60098e9b",
      "username": "johnfoo",
      "email": "jf@athento.com",
      "first_name": "John",
      "last_name": "Foo",
      "identification_number": "00000000X",
      "phone_number": "",
      "job_title": "TI"
      "is_active": true,
      "date_joined": "2023-01-01T12:12:12",
      "language": "en"
  }
}

Activar usuario

POST /api/v1/user/{username}/activate/

Content-Type: application/json

Nombre

Valores

Opcional

username

Nombre del usuario a activar.

False

 Respuesta:

{
    "request-id": "2e0fed76-74a9-43fe-8427-f4508e99fcbe",
    "response": {
        "message": "Execution success",
        "code": "ok"
    },
    "result": {
      "entity": "User",
      "uuid": "8f165dd2-d8aa-4f0b-9a00-90ff60098e9b",
      "username": "johnfoo",
      "email": "jf@athento.com",
      "first_name": "John",
      "last_name": "Foo",
      "identification_number": "00000000X",
      "phone_number": "",
      "job_title": "TI"
      "is_active": true,
      "date_joined": "2023-01-01T12:12:12",
      "language": "en"
  }
}

El campo is_active se encuentra actualizado a true.

Desactivar usuario

POST /api/v1/user/{username}/deactivate/

Content-Type: application/json

Nombre

Valores

Opcional

username

Nombre del usuario a activar.

False

 Respuesta:

{
    "request-id": "2e0fed76-74a9-43fe-8427-f4508e99fcbe",
    "response": {
        "message": "Execution success",
        "code": "ok"
    },
    "result": {
      "entity": "User",
      "uuid": "8f165dd2-d8aa-4f0b-9a00-90ff60098e9b",
      "username": "johnfoo",
      "email": "jf@athento.com",
      "first_name": "John",
      "last_name": "Foo",
      "identification_number": "00000000X",
      "phone_number": "",
      "job_title": "TI"
      "is_active": false,
      "date_joined": "2023-01-01T12:12:12",
      "language": "en"
  }
}

El campo is_active se encuentra actualizado a false.

Grupos — Group Entity

Athento permite la gestión de grupos desde la API v1 para crear nuevos grupos y consultarlos.

A continuación se muestra la representación de un usuario.

{
    "entity": "Group",
    "name": "Members"
}

Crear un grupo

Llamada genérica de creación:

POST https://demo.athento.com/api/v1/group/ 

Crear grupo

POST /api/v1/group/

Content-Type: application/json

Nombre

Valores

Opcional

name

Nombre del grupo

False

teams

Listado de Equipos a los que pertenecerá el grupo.

True

Petición:

{
    "name": "MyGroup",
}

Si en la petición no se informa del Team o de los Teams donde será creado el grupo, se tomará por defecto el Team del usuario que realiza la petición.

Petición (con Teams):

{
    "name": "MyGroup",
    "teams": [
        "Athento_ysvozgijse"
    ]
}

 Respuesta:

{
    "request-id": "bc9fb79b-b29c-4c25-aac6-4328d49f11c6",
    "response": {
        "message": "Execution success",
        "code": "ok"
    },
    "result": {
        "entity": "Group",
        "name": "MyGroup_pnyxlfbupbyvibcuoajajp"
    }
}

Búsqueda de documentos — Query & ResultSet Entities

Para realizar búsquedas de documentos sobre Athento es necesario usar servicios de query para la obtención de columnas específicas en modo resultset, o para obtener las entidades de documento completas. Éstos dos tipos de consulta son: resultset y query respectivamente.

Llamada genérica de consulta: 

POST https://demo.athento.com/api/v1/search/{query—type}/?{rest—query}

Nombre

Valores

Opcional

query-type

resultset, query

False

rest-query

page, page_size

True

  • page: es la página de documentos que se quiere obtener, por defecto, el valor de page es 1.

  • page_size: es el tamaño de página de la ventana de documentos que se pretende obtener. Por defecto, el valor de page_size es 20.

ResultSet

El servicio de resultset devuelve el listado de columnas indicadas en la cláusula SELECT de la consulta realizada. Las columnas obtenidas pueden ser atributos del documento o metadatos del formulario asociado.

Ver la parte de creación de consultas usando lenguaje ATQL para más información de fabricación de consultas.

POST /api/v1/search/resultset/?page=1&page_size=20

Petición

{
   "query": "SELECT uuid, filename, space FROM MyForm WHERE \
             (((filename = 'PDF-Athento.pdf' or filename = 'PDF-Athento-Other.pdf') \
            AND (form IN ('MyForm', 'OtherForm'))) \
            AND (metadata.numero_contrato = '12345'))"
}

 Respuesta:

{
    "request-id": "220f74b7-0ab4-4c02-bf2f-2e40142e1c09",
    "response": {
        "message": "Execution success",
        "code": "ok"
    },
    "result": {
        "entity": "ResultSet",
        "page": 1,
        "pageSize": 20,
        "totalCount": 1,
        "totalPages": 1,
        "maxPageSize": 200,
        "entries": [
            {
                "uuid": "a39f0360-dba0-4586-a9e2-480eec7a9f6c",
                "filename": "PDF-Athento.pdf",
                "serie": {
                    "name": "MySerie"
                }
            },
            {
                "uuid": "f4435660-dba0-4586-a9e2-480eec7a9f6c",
                "filename": "PDF-Athento-Other.pdf",
                "serie": {
                    "name": "MySerie"
                }
            }
        ]
    }
}

Query

El servicio de query devuelve el listado de entidades de documento completas para la consulta realizada.

POST /api/v1/search/query/?page=1&page_size=20

Petición:

{
   "query": "SELECT * FROM MyForm WHERE (((title = 'PDF-Athento.pdf' \ 
             or title = 'PDF-Athento-Other.pdf') \
             AND (form IN ('MyForm', 'OtherForm'))) \
            AND (metadata.numero_contrato = '12345'))"
}

Respuesta:

{
    "request-id": "d070d5a4-d30f-4238-8454-d4480ed17d67",
    "response": {
        "message": "Execution success",
        "code": "ok"
    },
    "result": {
        "entity": "Query",
        "page": 1,
        "pageSize": 20,
        "totalCount": 1,
        "totalPages": 1,
        "maxPageSize": 200,
        "entries": [
            {
                "entity": "Document",
                "uuid": "a39f0360-dba0-4586-a9e2-480eec7a9f6c",
                "filename": "PDF-Athento.pdf",
                "creation_date": "2022-08-11T18:24:54.293897+02:00",
                "modified_date": "2022-08-11T18:32:07.992000+02:00",
                "state": "pending",
                "version": "0.0",
                "author": "admin",
                "serie": "MySerie",
                "doctype": "MyForm",
                "container": true,
                "file": {
                    "url": "uploads/Athento_ysvozgijse/Expedientes_nsyzx/2d/9c/2d9c09cdb21fd0a56eefd627240d554f.pdf",
                    "extension": ".pdf",
                    "hash": "2d9c09cdb21fd0a56eefd627240d554f",
                    "size": 34073,
                    "content_type": "application/pdf"
                },
                "life_cycle_state": "Inicio"
            }
        ]
    }
}

Consultas sobre documentos eliminados

Para consultar documentos eliminados debe indicarse el parámetro "removed": true en tanto en resultset como en query del siguiente modo. Por defecto, las búsquedas se realizan sobre documentos que no están eliminados, pero con esta opción se ofrece la posibilidad de consultar sobre la papelera.

{
   "query": "SELECT * FROM MyForm WHERE (((title = 'PDF-Athento.pdf' \
             or title = 'PDF-Athento-Other.pdf') \ 
             AND (form IN ('MyForm', 'OtherForm'))) \
             AND (metadata.numero_contrato = '12345'))"
   "removed": true
}

Ver la parte de creación de consultas usando lenguaje ATQL para mas información de fabricación de consultas.


ATQL

ATQL (Athento Query Language) es un lenguaje definido por Athento para realizar consultas simples o complejas basadas en su modelo documental, de manera que se pueda establecer una consulta que formalice qué campos del formulario se desean obtener, sobre qué tipos de formularios concretos y haciendo sobre qué condiciones establecidas sobre los propios campos —metadatos— incluidos en dichos formularios.

El formato ATQL es similar a SQL en cuanto a su estructura aunque —por el momento— tiene limitaciones en sus cláusulas de agrupamiento y funciones de agregación.

Ejemplo de consulta ATQL.

SELECT uuid, filename FROM MyForm WHERE (filename = 'Athento1.pdf' \
OR filename = 'Athento2.pdf') AND (metadata.contract_number = '123456' \
AND not metadata.ciudad_firma IN ('Málaga', 'Madrid')) ORDER BY uuid DESC

 

Sintaxis

La consulta ATQL es una expresión basada en cláusulas para la consulta de campos de un documento o entidades completas.

La sintaxis general de la consulta es:

SELECT (*|<select-clause>) FROM <from-clause> \
                           [WHERE <where-clause>] [ ORDER BY <order-by-clause>]

 

La cláusula SELECT es una lista de campos fijos y metadatos separados por coma, o el asterisco (SELECT * FROM ...) para devolver la entidad documento completa.

La cláusula del FROM es una lista de nombres de formularios separada por coma sobre el que se quiere consultar. Puede usarse el valor Document para realizar la consulta sobre todos los tipos de formulario disponibles.

La cláusula WHERE es en general un predicado que contiene una lista de condiciones por las que se filtrarán los documentos. Dichas condiciones pueden ser anidadas en forma de expresión usando operadores lógicos AND, OR o NOT

Ejemplos de condiciones en forma de expresión:

  • expression

  • NOT expression

  • expression <operator> expression

Un operador puede ser:

  • AND

  • OR

  • =

  • !=

  • <

  • <=

  • >

  • >=

  • IN

  • BETWEEN

  • LIKE

  • ILIKE

Campos fijos de consulta vs metadatos

En ATQL puede hacerse uso de campos nominales fijos que ayudan a obtener información del documento. Por ejemplo, la consulta sobre el título (title ó filename) o el identificador interno (uuid).

Campo

Descripción

uuid

Identificador del documento

filename ó title

Título del documento

author

Creador del documento

creation_date o created

Fecha de creación del documento

modified_date o modified

Fecha de modificación del documento

validation_date o validated

Fecha de validación del documento

space ó serie

Espacio donde se encuentra el documento

form ó doctype

Nombre del formulario

life_cycle_state

Ciclo de vida del documento

state

Estado del documento

size

Tamaño del documento

 

Ejemplos:

SELECT filename, form, space, state FROM my_form WHERE \
       ((filename = 'PDF-Athento-One.pdf') \
      AND space = 'Documentos_aeuxa') OR filename = 'PDF-Athento.pdf'
      
SELECT uuid, creation_date FROM my_form WHERE \
      (creation_date BETWEEN '2022-01-01' AND '2022-12-31' \
      OR modified_date > '2022-12-01') \
      AND NOT state = 'pending' ORDER BY creation_date
      
SELECT * FROM my_form WHERE life_cycle_state = 'Iniciado' ORDER BY uuid DESC

 

Búsqueda por metadatos

Para la búsqueda de documentos usando metadatos del formulario, es necesario aplicar las condiciones con el nombre del metadatos. Ejemplos:

SELECT metadata.my_metadata FROM Document WHERE metadata.my_metadata IN ('1', '2')

SELECT uuid, metadata.my_metadata FROM my_form WHERE NOT metadata.my_metadata = '10'

SELECT uuid, metadata.my_metadata, metadata.my_other_metadata FROM form \
       WHERE NOT metadata.my_metadata = '10' \
       AND (metadata.my_other_metadata = '20' OR filename = 'PDF-Athento.pdf')

 

Ordenación

Para ordenar las búsquedas se deben hacer uso de la directiva ORDER BY, con el listado de campos fijos, o metadatos por los que queramos ordenar. Además, podemos establecer el tipo de ordenación, ascendente o descendente con ASC o DESC respectivamente.

Si no se especifica el tipo de ordenación, por defecto será ascendente.

Ejemplos:

SELECT uuid FROM Document ORDER BY uuid
SELECT filename FROM my_form WHERE filename LIKE 'pdf' ORDER BY filename, uuid DESC
SELECT uuid, metadata.my_metadata FROM my_form \
       WHERE NOT metadata.my_metadata = '10' ORDER BY metadata.my_metadata ASC

Funciones

ATQL permite el uso de funciones dinámicas para filtrar. A continuación se muestran las funciones disponibles.

Función

Parámetros

Descripción

NOW

Obtiene la fecha actual en formato yyyy-MM-dd hh:mm:ss con la posibilidad de incrementar (ó decrementar) con el parámetro según el formato wdhms para semanas, días, horas, minutos y segundos respectivamente.

Ejemplo: 1w2d para incrementar en 1 semana y 2 días, ó -3h4m para restar 3 horas y 4 minutos.

TODAY

No

Obtiene la fecha del día actual en formato yyyy-MM-dd

YESTERDAY

No

Obtiene la fecha del día anterior a hoy en formato yyyy-MM-dd

TOMORROW

No

Obtiene la fecha del día siguiente a hoy en formato yyyy-MM-dd

CURRENT_USER

No

Obtiene el nombre de usuario actual.

Ejemplos:

  1. Obtener los documentos creados en la última semana:

SELECT * FROM my_form WHERE creation_date > NOW(-1w)
  1. Obtener los documentos creados hoy:

SELECT * FROM my_form WHERE creation_date > TODAY
  1. Obtener los documentos creados desde ayer:

SELECT * FROM my_form WHERE creation_date > YESTERDAY
  1. Obtener documentos creados por el usuario actual:

SELECT * FROM my_form WHERE author = CURRENT_USER
  1. Obtener documentos creados entre hace una semana y mañana:

SELECT * FROM my_form WHERE created_date BETWEEN NOW(-1w) AND TOMORROW
  • No labels