Guía de inicio

<< Clic para mostrar Tabla de Contenidos >>

Navegación:  Bizagi Studio > Bizagi desde aplicaciones externas > API de Bizagi para aplicaciones externas > Servicios OData >

Guía de inicio

Introducción

Bizagi provee una API con servicios OData, como se describe en API de Bizagi.

Para explorar y validar como funcionan los servicios OData de Bizagi, considere iniciar siguiendo los pasos que se describen a continuación.

 

Recomendaciones generales

Tenga en cuenta las siguientes notas:

 

Usar Postman.

Para un inicio rápido le recomendamos usar Google Chrome y un plug-in de extensión llamado Postman.

Extensiones como Postman (puede elegir una similar tal como Advanced REST Client https://advancedrestclient.com/), le permiten invocar servicios OData mientras puede personalizar la información que se envía en el encabezado de la petición (lo que no es posible desde un navegador).

Si desea más información sobre Postman, refiérase a https://www.getpostman.com/docs/.

 

Configuración de los Stakeholders potenciales.

Para obtener resultados ideales y poder aprovechar los datos considerados por los servicios OData de Bizagi, recomendamos tener procesos modelados que hacen uso del Diseño de experiencia en su proyecto.

 

A lo largo de Diseño de experiencia, asegúrese que haya creado Stakeholders y que los haya configurado en el Portal de trabajo para sus usuarios, para que Bizagi presenta información de manera diferente dependiendo del Stakeholder.

 

OData_Postman1Workportal

 

La imagen anterior muestra un usuario llamado Tom Hall que está asignado como Stakeholder Legal Area Worker.

 

Lo que debe hacer

Para invocar los servicios OData de Bizagi, tenga en cuenta este esquema a alto nivel:

 

1.  Registrar una aplicación OAuth

Este primer paso consiste en otorgar acceso a la aplicación externa, mientras se crean las llaves de acceso adecuadas.

Esto es un requisito para poder hacer uso de los servicios OData.

 

2. Autenticar con OAuth

Este paso hace uso de Postman para establecer una comunicación autenticada con los servicios OData.

Una vez se haga uso de las llaves de acceso, se le dará un token de acceso para realizar más peticiones.

 

3. Invocar los servicios OData

Como último paso, cualquier número de invocaciones se podrán hacer mientras se haga uso del token (a través de Postman).

 

 

Procedimiento

Para probar de una manera fácil y rápida los servicios OData de Bizagi, siga los siguientes pasos:

 

1. Registrar una aplicación OAuth.

Una vez tenga usuarios como Stakeholders y  haya usado extensivamente las características de Diseño de experiencias en Bizagi, diríjase al Portal de trabajo.

 

Haga clic sobre la opción Aplicaciones OAuth2 en el menú Admin para poder otorgarle permiso a una aplicación externa.

 

OData_Workportal1

 

Note que esta opción muestra una lista de todos los servicios que son accedidos por dispositivos Bizagi, y le permite agregar aplicaciones adicionales que representan los accesos otorgados al tener las llaves de acceso adecuadas.

Haga clic sobre la opción para agregar un nuevo registro en la tabla.

 

 

OData_Workportal2

 

note_pin

Tenga en cuenta que para la configuración por defecto del sistema, puede elegir editar el tiempo de vida del token, que determina el numero de minutos que deben transcurrir para que se venza el token (esto es para mejorar la seguridad empleada por estos tokens, en especial cuando se atacan de ataques de replay).

 

OData_Workportal15

 

 

Cuando defina una nueva aplicación, asegúrese de considerar los siguientes detalles:

Nombre: Dé un nombre único y significativo

Tipo de Permiso: Los valores posibles son: Código de autorización, Credenciales de cliente, o todos.

Más información sobre estos valores y cuándo usarlos mejor se encuentra en Conceptos de OAuth de Bizagi API.

Pagina Web: Especifique una URL asociada.

Scope permitido: Las posibles casillas para marcar son: API o Login.

Se recomienda siempre habilitar API para poder otorgar los permisos necesarios para poder sacar el máximo provecho a los servicios OData.

Active Login cuando elige Código de autorización como Tipo de permiso.

Nombre de usuario: (Aplica cuando se hace uso de Credenciales de cliente). Escriba el nombre de un usuario Bizagi existente y asegúrese que lo seleccione de la lista de usuarios sugeridos que coinciden (incluye información del dominio).

Estrategia de Redirección:  (Aplica cuando se hace uso de Código de autorización). Valores posibles: Web Application, Mobile Title Bar Browser, y Mobile Localhost Port.

Una estrategia de redirección define cuales clientes podrán hacer uso de la aplicación.

Para esta prueba inicial, y para uso general, se puede hacer uso de la configuración con Web application.

Sin embargo, el enfoque usualmente recomendado es efectivamente hacer uso de Web application para que el servidor (que puede procesar las peticiones por medio de endpoints) invoca el API de Bizagi, mientras se tiene en cambio, aplicaciones móviles o cualquier otro tipo de clientes invocar servicios del servidor.

URI de redirección: (Aplica cuando se hace uso de Código de autorización). Define la URL a la cual se debe redireccionar cuando haya callback una vez el usuario haya ingresado sus credenciales.

Deberá utilizar siempre una URL que haga uso del protocolo HTTPS.

Tiempo de vida del Token: Define el número de minutos en los cuales un token es válido y puede ser reutilizado para otra invocación (usualmente para mejorar la seguridad mientras se evitan ataques replay)

 

 

note_pin

Se recomienda hacer uso de estas dos combinaciones, que usualmente involucran dos aplicaciones diferentes:

 

Para Servicios de Datos:

Tipo de Permiso: Código de autorización, Scope permitido: Login y API.

 

Para Servicios de Metadata:

Tipo de Permiso Credenciales de Cliente, Scope permitido: API.

 

 

OData_Workportal3

 

En estos ejemplos la aplicación registrada será autenticada en nombre del usuario agilityCorp\TomH.

 

Una vez haya terminado, haga clic sobre Guardar.

Notará que la aplicación recién registrada está en la lista con sus llaves de acceso.

Las llaves que deben ser usadas y copiadas en el porta papeles son: Client Id y Client Secret.

 

OData_Workportal4

 

 

2. Autenticar con OAuth.

Una vez haya copiado las llaves Client Id y Client Secret, estableceremos la comunicación autenticada por medio de Postman.

Antes de hacerlo, tenga en cuenta que Bizagi espera las credenciales como una una cadena de texto codificada en base64.

 

2.1 Para cifrar estas llaves como una sola cadena de texto, lleve a cabo lo siguiente:

Copie la llave Client Id primero y agréguele dos puntos (:) para añadir después Client secret.

El siguiente formato muestra la estructura, ignorando los caracteres []:

[Client Id]:[Client Secret]

Codifique esta cadena con base64.

Para lograrlo, puede hacer uso de páginas web como https://www.base64encode.org/, o hacer uso de su propio programa.

 

Al final, tendrá la cadena de texto con las credenciales, vamos a referirnos a este como las Credenciales cifradas:

 

OData_Postman0

 

 

2.2 Abra el plug-in de Postman y utilice la credencial cifrada para autenticarse con el servicio OAuth.

 

OData_Postman0b

 

2.3 Antes que todo, asegúrese que ingrese la URL del servicio para su proyecto Bizagi.

Asegúrese de usar una acción HTTP POST con la URL de la manera: [url_del_proyecto_bizagi]/oauth2/server/token

 

Siendo:

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

Por ejemplo, para proyectos de Bizagi en sus instalaciones, esta URL sería:

https://[su_servidor]/[su_proyecto]/oauth2/server/token

Mientras que para proyectos Bizagi Cloud, esta URL sería:

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

 

Especifique que No Auth es empleado.

OData_Postman2

 

2.4 Pase a la pestaña Headers y especifique:

Content-type: application/x-www-form-urlencoded

Authorization: Ingrese la palabra Basic, seguida por un espacio y agregue las Credenciales cifradas que obtuvo en el paso anterior.

 

Este es el formato empleado, ignorando los caracteres []:

Basic [Credenciales cifradas]

 

OData_Postman2b

 

 

2.5 Finalmente, en la pestaña Body seleccione la configuración raw y agregue esta linea en la caja de texto:

grant_type=client_credentials&scope=api

 

OData_Postman3

 

 

note_pin

Nótese que los valores posibles de grant_type son: client_credentials or authorization_code.

De manera similar, los valores posibles para scope son: login, api or all.

Sin embargo, authorization_code debe usarse desde un cliente donde se implemente debidamente su uso (con el envio de credenciales).

 

Ya puede hacer clic sobre Send, que dispara la petición para autenticar.

Una respuesta exitosa devuelve un access_token con información relevante a este:
 

OData_Postman5

 

 

3. Invocar servicios OData.

Una vez tenga el access_token, puede usarlo para una nueva invocación y probar los servicios OData.

Esta vez para realizar una prueba rápida, puede hacer uso de una acción HTTP GET para extraer información básica.

 

Cuando haga esto, asegúrese de usar una URL de servicios OData.

Para una prueba rápida puede usar: [url_del_proyecto_bizagi]/odata/data/stakeholders

 

Luego configure:

Authorization: Ingrese la palabra Bearer seguida por un espacio y agregue el access_token obtenido en el paso anterior.

El siguente es el formato empleado, ignore los caracteres []:

Bearer [access_token]

Content-type: application/json

 

OData_Postman4

 

Ya puede hacer clic sobre Send, que dispara la petición que solicita datos en formato JSON.

Una respuesta exitosa para este ejemplo y URL en específico, retorna el nombre de los Stakehoders a los que pertenece el usuario autenticado:

 

OData_Postman6

 

Note que el grupo Stakeholder para este usuario (agilityCorp/TomH con nombre completo Tom Hall) es Legal Area Worker.

 

OData_Postman1Workportal

 

Tenga en cuenta que el access_token expira como se configuró en la configuración para Tiempo de vida del Token, y por ello es posible que deba primero autenticarse con las Credenciales cifradas antes de lanzar una nueva invocación.

 

note_pin

Se pueden incluir filtros o navegar la información entregada con la respuesta.

Para aprender sobre filtros y opciones para restringir los datos que quiere manejar, refiérase a Opciones de consulta.

 

Ya ha realizado su primera invocación de estos servicios, puede explorar los recursos y las diferentes alternativas para consultarlos.

Para mayor información sobre estos servicios, refiérase a Servicios de Datos o Servicios de Metadatos.