De

<keywords content="keywords"> getEntitySchema, esquema de entidad, getEntitySchemaStr, getEntities, getEntitiesAsString, getEntitiesUsingSchema, getEntitiesUsingSchemaAsString, saveEntity, SaveEntities, Scopes, saveEntityAsString, saveEntityWithKey </keywords>

Contenido 1 Métodos de EntityManagerSOA 1.1 getEntitySchema 1.2 getEntitySchemaStr 1.3 getEntities 1.3.1 Registros Deshabilitados 1.3.2 Estructura de Salida XML 1.4 getEntitiesAsString 1.5 getEntitiesUsingSchema 1.6 getEntitiesUsingSchemaAsString 1.7 saveEntity 1.7.1 Manipulación de SaveEntities con Scopes 1.8 saveEntityAsString 1.9 saveEntityWithKey

Métodos de EntityManagerSOA

getEntitySchema

El nombre de entidad es el parámetro requerido por este método. Este método retorna un documento XML junto con el esquema de entidad.

El programa a ser invocado por el servicio web contendrá las siguientes líneas:

//An object reference to the web service EntityManagerSoa is created
EntityManagerSOA.EntityManagerSOA emSOA = new EntityManagerSOA.EntityManagerSOA(); 

//The method getEntitySchema is invoked, the name of the entity along with the key of an existing record 
//are passed 
XmlNode node = emSOA.getEntitySchema("Client"); 

//Operations are performed to save the results to disk 
XmlDocument scheme = new XmlDocument(); 
scheme.LoadXml(node.OuterXml);
scheme.Save(@"D:\SOA\Outputs\Scheme.xsd")

El método retorna el siguiente esquema:

El esquema ofrece la estructura de entidad con el FACT y la estructura de la entidad relacionada.

getEntitySchemaStr

Este método también retorna un esquema de entidad. El nombre de entidad es también un método requerido por este método. El método retorna el esquema de entidad en una cadena.

getEntities

Este método retorna un documento XML con la información requerida por la entidad. Un documento XML es el parámetro requerido por este método; en este parámetro se especifica el nombre de la entidad para la cual se requiere.

El XML que recibe el servicio web debe preservar la estructura especificada, que se detalla a continuación:

Tag Root <BizAgiWSParam>: El elemento raíz (root) del xml que recibe el método getEntities, el encabezado del documento XML (<?xml version="1.0" encoding="utf-8"?>) no se incluye.

Tag <EntityData>: Este tag define el comienzo de la información descriptiva relacionada con la entidad a ser solicitada.

Tag <EntityName>: El elemento usado en este tag es el nombre de la entidad solicitada.

Tag <Filters>: Este tag es opcional y se puede incluir cuando la información de uno o más registros que llenan una condición especial se requiere,

<Filters>

<![CDATA[

        idRequest = 5

        ]]>

</Filters>

Tag <![CDATA[ condition]]>: Este tag contiene la información usada para realizar una búsqueda filtrada sobre la entidad seleccionada. Las palabras OR/AND se pueden usar para crear validaciones con operadores lógicos como

<![CDATA[

        (DocumentType = 1 OR City= 2) AND Approved = true

        ]]>

Comillas simples deben añadirse para crear cadenas de filtros

<![CDATA[

        Option  = 'Automatic'

        ]]>

De forma similar, los operadores >, <, >= y <= se pueden usar. El formato de fecha de la base de datos debe incluirse en el formato XML cuando un filtro con fechas se requiere.

<![CDATA[

    date1 >= '06/05/2008'

    ]]>

Un programa que ilustra el uso de este método de servicio Web tendría las siguientes líneas:

//An object reference to web service EntityManagerSoa is created
EntityManagerSOA.EntityManagerSOA emSOA = new EntityManagerSOA.EntityManagerSOA();

//A XmlDocument object that will contain the xml document is created as an input
XmlDocument xDoc = new XmlDocument();
xDoc.Load(@"D:\SOA\Inputs\GetEntityRequest.xml");

//The method getEntities of the SOA layer is invoked
XmlNode node = emSOA.getEntities(xDoc);

//Operations are performed to save the results to disk
XmlDocument resp = new XmlDocument();
resp.LoadXml(node.OuterXml);
resp.Save(@"D:\SOA\Outputs\getEntitiesOutput.xml");

La respuesta en documento xml es presentada como sigue:

La respuesta en documento XML muestra los datos de la entidad y también los datos de la entidad relacionada o FACT, que puede ser observada un las selecciones resaltadas con color rojo. La información provista por el método getEntities desciende a un nivel más bajo; entonces, la información de entidades relacionadas a la entidad solicitada puede ser extraída. El FACT debe estar relacionado a la entidad solicitada a través del XML y no con la entidad donde los registros esperados se localizan cuando la información una muchos a muchos (N a M) es requerida.

Registros Deshabilitados

Normalmente, una consulta que usa los métodos getEntities, getEntitiesAsString, getEntitiesUsingSchema o getEntitiesUsingSchemaAsString no retornará registro deshabilitados (borrado lógico); sin embargo, si esta información es alguna vez requerida, se puede obtener al añadir el tag <FilterDisabled> al XML de solicitud y establecer el valor a falso (false). Éste es un ejemplo de ese XML:

Estructura de Salida XML

El Tag <BizAgiWSResponse> es el primer elemento del documento de respuesta, que es seguido por el tag <Entities>. El tag con el nombre de la entidad requerida es incluido subsecuentemente, en este ejemplo, <Request>, y el resto de líneas contendrá la información relacionada para la entidad solicitada.

getEntitiesAsString

Este método provee la misma funcionalidad como el método getEntities; sin embargo, el contenido y la respuesta del documento XML son recibidos y provistos como una cadena, respectivamente.

//An object reference to EntityManagerSoa web service is created
EntityManagerSOA.EntityManagerSOA emSOA = new EntityManagerSOA.EntityManagerSOA();

//An Xml Document object that will contain the content of the input xml 
//document is created
XmlDocument xDoc = new XmlDocument();
xDoc.Load(@"D:\SOA\Inputs\GetEntityRequest.xml");

//The method getEntities of the Soa layer is invoked
string resp = emSOA.getEntitiesAsString(xDoc.OuterXml);

getEntitiesUsingSchema

Este método permite obtener la entidad en un documento XML; este documento tendrá el mismo formato usado para el esquema recibido como un parámetro.

Documento XML

Esquema

Un programa que invoca este método de servicio Web tendrá las siguiente líneas

//An object reference to web service EntityManagerSoa is created
EntityManagerSOA.EntityManagerSOA emSOA = new EntityManagerSOA.EntityManagerSOA();

//An XmlDocument object that will contain the content of xml document 
//input is created
XmlDocument xDoc = new XmlDocument();
xDoc.Load(@"D:\SOA\Inputs\info.xml");

XmlDocument xSch = new XmlDocument();
xSch.Load(@"D:\SOA\Inputs\SchemaRequest2.xsd");

XmlNode node = emSOA.getEntitiesUsingSchema(xDoc, xSch);
XmlDocument output = new XmlDocument();
output.LoadXml(node.OuterXml);
output.Save(@"D:\SOA\Outputs\DocumentOutput.xml");

El documento xml de salida se muestra a continuación:

getEntitiesUsingSchemaAsString

Este método es una variante del anterior. El método recibe una cadena con el contenido de documentos XML y XSD en vez de recibir directamente los documentos XML y XSD. De modo similar, el método retorna una cadena con el contenido de la entidad de acuerdo al formato XSD usado para la entrada en vez de retornar directamente un documento XML.

//An object reference to webservice EntityManagerSoa is created
EntityManagerSOA.EntityManagerSOA emSOA = new EntityManagerSOA.EntityManagerSOA();

//An Xml document object that will contain the content of the xml document 
//input is created
XmlDocument xDoc = new XmlDocument();
xDoc.Load(@"D:\Temp\soa-30052006\SOA\Input\info.xml");
XmlDocument xEsq = new XmlDocument();
xEsq.Load(@"D:\Temp\soa-30052006\SOA\Input\EsquemaRequest2.xsd");
string output = emSOA.getEntitiesUsingSchemaAsString(xDoc.OuterXml, xEsq.OuterXml);

saveEntity

Este método recibe como un parámetro la información de la entidad en la que se insertará un nuevo registro o uno existente será actualizado. Una actualización puede diferenciarse de una inserción porque la actualización requiere la especificación explícita de la llave primaria del registro que será actualizado, i.e., key='value'; por otro lado, las inserciones no requieren esta especificación.

Un documento xml que referencie una inserción se muestra a continuación:

Una inserción en la organización de entidad V_Request y la configuración de los campos idRequesStatus, idAcessWay, RadicationDate, idRadicationOffice se puede observar en el ejemplo anterior.

La estructura del documento XML que recibe este método se presenta en seguida.

Tag BizAgiWSParam: El tag root del documento XML; el encabezado (<?xml version="1.0" encoding="utf-8" ?>) no se incluye en este documento.

Entidades de Tag (Tag Entities): Las Entidades de Tag (tag Entities) delimitan la informaicón relacionada con la entidad que será insertada o actualiazada en la base de datos.

Datos de Entidad Tag (Tag Entity Data): Finalmente, los elementos de la entidad que serán inserados son descritos. La descripción empieza con el nombre de la organización, en este caso V_Request y continúa con los valores de los atributos que serán insertados en la entidad.

//An object reference to webservice EntityManagerSoa is created
EntityManagerSOA.EntityManagerSOA emSOA = new EntityManagerSOA.EntityManagerSOA();

//An XmlDocument object that will contain the content of the xml document 
//input is created
XmlDocument xDoc = new XmlDocument();
xDoc.Load(@"D:\SOA\Inputs\insert2.xml");

//Invokes the method saveEntity of the Soa layer
XmlNode node = emSOA.saveEntity(xDoc);

//Operations are performed to save the response to disk
XmlDocument output= new XmlDocument();
output.LoadXml(nodo.OuterXml);
output.Save(@"D:\SOA\outputs\outputssave.xml");

Un XML simple se recibe como respuesta; ahí, un nodo muestra el id del registro para la entidad actualizada. Los ids de los registros actualizados en entidades relacionadas o FACT no son mostrados; sólo el id de la entidad raíz (root).

El registro donde la llave primarias igual a 1 para la entidad Solicitud (Request) será actualizado; el atributo RadicationOffice será fijado a 1 y el registro que contiene los valores de los atributos Cliente (Client), ClientRole, Existir (Exist), DocumentType, y DocumentNumber será insertado en la tabla ClientRequest. Los valores para este registro pueden observarse en el documento xml.

El documento de retorno contiene sólo el id del registro de la entidad de más alto nivel actualizada o donde el registro fue insertada:

<Entities xmlns="">

<Request>576</Request>

</Entities>

Es posible la actualización de los registros en las entidades sin saber la llave sustituta; por lo tanto, el uso de llaves de negocio para determinar el registro a ser actualizado es factible. Esta llave de negocio debe ser un valor único dentro del grupo de registro de la entidad a ser actualizada.

Un ejemplo del uso de las llaves para actualizar registros se muestra a continuación:

Las llaves de Negocio se pueden usar también para actualizar registros en FACTS

Manipulación de SaveEntities con Scopes

Los datos que graban en una instancia de proceso deben ser contextualizados cuando el proceso soporta ámbitos (scopes). La instancia idCase debe especificarse para la instancia del proceso que será actualizada dentro del XML a través del atributo "idCase", como se ilustra a continuación:

El idCase ha sido provisto en un formato de atributo XML en el nodo Entidades (Entities). Este id puede incluirse también en la entidad que será grabada, como se ilustra en el siguiente ejemplo; el nodo con el mismo nombre de la entidad tendrá prioridad (en este caso "Negocio" (Business) en el nodo principal "Entidades" (Entities)).

El ejemplo también muestra el atributo "XPath" que indica el camino hacia la entidad; el camino empieza con la Entidad de Aplicación (Application Entity) (el PV), incluyendo el camino de la entidad que será actualizada. Por ejemplo, la relación entre PV y "Gestión" (Management) a través del atributo Gestión (Management) es asumida cuando la entidad de Negocio debe ser modificada. Del mismo modo, la relación "Gestión" (Management) con "Negocio" (Business) a través del atributo "Negocio" (Business) se asume, como se ilustra en este ejemplo.

Otra forma para contruir el XML con la estructura indicada poe el XPATH para llegar a la entidad requerida se muestra a continuación:

Cuando Gestión (Management) es el atributo con el que PV se relaciona a la tabla GESTIÓN (MANAGEMENT), la cual está también relacionada por el atributo Business a BUSINESS, que es la entidad que contiene el atributo Code. Este formato es válido también cuando el proceso soporta scopes. idCase es mandatorio para especificar el contexto.

saveEntityAsString

Este método es una derivación de los métodos saveEntity; entonces, este método también recibe como parámetro el documento XML, en formato de cadena, que contiene la información de la entidad en la que el nuevo registro será insertado o un registro existente será actualizado. De modo similar, el contenido del documento XML se retorna como una cadena.

//An object reference to web service EntityManagerSoa is created
EntityManagerSOA.EntityManagerSOA emSOA = new EntityManagerSOA.EntityManagerSOA();

//An XmlDocument object that will contain the content of the xml input document
XmlDocument xDoc = new XmlDocument();
xDoc.Load(@"D:\SOA\Inputs\insert2.xml");

//The method saveEntityAsString of the Soa layer is invoked
//The OuterXml property is used to convert the content of the object to String
//XmlDocument

string rta = emSOA.saveEntityAsString(xDoc.OuterXml);

saveEntityWithKey

Este método permite actualizar registros de entidad existentes. El método recibe como parámetro un documento XML con el contenido de la entidad que será actualizada y la llave primaria del registro que será modificado; el método retorna un documento XML.

El ejemplo anterior muestra que los atributos RequestStatus, RadicationOffice, RadicationDate y Approved será actualizados. En otros lugares, la llave del registro que será actualizado no puede visualizarse en el documento porque la llave se pasa como un parámetro separado cuando el método se invoca.

//An object reference to webservice EntityManagerSoa is created
EntityManagerSOA.EntityManagerSOA emSOA = new EntityManagerSOA.EntityManagerSOA();

//An Xml document object that will contain the content of the xml input 
//document is created
XmlDocument xDoc = new XmlDocument();
xDoc.Load(@"D:\SOA\Inputs\savewithkey.xml");
XmlNode node = emSOA.saveEntityWithKey(48, xDoc);

La llave primario del registro que será actualizada es 48. El documento retornado se muestra a continuación:

<comments />