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). Este método solo está disponible para Entidades Paramétricas, Entidades Maestras y la entidad WFUSER.
Por actualizar información, entiéndase: insertar nuevos registros, modificar algunos existentes, o marcarlos como des-habilitados (borrado lógico).
Este método es especialmente útil para manejar registros de Entidades de Paramétricas, dado que sus valores no son modificados a lo largo de las instancias de Procesos.
En el ambiente de Producción, puede ser usado para afectar entidades administrables en Producción exclusivamente.
Este método recibe un único parámetro de entrada el cual contiene los valores a insertar, modificar o deshabilitar.
Par las Entidades de Paramétricas, 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.
•En el método saveEntity, los XMLs de petición y de respuesta son de tipo XmlDocument nativo de .NET.
•En el método saveEntityAsString se maneja la misma estructura XML pero los parámetros son enviados como un tipo cadena de texto por medio de CDATA.
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 .
|
•Para desactivar 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. •Cuando agregue valores con Llaves de Negocio, envíe todos los atributos que componen dicha llave, incluso si uno o más valores están vacíos. Por defecto, Bizagi asignará nulo a los valores vacíos. |
Ejemplo de entrada
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).
Entrada del método SaveEntity
<BizAgiWSParam>
<Entities>
<City>
<Name>Cartagena</Name>
<Code>4</Code>
<Country businessKey="Code='1'"/>
</City>
<City key="2">
<Name>Bogota D.C.</Name>
</City>
<City businessKey="Code='3'" >
<dsblCity>true</dsblCity>
</City>
</Entities>
</BizAgiWSParam>
Entrada del método SaveEntityAsString
<entityInfo>
<![CDATA[<BizAgiWSParam>
<Entities>
<City>
<Name>Cartagena</Name>
<Code>4</Code>
<Country businessKey="Code='1'"/>
</City>
<City key="2">
<Name>Bogota D.C.</Name>
</City>
<City businessKey="Code='3'" >
<dsblCity>true</dsblCity>
</City>
</Entities>
</BizAgiWSParam>]]>
</entityInfo>
Para la primera operación, nótese que la Entidad tiene un atributo que referencia a otra Entidad Paramétrica 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):
Entrada del método SaveEntity con llaves de negocio predefinidas
<BizAgiWSParam>
<Entities>
<City>
<Name>Cartagena</Name>
<Code>4</Code>
<Country>
<Code>1</Code>
</Country>
</City>
</Entities>
</BizAgiWSParam>
Entrada del método SaveEntityAsString con llaves de negocio predefinidas
<entityInfo>
<![CDATA[<BizAgiWSParam>
<Entities>
<City>
<Name>Cartagena</Name>
<Code>4</Code>
<Country>
<Code>1</Code>
</Country>
</City>
</Entities>
</BizAgiWSParam>]]>
</entityInfo>
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).
|
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 Paramétricas 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 de entrada - Actualizar información
En este ejemplo, se ilustra como actualizar la información de negocio de una instancia de Proceso en particular (un caso existente):
Entrada del método SaveEntity - Actualizar información
<BizAgiWSParam>
<Entities idCase="1">
<Vacations>
<VacationRequest>
<Applicant>
<IdentificationNumber>159753</IdentificationNumber>
</Applicant>
</VacationRequest>
</Vacations>
</Entities>
</BizAgiWSParam>
Entrada del método SaveEntityAsString - Actualizar información
<entityInfo>
<![CDATA[<BizAgiWSParam>
<Entities idCase="1">
<Vacations>
<VacationRequest>
<Applicant>
<IdentificationNumber>159753</IdentificationNumber>
</Applicant>
</VacationRequest>
</Vacations>
</Entities>
</BizAgiWSParam>]]>
</entityInfo>
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, que varía dependiendo del tipo de Entidad involucrado (Maestra o Paramétrica):
Para las Entidades Paramétricas, se tienen la información de las llaves involucradas (IDs):
Salida del método SaveEntity - Entidades Paramétricas
Salida del método SaveEntityAsString - Entidades Paramétricas
Una Entidad Maestra (por ejemplo, al actualizar información de un caso), el XML de respuesta tendrá un único nodo vacío llamado Entities:
Salida del método SaveEntity - Entidad Maestra
Salida del método SaveEntityAsString - Entidad Maestra
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 Obtener el Esquema de una Entidad.
Last Updated 1/28/2022 4:00:35 PM