<< Clic para mostrar Tabla de Contenidos >> Navegación:  Automatización de Procesos con poco código > Studio Cloud -ambiente de autoría > Bizagi Studio > Bizagi desde aplicaciones externas > API de Bizagi para aplicaciones externas > Servicios RESTful OData > Conceptos básicos > Propiedades y Opciones de Consulta

Introducción

Bizagi ofrece servicios OData que manejan un conjunto extenso de recursos relacionados con el Asistente de Personas, como se mencione en API de Bizagi.

Para estos recursos se puede elegir agregar filtros o navegar la información obtenida con la respuesta basándonos en unas propiedades estándares y opciones de consulta.

 

Propiedades

Para todos los resultados que entregan los servicios de OData, la respuesta exitosa incluye un grupo de propiedades que son precedidas por el símbolo @.

Estas propiedades son:

 

 

Filtrar los resultados

Cuando se obtienen resultados múltiples dentro de una respuesta de invocación (p.ej. una colección de valores) por medio de una acción HTTP GET, puede hacer uso de la opción estándar (basada en especificaciones OData) $filter (parámetro de consulta URL), para lograr disminuir los resultados que desea de acuerdo a ciertos criterios.

 

Algunos de los operadores más comunes de las especificaciones OData son soportados por Bizagi y se describen en la taba a continuación:

 

 

Tenga en cuenta que toda la información en las respuestas son cadenas de texto (como tipo de dato), y por ello, los operadores y valores deben ir entre apóstrofes (caracteres ' ').

 

Filtrar con operadores simples

Para los operadores simples tales como and, or, eq, ne, puede hacer uso de $filter con la siguiente sintaxis básica:

[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]?$filter=[recurso_campo] [operador] [valor]

 

Siendo:

•[operador]: Puede usar eq / ne.

•[valor]: El valor a comparar.

•[recurso_campo]: El campo en particular dentro de la respuesta de invocación que contiene los resultados múltiples. Un ejemplo típico en Bizagi sería valores (values).

•[servicio_odata]: El nombre del servicio OData que sería data o metadata.

•[recurso_odata]: El recuso OData que se está consultando que retorna varios resultados dentro de la respuesta. Un ejemplo en Bizagi sería consultar stakeholders.

•[url_del_proyecto_bizagi]: Corresponde a la URL donde los usuarios finales acceden al Portal de Trabajo de Bizagi.

Proyectos de Automation Service, esta URL sería:

https://[ambiente_del_proyecto]-[su_proyecto]-[su_compañía].bizagi.com/

 

Cuando se encadena más de un filtro (usando 'and'/'or'), usted usaría $filter con la siguiente sintaxis (de manera similar puede agregar filtros adicionales):

•[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]?$filter=[recurso_campo] [operador_1] [valor_1] and [operador_2] [valor_2]

•[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]?$filter=[recurso_campo] [operador_1] [valor_1] or [operador_2] [valor_2]

 

Un ejemplo con un operador simple, sería filtrar el recurso casos (cases) al asegurarnos que un caso en específico es obtenido por su identificador:

.../cases?$filter=caseNumber eq '1169'

 

 

Otro ejemplo para usar un operador simple podría evaluar qué hay en la colección interna de información del caso.

Este ejemplo filtra los resultados para que traiga únicamente aquellos procesos que no consideran el parámetro del tipo XPath llamado Puntuación.

En otras palabras, aquellos procesos que no exigen que se envíe una puntuación para iniciar un caso nuevo:

.../processes?$filter=parameters/XPath ne 'Score'

 

 

Finalmente, tenemos un ejemplo para encadenar más de un filtro usando and / or.

En este caso obtendremos todas las actividades que se encuentran a tiempo, es decir, con estado verde, o expirada, con estado rojo, dejando por fuera aquellas en estado amarillo:

.../workitems?$filter=Contains(state, 'green') or Contains(state,'red')

 

 

Tenga en cuenta que el ejemplo anterior hace uso del operador Contiene, el cual hace uso de una notación diferente que se asemeja a como se usaría la función en la mayoría de los lenguajes de programación.

 

Filtrando con operadores complejos

Para operadores complejos como any, all, puede usar  $filter con la siguiente sintaxis básica:

[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]?$filter=[recurso_colección]/[operador_complejo](p:p/[atributo_colección] [operador_simple] [valor])

 

Siendo:

•[operador_complejo]: Puede usar any  / all.

•[operador_simple]: Puede usar eq / ne.

•[valor]: El valor a comparar (usado por el operador_simple).

•[recurso_collección]: La colección en particular dentro de los valores de respuesta de la invocación, que contiene varios resultados para iterar. Un ejemplo típico en Bizagi sería parámetros (parameters).

•[servicio_odata]: El nombre del servicio OData que sería data o metadata.

•[recurso_odata]: El recuso OData que se está consultando que retorna varios resultados dentro de la respuesta. Un ejemplo en Bizagi sería consultar stakeholders.

•[url_del_proyecto_bizagi]: Corresponde a la URL donde los usuarios finales acceden al Portal de Trabajo de Bizagi.

Para proyectos Automation Service, esta URL sería:

https://[ambiente_del_proyecto]-[su_proyecto]-[su_compañía].bizagi.com/

 

Nuestro primer ejemplo con el operador cualquier, será para buscar procesos donde haya al menos un parámetro del tipo colección ('Collection'):

...processes?$filter=parameters/any(p: p/type eq 'Collection')

 

 

De igual manera, para encadenar más de un filtro (usando 'y'/'o') usted deberá usar $filter con la siguiente sintaxis (de manera similar puede agregar filtros adicionales):

•[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]?$filter=[recurso_collección]/[operador_complejo](p:p/[atributo_coleccion1] [operador_simple_1] [valor1]

and p/[atributo_coleccion2] [operador_simple_2] [valor2)

•[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]?$filter=[recurso_collección]/[operador_complejo](p:p/[atributo_coleccion1] [operador_simple_1] [valor1]

or p/[atributo_coleccion2] [operador_simple_2] [valor2])

 

Paginación de los resultados

Siempre que obtenga resultados por medio de una acción HTTP GET, puede confiar en el uso de los estándares de opciones de consulta $top y $skip para implementar la paginación, especialmente si el servicio retorna una gran cantidad de resultados.

Por lo tanto, para implementar una consulta que maneja paginación, use estos parámetros que se describen a continuación:

 

 

Note que Bizagi automáticamente incluye en la respuesta las propiedades @odata.totalCount y @odata.nextLink.

El siguiente es el ejemplo de la respuesta que se tiene cuando se consulta en la URL en los ejemplos anteriores usando la paginación de los resultados:

{

 "@odata.context": "[url_del_proyecto_bizagi]/odata/metadata/$metadata#stakeholders",

 "@odata.totalCount": 16,

 "valor": [

   {

     "@odata.id": "[url_del_proyecto_bizagi]/odata/metadata/stakeholders(e6e38460-2f33-4804-bddf-46058843c314)",

     "id": "e6e38460-2f33-4804-bddf-46058843c314",

     "name": "Client",

     "displayName": "Client",

     "IconName": "bz-icon-ctg bz-icon-ctg-helicopter"

   }

 ],

 "@odata.nextLink": "[url_del_proyecto_bizagi]/odata/metadata/stakeholders?$top=1&$skip=1"

}

 

Ejemplo $top y $skip

Tenemos la siguiente URL que nos retorna una lista con n resultados

[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]

 

Siendo:

•[servicio_odata]:  El nombre del servicio OData, sea data o metadata.

•[recurso_odata]: El nombre del recurso (URI) que está siendo consultado. Ejemplo: cosas, búsquedas, relevantes, procesos, stakeholders.

•[url_del_proyecto_bizagi]: Corresponde a la URL donde los usuarios finales acceden al Portal de Trabajo de Bizagi.

Para proyectos Automation Service, esta URL sería:

https://[ambiente_del_proyecto]-[su_proyecto]-[su_compañía].bizagi.com/oauth2/server/token

 

Ahora, al agregar parámetros tales como $top y $skip, se puede manejar de una mejor manera una gran cantidad de resultados

Por ejemplo, mientras se hace uso de la URL especificada anteriormente, esta nueva invocación obtiene 50 resultados empezando por el resultado 1001:

[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata]?$top=50&$skip=1000

 

 

Expansión de los resultados

Cuando obtenga resultados por medio de una acción HTTP GET, puede confiar en el uso de la opción estándar (según especificaciones OData) $expand (parámetro de consulta URL), para lograr extraer información adicional (de los recursos hijo) en la misma invocación.

Por lo tanto y para implementar una consulta que extrae tal información en la misma invocación, haga uso de los parámetros descritos a continuación:

 

Esto quiere decir, que usted puede usar $expand con la siguiente sintaxis:

[url_del_proyecto_bizagi]/odata/[servicio_odata]/[recurso_odata_padre]?$expand=[recurso_odata_hijo]

 

Ejemplo $expand

Comencemos con la siguiente consulta que obtiene la información de la Persona.

 

 

Tomando como un ejemplo, la información de la Persona Doctor como se muestra en al figura anterior, se puede notar que los detalles que se encontraron para esa Persona (consultado por ID) no incluye por defecto información de Mis Cosas del Doctor como se muestra a continuación:

 

 

Note que para la simplicidad del ejemplo, no resaltamos la información de contexto (contexts) dado que no es relevante.

 

Sabemos que podemos obtener la información de Mis Cosas, dado que es una recurso que se encuentra disponible ((/stuff)) atado a una Persona (en este caso el Doctor).

Observe que la colección Mis Cosas para el Doctor en este ejemplo consiste solamente en el equipo médico (equipo médico), como se muestra a continuación:

 

 

Ahora, podemos confiar en la opción $expand para traer la información de Mis cosas cuando consultamos la información de la Persona Doctor, como se realizó inicialmente.

Esto uniría los detalles de la Persona junto con las colecciones de Mis Cosas en una sola respuesta:

 

 

Opciones de consulta con el parámetro allUsers

Cuando usted hace una consulta, puede utilizar el parametro allusers para obtener resultados para todos los usuarios. Sin este parámetro, usted puede obtener resultados únicamente para el usuario que se encuentra con la sesión iniciada. Hay múltiples escenarios en donde usted puede utilizar este parámetro, que se explican en la siguiente sección:

 

Usted puede consultar todas estas opciones por medio de Postman.

 

Como prerrequisito, usted debe generar primero un bearer token en el Portal de Trabajo y conectarse a su proyecto de Bizagi. Los pasos para hacerlo se detallan en Autenticación de la API de Bizagi.

 

Seleccione el tipo de método que ejecutará (GET, POST, DELETE, etc.). Escriba la URL de su proyecto y apenda el endpoint en el que está interesado. Envíe la solicitud y el resultado de la consulta se retorna.

 

Retorna todos los procesos para todos los usuarios o un proceso específico para todos los usuarios.

 

Endpoint para todos los casos de un proceso: /odata/data/processes(ID)/cases?$allUsers=true

Enpoint para un caso específico de un proceso: /odata/data/processes(ID)/cases(ID)?$allUsers=true

 

Para este ejemplo usted debe haber obtenido el id del proceso en el que está interesado previamente. Puede obtener el id, haciendo una consulta para obtener todos los procesos. Tenga en mente que debe buscar el parametro id  y no processId.

 

Una vez tenga el id, debe reemplazar ID en el endpoint /odata/data/processes(ID)/cases?$allUsers=true, con el id real. La URL en Postman debe verse de la siguiente forma:

•[url_de_su_proyecto_bizagi]/odata/data/processes(ID)/cases$allUsers=true

 

En el caso de un caso específico para un proceso específico, La URL en Postman debe verse de la siguiente forma:

•[url_de_su_proyecto_bizagi]/odata/data/processes(ID)/cases(ID)$allUsers=true

 

 

 

Buscar por número de caso para todos los usuarios

Endpoint: /odata/data/searchByCaseNumber(caseNumber=’caseNumber’)?$allUsers=true

 

La URL de Postman se debe ver de la siguiente forma:

•[url_de_su_proyecto_bizagi]/odata/data/searchByCaseNumber(caseNumber= case number)?$allUsers=true

 

 

Retorna todos los casos o un caso específico para todos los usuarios

 

Endpoint para todos los casos: /odata/data/cases?$allUsers=true

 

Para obtener un caso específico para todos los usuarios, la URL en Postman debe verse de la siguiente forma:

•[url_de_su_proyecto_bizagi]/odata/data/cases?$allUsers=true

 

Endpoint para un caso específico: /odata/data/cases(ID)?$allUsers=true

 

Para obtener todos los casos para todos los usuarios, la URL en Postman debe verse de la siguiente forma:

•[url_de_su_proyecto_bizagi]/odata/data/cases?$allUsers=true

 

 

Retorna todos los casos con Work Items o con un Work Item específico para todos los usuarios

 

Endpoint para todos los casos con Work Items: /odata/data/casesWithWorkitems?$allUsers=true

Para este ejemplo, usted debe haber obtenido los ids del procesos y el caso de interés. Puede hacer esto haciendo una consulta que retorne todos los procesos y/o todos los casos.

 

Una vez tenga los ids, debe reemplazar ID en el endpoint /odata/data/casesWithWorkitems?$allUsers=true, con el id real. La URL en Postman debe verse de la siguiente forma:

•[url_de_su_proyecto_bizagi]/odata/data/casesWithWorkitems?$allUsers=true

 

 

 

 

Endpoint for a specific case with work items: /odata/data/casesWithWorkitems(ID)?$allUsers=true

 

Para este ejemplo, también debe haber obtenido los ids del procesos y el caso de interés. Puede hacer esto haciendo una consulta que retorne todos los procesos y/o todos los casos.

 

Una vez tenga los ids, debe reemplazar ID en el endpoint /odata/data/casesWithWorkitems(ID)?$allUsers=true, con el id real. La URL en Postman debe verse de la siguiente forma:

•[url_de_su_proyecto_bizagi]/odata/data/casesWithWorkitems(ID)?$allUsers=true

 

 

Last Updated 11/28/2023 9:20:19 AM