saveEntityAsString

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Bizagi desde aplicaciones externas > API de Bizagi para aplicaciones externas > Servicios web disponibles > Métodos Web de EntityManagerSOA >

saveEntityAsString

Introducción

Este método se utiliza para actualizar la información de negocio en una Entidad del modelo de datos de Bizagi (desde una aplicación externa).

Por actualizar información, entiéndase: insertar nuevos registros, modificar algunos existentes, o marcarlos como deshabilitados (borrado lógico).

 

 

Este método es especialmente útil para manejar registros de Entidades de Parametrización, dado que sus valores no son modificados a lo largo de las instancias de Procesos.

Este método recibe un único parámetro de entrada el cual contiene los valores a insertar, modificar o deshabilitar.

 

 

Par las Entidades de Parametrización, la invocación a este método actualiza los registros de la misma manera como se puede realizar a través de las opciones de administración del Portal de Trabajo.

Tenga en cuenta que en la administración de Entidades del Portal, se requiere que la Entidad haya sido definida como administrable en ese ambiente específico (por ejemplo, producción.

Para más información sobre esta opción, consulte la Administración de Entidades.

 

note_pin

La descripción en este artículo aplica también para el método Web saveEntity, el cual está disponible en la edición Bizagi .NET.

Para el método saveEntity, el XML que se maneja en la solicitud (request) y en la respuesta (response) son del tipo XmlDocument (nativa de .NET).

Para el método saveEntityAsString la misma estructura de XMLs se maneja, sin embargo este parámetro es de tipo cadena (string).

 

Datos de entrada

 

Esquema de entrada

La estructura del XML que se envia a Bizagi debe ser cumplir con este XSD:

<?xml version="1.0"?>

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">

 <xs:element name="BizAgiWSParam">

         <xs:complexType>

                 <xs:sequence>

                         <xs:element name="Entities" maxOccurs="1">

                                 <xs:complexType/>

                         </xs:element>

                 </xs:sequence>

         </xs:complexType>

 </xs:element>

</xs:schema>

 

Parámetros de entrada

BizAgiWSParam: Es el nodo raíz del XML.

Entities: Dependiendo de lo que se pretenda hacer, puede contener las entidades que se van a actualizar en el caso de entidades paramétricas; o puede contener la jerarquía del modelo entidad relación, comenzando por la entidad del procesos requerido, para actualizar la información del caso. El resto del XML se basa en la estructura del modelo entidad relación. A continuación se presentan dos ejemplos, en el primero de ellos se actualiza información en entidades paramétricas y en el segundo se muestra como actualizar información en el caso.

Se puede ver fácilmente la diferencia entre una actualización y una inserción ya que la actualización requiere una especificación explícita de la llave primaria (o llaves primarias) de los registros que se van a actualizar, e.g. key="valor" (o businessKey="Attributo=valor"); las inserciones no requieren esta especificación.

Tenga presente que al apoyarse en llaves de negocio (business keys), se recomienda principalmente utilizar la definición de llaves de negocio dentro de Bizagi Studio como se indica en Usando llaves de negocio en archivos XML (esto quiere decir, preferiblemente sin usar explícitamente la cláusula businessKey dentro del XML como se describió anteriormente).

Para más información sobre la estructura esperada de los elementos dentro de Entities, consulte cómo se representan el modelo de datos del Proceso en Esquema XML de Bizagi para el modelo de datos .

 

note_pin

Para deshabilitar un registro, puede hacer uso del atributo llamado dsbl[Entidad] que adiciona Bizagi a toda entidad paramétrica. En el ejemplo 1 a continuación se ilustra esta posibilidad.

 

 

Ejemplo # 1

Con el siguiente ejemplo, se realizan 3 operaciones diferentes a la Entidad de Parametrización llamada Ciudad (City):

 

Con la primera operación, se ingresa un nuevo registro.

Con la siguiente, se modifica el nombre de un registro que se ubica por su llave primaria.

Con la última, se deshabilita un registro (borrado lógico). Puntualmente de la ciudad con código 3 (válido para entidades paramétricas).

 

SaveEntity_Image002

 

Para la primera operación, nótese que la Entidad tiene un atributo que referencia a otra Entidad de Parametrización que en este ejemplo es la Entidad País (Country).

En este escenario, establecemos la relación a un registro existente de país.

Para ello hay dos opciones:

 

La primera involucra el uso del atributo XML llamado businessKey, como se muestra en la imagen superior.

Esta opción aplica si no hay una definición explícita de llaves de negocio predefinidas en esa Entidad.

 

Por otro lado, está la opción de usar la sintaxis de XML para un nuevo registro (si ya hay llaves de negocio predefinidas):

SaveEntity_Image006

 

 

Para más información sobre el uso de llaves de negocio, consulte Usando llaves de negocio en XMLs.

 

 

En la segunda operación, utilizamos un atributo llamado key.

Dado que cada Entidad en Bizagi tiene un atributo que es asignado como llave primaria de Bizagi, se puede ubicar un registro por medio de la llave subrogada.

Este atributo se ubica como el atributo con id como prefijo, seguido del nombre de la Entidad (por ejemplo idCountry para la Entidad Country).

 

note_pin

Es posible utilizar también el atributo businessKey para definir una llave compuesta. Esto significa utilizar más de un atributo para la definición de una llave de negocio en los registros. Por ejemplo: businessKey=" DocumentNumber='123456' and DocumentType='Passport'  ".

 

 

Si se conoce el valor de este atributo de antemano (se sabe cuál es la llave surrogada para un registro), se puede actualizar un registro como se muestra en la primera imagen para la ciudad llamada Bogotá D.C..

 

 

 

En la tercera operación, utilizamos un atributo que Bizagi crea de manera automática en las Entidades de Parametrización para deshabilitar registros.

Este atributo maneja un borrado lógico (donde estos registros no estarían disponibles para nuevas instancias de Procesos) ya que el borrado físico comprometería la integridad de los datos (integridad referencial en instancias existentes).

 

En la Capa SOA, este atributo se ubica con el prefijo dsbl seguido del nombre de la Entidad.

Por ejemplo, el atributo de la primera imagen que nos muestra dsblCity, que sería el atributo de deshabilitar registros para le Entidad City.

 

Nótese que en este ejemplo, deshabilitamos un registro cuya llave es key=3 (también se usa el atributo key).

 

 

Ejemplo #2

En este ejemplo, se ilustra como actualizar la información de negocio de una instancia de Proceso en particular (un caso existente):

 

SaveEntity_Image003

 

En este escenario, usamos el atributo XML idCase (para asignar 340 al DocumentNumber para el caso con identificador=9001).

 

 

Datos de salida

 

Esquema y Parámetros de salida

La estructura del XML que se retorna en Bizagi cumple con este XSD:

<?xml version="1.0"?>

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">

 <xs:element name="Entities">

         <xs:complexType/>

 </xs:element>

</xs:schema>

 

Los elementos al interior de Entities, corresponden a la estructura (atributos y relaciones) de la Entidad, como se define en Bizagi.

 

Ejemplo

Con el siguiente ejemplo, se ilustra la respuesta que retorna la invocación de este método en Bizagi, en donde vemos la respuesta de una invocación exitosa para:

 

Una Entidad de Parametrización: se tienen la información de las llaves involucradas (ids):

SaveEntity_Image004

 

Una Entidad Maestra (por ejemplo, al actualizar información de un caso):

 

SaveEntity_Image005

 

 

Poblando o sincronizando usuarios

Este método puede utilizarse para poblar o sincronizar usuarios desde un repositorio externo hacia Bizagi.

Para ver mayor información o un ejemplo sobre esto, consulte Sincronizando usuarios via web.

 

Métodos Web relacionados

Para actualizar la información de negocio de un caso particular (por ejemplo, datos de Entidades maestras), es común utilizar un método que asocie esta información a una Actividad o Evento, a través de los métodos performActivityAsString o setEventAsString.

Para más información sobre estos métodos del motor BPMN de Bizagi, consulte los servicios Web de WorkflowEngineSOA.

 

También es posible que se desee obtener previamente el esquema de la Entidad a utilizar como dato de entrada en este método. Para hacerlo de una manera dinámica, use los métodos getEntitySchemaStr o getEntitySchema.

Para más información sobre esta opción, consulte getEntitySchemaStr.