Introducción
Bizagi presenta un API para que las aplicaciones externas puedan acceder la funcionalidad de los procesos y la información de negocio que se encuentra en el modelo de datos, como se describe en API de Bizagi para aplicaciones externas.
Consulte las siguientes notas importantes y detalles sobre el uso del API de Bizagi.
URL de los servicios web de Bizagi
Bizagi presenta un conjunto de servicios web ya generados, compilados y publicados para que usted pueda agilizar el desarrollo de sus requerimientos de integración.
La URL de estos servicios varía según las tres categorías que representa un componente principal de la arquitectura de producto de Bizagi (motor BPMN/Workflow, motor de acceso a datos/Entity Manager, o motor de consultas/Queries).
Los servicios web con soporte a WS-Security al ser habilitados, se ubican como:
https://[ambiente]-[proyecto]-[compañía].bizagi.com/WebServices/[componente_interno].svc?wsdl
Observe que:
•[ambiente] es el ambiente donde corre su proyecto.
•[proyecto] es el nombre de su proyecto Bizagi.
•[componente_interno] es el nombre del componente interno de Bizagi: EntityManagerSOA, WorkflowEngineSOA, o QuerySOA.
Ejemplo:
http://test-CreditApplication-AceCompany.bizagi.com/WebServices/EntityManagerSOA.asmx?wsdl
|
Nótese que usted deber siempre referenciar estos servicios web con la terminación explícita ?wsdl. Aunque a través de tecnologías de .NET (un cliente, incluso un navegador) usted pueda acceder a la definición de los servicios sin incluir dicha terminación, es recomendado según mejores prácticas de interoperabilidad usarla (p.e para un cliente php o de Java). |
Notas importantes y mejores prácticas
Las siguientes notas consideran mejores prácticas y temas específicos a tener en cuenta para la interoperabilidad entre servicios web y diferentes plataformas tecnológicas.
1. Tipos de datos de los métodos web
Los métodos web disponibles ofrecen la misma funcionalidad sea para proyectos de Bizagi en plataformas .NET o de JEE.
Tanto para .NET como para JEE, los métodos web del API de Bizagi tienen una nomenclatura que finaliza en "...AsString" (tales como createCasesAsString, getEntitiesAsString, queryCasesAsString, performActivityAsString, o saveEntityAsString, entre otros).
Estos métodos reciben y retornar cadenas de texto (usan el tipo de dato string).
|
Otros servicios web y métodos que no utilicen el sufijo "...AsString" en su nomenclatura y que manejen tipos de dato XMLDocument, se incluyen en Bizagi principalmente por compatibilidad hacia atrás. Estos métodos web (como por ejemplo, createCases, getEntities, queryCases, performActivity, o saveEntity) utilizan la clase XMLDocument la cual es propiamente nativa del framework de .NET y no permite mejores prácticas de interoperabilidad. |
2. Nodo raíz obligatorio
Cuando se utiliza el API de Bizagi (o incluso cuando Bizagi recibe una respuesta de un servicio externo invocado), el XML resultante (después de cualquier transformación) siempre deberá incluir un nodo raíz.
Este concepto es aplicable como buena práctica de manera general para los archivos XML, los cuales son correctamente estructurados si contienen un nodo raíz.
3. Uso de la sintaxis CDATA
Cuando se utiliza el API de Bizagi (o incluso cuando Bizagi recibe una respuesta de un servicio externo invocado), tenga presente que el XML deberá estar bien formado (sin elementos sin cerrar).
Se recomienda enfáticamente utilizar la definición CDATA dentro de la sintaxis del XML para envolver cualquier información de negocio que pueda interferir con el adecuado cierre de los elementos.
El uso de CDATA es estándar a los XMLs como mejor práctica para asegurarse de que los caracteres especiales (aquellos propios de la notación XML como apóstrofes, comillas, ampersand o signos mayor y menor que) se interpreten adecuadamente.
El uso de la sintaxis CDATA le permitirá escapar estos caracteres.
El siguiente ejemplo muestra el uso del elemento CDATA en una invocación getActivitiesAsString:
<![CDATA[<BizAgiWSParam><domain>domain</domain><userName>admon</userName></BizAgiWSParam>]]>
El siguiente ejemplo muestra el uso del elemento CDATA en una invocación getEntities :
<BizAgiWSParam><EntityData><EntityName>Customer</EntityName><Filters><![CDATA[ Active=1 ]]></Filters>
</EntityData></BizAgiWSParam>
|
Tenga en cuenta que hay herramientas especializadas que son clientes SOAP que requieren el uso de CDATA u otros tratamientos especiales para enviar información, como por ejemplo, SOAP UI. Por lo tanto, consulte la documentación de esas herramientas particulares para conocer si requieren de manejos especiales. |
4. Formato de fechas
Cuando se utiliza el API de Bizagi (o incluso cuando Bizagi recibe una respuesta de un servicio externo invocado), tenga presente que para enviar fechas se requiere del formato estándar de XML para fechas completas.
Deberá asegurarse de utilizar el siguiente formato:
YYYY-MM-DDTHH:mm:ss
5. Archivos enviados como adjuntos
Cuando se utiliza el API de Bizagi (o incluso cuando Bizagi recibe una respuesta de un servicio externo invocado), tenga presente que para enviar archivos se requiere codificarlos como cadenas en base 64.
Para ver un ejemplo de cómo enviar adjuntos a procesos Bizagi desde una aplicación externa, consulte Cargar archivos o imágenes desde una aplicación externa.
6. Eliminar relaciones
Cuando utiliza los métodos del API de Bizagi para guardar o actualizar datos desde las entidades de Bizagi (es decir, Guardar Entidad, Realizar Actividad o Establecer Evento). Usted puede utilizar la etiqueta <REMOVE> para eliminar registros de una colección.
Necesitará especificar los registros que serán eliminados utilizando la llave de negocio (businesskeys) de cada registro.
El siguiente ejemplo muestra cómo eliminar registros de la colección Applicants:
<?xml version="1.0" encoding="utf-8"?>
<BizAgiWSParam>
<Entities idCase="7501" idTask="180">
<idRequest>
<Applicants>
<REMOVE>
<Applicant businessKey="BuroScore=6">
</Applicant>
<Applicant businessKey="BuroScore=9"/>
</REMOVE>
<Applicant>
<BuroScore>100</BuroScore>
</Applicant>
</Applicants>
</idRequest>
</Entities>
</BizAgiWSParam>
En este ejemplo, los solicitantes con BuroScore igual a 6 e igual a 9 serán eliminados de la colección Applicants. Además, se está agregando un nuevo solicitante con BuroScore igual a 100.
7. Asignar como nulo un atributo
En métodos cóm Save Activity o Save Entity usted puede darle un valor nulo a un atributo específico. Para hacer esto, debe dejar en verdadero el atributo "nil" dentro del atributo de la entidad que desea establecer en nulo:
<Entities>
<idRequest>
<Applicants>
<Applicant businessKey="DocumentNumber = '123456'">
<DocumentNumber>123456</DocumentNumber>
<BuroScore nil="true"></BuroScore>
</Applicant>
</Applicants>
</idRequest>
</Entities>
|
El anterior ejemplo no aplica para los atributos de tipo file o image. |
Last Updated 2/8/2022 10:56:41 AM