XML Helper para interfaces

<< Clic para mostrar Tabla de Contenidos >>

Navegación:  Bizagi Studio > Asistente de Procesos > Reglas de Negocio > Ejemplos de reglas de negocio >

XML Helper para interfaces

Introducción

La invocación de servicios de un sistema externo se configura de una manera fácil en Bizagi a través del Conector de servicios web (WS Connector).

El Conector de servicios web de Bizagi soporta funcionalidad estándar SOAP y de servicios REST, y presenta características de mapeo gráfico que permite que las entradas y salidas se manejen sin la necesidad de programación.

Incluso, se puede sobrescribir el comportamiento del mapeo gráfico de manera que se usen en cambio archivos de transformación XSL personalizados.

Para mayor información, consulte Invocar servicios externos desde Bizagi.

 

En escenarios más sofisticados donde la configuración de un servicio web de tipo SOAP no es posible mediante el Conector de servicios web, sea por el mapeo gráfico o con transformaciones, usted podrá optar por:

1. Apoyarse en la funcionalidad de Librería de componentes que le permite desarrollar su propio cliente que consuma el servicio web (opción preferida).

Para mayor información, consulte la Librería de componentes.

2. Invocar un servicio web desde una regla de negocio de Bizagi, por medio del elemento de Servicio web que se presenta visualmente (deprecado, disponible principalmente por compatibilidad hacia atrás).

De todas maneras, en este caso también es más recomendado por mantenibilidad y mejores prácticas, hacer uso de la Librería de componentes.

Nótese que si aún desea utilizar el elemento de Servicio web en este escenario y si las entradas y salidas involucradas usan elementos XML de tipo complejo (no datos primarios como enteros o Booleanos), entonces usted podrá apoyarse en la clase XML Helper como se describe a continuación.

 

 

¿Cuando son estas otras alternativas válidas?

Los escenarios sofisticados en los que el uso del Conector de servicios web no suele ser viable son:

Cuando los servicios web se han construido con estándares no soportados por el Conector de servicios web.

Recuerde que este Conector soporta un amplio conjunto de estándares que incluyen SOAP 1.0 y 1.1, WSDL 1.0 y otros aspectos considerables de extensiones como por ejemplo WS-Security.

En estos casos, se recomienda utilizar la Librería de componentes (por encima del elemento de Servicio web de las reglas), dado que el Conector de servicios web soporta más estandares que los soportados por el elemento de Servicio web.

Cuando usted necesita invocar un servicio X veces, mientras se itera por elementos de una colección.

Esto implica cuando el servicio web para invocar no recibe un arreglo de ítems sino que recibe información de solo un ítem (y por ende se debe invocar múltiples veces).

 

 

Clase XML Helper

Bizagi provee un conjunto funcional de métodos en el API de reglas para el manejo de XMLs e información como la maneja Bizagi (tanto para enviar como para recibir de interfaces).

 

 

 

Antes de continuar

Tenga en cuenta que el uso de estos métodos comúnmente requiere de habilidades técnicas orientadas a la programación con archivos XMLs y transformaciones (XSLT), y también exige experiencia con Bizagi en el manejo de sus datos y los scopes.

Para mayor información, consulte Scopes.

Nótese que estos métodos a nivel general, podrán usualmente:

Recibir o retornar instancias de entidades en sus parámetros, de manera que antes de usar estos métodos, podrá ser necesario el uso de  la clase CEntityManager y sus métodos.

Requerir o alimentarse de esquemas XML y de transformaciones previamente definidas a partir de las definiciones de las entidades.

Para más información sobre esta opción, consulte los Esquemas XML del modelo de datos de Bizagi.

 

 

Métodos

Lo siguientes métodos se clasifican por el tipo de información que manejan y por su objetivo.

Los métodos son invocados a través de la clase CEntityXmlHelper

 

Métodos para consultar información directamente en entidades

Estos deben usarse principalmente cuando se trabaja con entidades de parametrización.

 

MÉTODO

ENTRADAS

SALIDAS

DESCRIPCIÓN

NOTAS

getEntitiesAsString

 

getEntityData

string entityInfo, string xsd

string

Obtiene registros de la entidad especificada.

 

El parámetro entityInfo es una cadena (string) presentando una definición en estructura XML, donde se especifica la entidad a consultar, con filtros opcionales.

La estructura XML debe ser cómo se especifica en el método web getEntitiesAsString del API de Bizagi.

 

El parámetro xsd es una cadena (string) presentando un esquema de XML, de manera que éste incluya los atributos que se deben retornar.

Los otros métodos similares a este están deprecados y se preservan principalmente por compatibilidad hacia atrás.

Los métodos que no deberían utilizarse son:

XmlDocument getEntities (XmlDocument, XmlDocument)

XmlDocument getEntities (XmlDocument)

String getEntitiesFromPathAsString (string, string)

entityToStringXml

CEntity entity, string xsd

string

Obtiene registros de la entidad especificada.

 

El parámetro entity es una instancia del objeto de la entidad dada, usualmente obtenido previamente con expresiones de tipo: CEntityManager.GetEntity("Entity").

 

El parámetro xsd es una cadena (string) presentando un esquema de XML, de manera que éste incluya los atributos que se deben retornar.

Se recomienda enfáticamente utilizar getEntitiesAsString.

 

Los otros métodos similares a este están deprecados y se preservan principalmente por compatibilidad hacia atrás.

Los métodos que no deberían utilizarse son:

XmlDocument entityToXml (CEntity)

XmlDocument entityToXml (CEntity, boolean)

XmlDocument entityToXml (CEntity, string)

String entityToStringXmlwithPath (CEntity, string)

 

 

Métodos para consultar la información de caso (con scopes)

Estos métodos consideran la información que Bizagi maneja para un caso, como la maneja en la tecnología de scopes.

 

MÉTODO

ENTRADAS

SALIDAS

DESCRIPCIÓN

NOTAS

entityToStringXml

WithScopes

Me,

string xsd, string xsl

string

Obtiene información sobre el caso actual.

 

El parámetro Me es necesario para referenciar el caso actual (workitem).

 

El parámetro xsd es una cadena (string) presentando un esquema de XML, de manera que éste incluya los atributos que se deben retornar (éste debe tener como nodo raíz la entidad de aplicación).

 

El parámetro xsl es opcional, y es una cadena (string) presentando un archivo de transformación que se aplica al resultado.

 

entityToStringXml

WithScopesByidCase

int IdCase,

string xsd,

string xsl

string

Obtiene información sobre un caso.

Al compararse con entityToStringXmlWithScopes, este otro método es útil si se desea consultar otro caso diferente al actual.

 

El parámetro xsd es una cadena (string) presentando un esquema de XML, de manera que éste incluya los atributos que se deben retornar (éste debe tener como nodo raíz la entidad de aplicación).

 

El parámetro xsl es opcional, y es una cadena (string) presentando un archivo de transformación que se aplica al resultado.

Los otros métodos similares a este están deprecados y se preservan principalmente por compatibilidad hacia atrás.

Los métodos que no deberían utilizarse son:

String entityToStringXmlWithScopesXmlByidCase (int, XmlDocument, XmlDocument)

getCaseData

int IdCase,

string XPath,

string xsd,

string xsl

string

Obtiene información sobre un caso, de manera similar al método entityToStringXmlWithScopesByidCase.

 

Cuando se compara con este otro método, el parámetro diferente es XPath, el cuál recibe la ruta de navegación Xpath inicial.

 

 

 

Métodos para insertar información directamente en entidades

Estos deben usarse principalmente cuando se trabaja con entidades de parametrización.

Para el uso de estos métodos, considere la definición de llave de negocio en sus entidades, como se describe en Usando llaves de negocio en XMLs.

 

MÉTODO

ENTRADAS

SALIDAS

DESCRIPCIÓN

NOTAS

fromXmlToEntity

string entityInfo

CEntity

Inserta o actualiza información en la entidad especificada.

 

El parámetro entityInfo es una cadena (string) presentando una definición en estructura XML, donde se contiene la información a insertar o actualizar.

La estructura XML debe ser cómo se especifica en el método web saveEntitiesAsString del API de Bizagi.

Los otros métodos similares a este están deprecados y se preservan principalmente por compatibilidad hacia atrás.

Los métodos que no deberían utilizarse son:

CEntity fromXmlToEntityAsXml (XmlDocument)

saveEntitiesData

string entityInfo

string

Inserta o actualiza información en la entidad especificada.

 

El parámetro entityInfo es una cadena (string) presentando una definición en estructura XML, donde se contiene la información a insertar o actualizar.

La estructura XML debe ser cómo se especifica en el método web saveEntitiesAsString del API de Bizagi.

 

 

Métodos para actualizar la información del caso (con scopes)

Estos métodos consideran la información que mantiene Bizagi en su scope.

 

MÉTODO

ENTRADAS

SALIDAS

DESCRIPCIÓN

NOTAS

fromXmlToEntity

WithScopes

Me,

string entityInfo,

boolean businessKeys

CEntity

Inserta o actualiza información en el caso actual.

 

El parámetro Me es necesario para referenciar el caso actual (workitem).

 

El parámetro entityInfo es una cadena (string) presentando una definición en estructura XML, donde se contiene la información a insertar o actualizar.

La estructura XML debe ser cómo se especifica en el método web saveEntitiesAsString del API de Bizagi, pero asegurando que el nodo raíz sea la entidad de Aplicación.

 

El parámetro businessKeys es para asignar a falso para utilizar las definiciones de llaves de negocio.

Los otros métodos similares a este están deprecados y se preservan principalmente por compatibilidad hacia atrás.

Los métodos que no deberían utilizarse son:

CEntity fromXmlToEntityWithScopesAsXml (Me, XmlDocument)

CEntity fromXmlToEntityWithScopes (Me, string)

CEntity fromXmlToEntityWithScopesAsXml (Me, XmlDocument, boolean) )

saveCaseData

int idCase,

string entityInfo,

boolean businessKey

void

Inserta o actualiza información a un caso.

 

El parámetro idCase especifica el caso a actualizar.

 

El parámetro entityInfo es una cadena (string) presentando una definición en estructura XML, donde se contiene la información a insertar o actualizar.

La estructura XML debe ser cómo se especifica en el método web saveEntitiesAsString del API de Bizagi, pero asegurando que el nodo raíz sea la entidad de Aplicación.

 

El parámetro businessKeys es para asignar a falso para utilizar las definiciones de llaves de negocio.

 

 

 

Métodos para manipular información (usando esquemas y transformaciones de XML)

Por ejemplo, estos métodos permiten aplicar transformaciones XML a los datos de negocio.

 

MÉTODO

ENTRADAS

SALIDAS

DESCRIPCIÓN

NOTAS

getEntitySchema

 

string entityName

bool includeRelated, bool includeCollections

XmlDocument

Obtiene el esquema (XSD) de una entidad especificada.

 

El parámetro entityName simplemente especifica el nombre de la entidad.

 

El parámetro includeRelated deberá ser verdadero cuando necesite incluir las entidades referenciadas.

 

El parámetro includeCollections deberá ser verdadero cuando necesite incluir las colecciones en esa entidad (facts).

Los otros métodos similares a este están deprecados y se preservan principalmente por compatibilidad hacia atrás.

Los métodos que no deberían utilizarse son:

XmlDocument getEntitySchema (string)

XmlDocument getEntitySchemaAsEntity (CEntity)

XmlDocument getEntitySchema (string, string)

XmlDocument getEntitySchemaAsEntity (CEntity, string)

XmlDocument getEntitySchemaAsEntity (CEntity, boolean, boolean)

transformXmlAsString

 

transformXml

string xml,

string xsl

String

Aplica una transformación, apoyándose en el estándar de XSLT 1.1.

 

El parámetro xml es una cadena (string) presentando una definición en estructura XML con la información.

 

El parámetro xsl es una cadena (string) presentando un archivo de transformación que se aplica al resultado.

Los otros métodos similares a este están deprecados y se preservan principalmente por compatibilidad hacia atrás.

Los métodos que no deberían utilizarse son:

XmlDocument transformXml (XmlDocument, XmlDocument)

String transformXmlUsingPath (string, string)

String transformXmlUsingContent (string, string)