Sharepoint
Para lograr este objetivo, Dynamics 365 presenta un abanico de opciones disponibles para permitir integrarse con otros sistemas, y una de las opciones que está presente en esta nueva versión es la integración a través de OData.
Qué es OData
OData es el acrónimo de Open Data Protocol, el cual define un conjunto de reglas y buenas prácticas para permitir la integración de sistemas de información sin importar la arquitectura, lenguaje o plataforma en la que estén construidos. Este protocolo está basado en la arquitectura de servicios REST, y hace uso especialmente de las tecnologías web HTTP y JSON.
OData y Dynamics 365
En versiones anteriores de Dynamics se contaba con la plataforma AIF y el tipo de servicio “basados en documentos”, que permitía construir rápidamente servicios para exponer datos a partir de un artefacto tipo Query. En esta nueva versión, Microsoft ha dejado de lado la plataforma AIF y los servicios basados en documentos, dejando como reemplazo a los servicios basados en OData.
OData presenta como ventajas frente a AIF:
- Mayor interoperabilidad con otras plataformas y lenguajes al tratarse de un protocolo abierto. AIF estaba basado en la tecnología propietario WCF, la cual tiene ciertos inconvenientes y limitaciones de compatibilidad cuando los sistemas que se intentan conectar son basados en tecnologías no Microsoft.
- JSON al ser un protocolo más liviano que XML mejora el desempeño al reducir el tiempo de procesamiento de peticiones y consumo de ancho de banda.
- El código necesario del lado de cliente para consumir un servicio de OData vs. Un servicio de AIF basado en documentos es más sencillo, legible y rápido de construir.
- Se puede realizar la validación de las entidades expuestas en OData incluso desde un web browser.
Exponiendo datos de Dynamics 365 en OData
Para exponer datos por medio de OData se debe hacer uso de un concepto que ya existía desde AX2012 pero que en esta nueva versión ha tomado mayor importancia: Entidades de datos. Las entidades de datos son artefactos que permiten conectar otros sistemas que necesiten manipular u obtener datos de Dynamics 365 (Por ejemplo, Microsoft Office). También facilitan las integraciones al permitir transformar el complejo modelo de datos normalizado de Dynamics 365 a otro formato intermedio más natural y manejable al usuario o sistema que se vaya a integrar.
Antes de partir con la creación de una Entidad es necesario definir la fuente de datos que se planea exponer. Para efectos de mantener las cosas simples la fuente de datos va a ser una tabla sencilla en 365 creada de ceros con las siguientes características
- 3 campos: Un campo que sirva como llave natural de la tabla (debe ser definido como obligatorio), un campo de descripción y un campo auxiliar
- Un método que sirva para que el valor del campo auxiliar sea igual a la composición de los otros dos campos
- Un índice único basado en la llave natural
La tabla resultante en 365 queda de esta forma. Las características fijadas servirán para mostrar posteriormente conceptos de manipulación de datos sobre OData y de las entidades.
Nótese también que, para cumplir el segundo cometido planteado, se ha sobrescrito el método insert. La lógica agregada es la siguiente:
De esta forma, nuestra fuente de datos está lista.
Con la fuente de datos armada, podemos proceder a crear la entidad de datos. La forma más simple de hacerlo es a través de la opción de menú que se despliega al hacer clic derecho sobre el nodo de la tabla en el diseñador y seleccionar Addins -> Create Data Entity.
Esta opción, tomando como base los metadatos definidos en la tabla, creará todos los artefactos necesarios para poder usar la entidad de datos. Más explícitamente, creará el artefacto de entidad de datos, dos privilegios y una tabla con el sufijo Staging.
Cabe mencionar que otra de las características útiles de las entidades de datos es poseer atributos y métodos de características y funcionamiento similar al de otros artefactos pertenecientes al modelo de datos (Tablas, Vistas), presentando los siguientes comportamientos:
- Los atributos de la entidad sirven como agregación a los existentes en las tablas origen. Por ejemplo, pueden hacer que un dato sea obligatorio cuando en la fuente de datos no lo es, pero no pueden hacer que un campo obligatorio en la fuente deje de serlo en la entidad.
- El comportamiento y funcionamiento de los métodos que se sobrescriban en la entidad no es afectado por la implementación de la fuente de datos origen. Esto quiere decir que la lógica definida en la entidad de datos es totalmente independiente de la definida en la tabla origen.
Para efectos de mostrar lo anterior y para mostrar otros conceptos de OData se va a modificar un método de la entidad de datos recién creada ODataTestEntity para que al crear un nuevo registro automáticamente se inicialice el campo auxiliar IdPlusName con un valor fijo. La sobreescritura se realiza de forma similar a una tabla convencional:
- Abrir la tabla en el diseñador
- Clic derecho en el nodo methods
- Seleccionar el método a sobrescribir
- En el editor de código que se abre inmediatamente, agregar la lógica necesaria al método sobrescrito
El resultado es el siguiente:
Hay un par de puntos importante a tener en cuenta al trabajar con OData y entidades de datos:
- La entidad de datos debe ser marcada como pública (Propiedad IsPublic en Yes) para que se pueda exponer a través de OData.
- Para consultar la entidad en OData a través de web browser se debe usar el valor existente en la propiedad Public Collection Name
Finalmente, se debe compilar el proyecto y sincronizar con la base de datos. Con esto, la entidad de datos es tanto publicada en 365 como habilitada en OData, y la tabla Staging que la misma necesita es creada en la base de datos.
Usando la nueva entidad desde un web browser
El protocolo OData define que la información relativa a todo lo que se expone en un servidor OData debe estar disponible a través de un servicio conocido como $metadata. Es importante conocer este servicio puesto que ya existen herramientas gratuitas y/o de código abierto que pueden tomar las definiciones descargadas de este servicio y generar clases que se encargan de muchas de las operaciones de más bajo nivel, tales como armar las peticiones http, serializar/deserializar las respuestas en JSON, etc., permitiendo que el desarrollador solamente se preocupe por armar la lógica de negocio de la integración.
En Dynamics 365 este servicio siempre está expuesto en una URL de esta forma:
- https://<nombre_de_máquina_entorno>/data/$metadata
Por ejemplo, para las máquinas comunes de 365 para desarrollo descargadas para ejecución on-premises la ruta es https://usnconeboxax1aos.cloud.onebox.dynamics.com/data/$metadata.
Al abrir en un web browser esta ruta, 365 devuelve todas las entidades de datos disponibles en OData y las definiciones relativas a su formato. OData define que este servicio es todo o nada, es decir, se devuelven absolutamente todas las entidades disponibles. 365 out-of-the-box incluye varios cientos de entidades, por lo que la descarga puede tomar un periodo relativamente prolongado, y generar complicaciones en el procesamiento de las entidades por los ya mencionados clientes Open Source. Es por esto que es recomendable descargar la respuesta del servicio a un archivo y continuar trabajando con el mismo, teniendo en cuenta que se debe actualizar el contenido cada vez que se modifique una entidad de datos en 365.
El contenido devuelto por el servicio de metadata es un extenso XML con todas las entidades de datos, lo principal es validar que la entidad publicada se encuentre ahí y que su definición corresponda con lo que se hizo en Visual Studio:
Al buscar la entidad en el archivo se observa que la entidad si está y que su definición es correcta, por lo cual se puede avanzar al siguiente paso que es realizar una consulta de datos. Obviamente es necesario que la tabla origen de la entidad contenga datos para que la consulta por OData devuelva información, por lo cual se crean un par de registros simples usando el explorador de tablas de Visual Studio.
Nótese la operación del método insert sobre el campo IdPlusName, donde independientemente del valor que inicialmente fue colocado en este campo finalmente se cambia por el definido en el método. Servirá para comparar el comportamiento al crear datos desde 365 vs. la entidad de datos.
Para realizar la consulta desde el explorador es necesario abrir previamente una sesión en el entorno de Dynamics 365, luego se debe abrir otra pestaña y acceder a la URL del servicio usando la notación de OData, la cual es de esta forma: https://<nombre_de_máquina_entorno>/data/. Usando como ejemplo la ruta de las máquinas de desarrollo y nuestra entidad, la URL sería: https://usnconeboxax1aos.cloud.onebox.dynamics.com/data/OdataTests. Se debe tener cuidado en la URL puesto que como nombre de entidad se debe colocar el valor exacto de Public Collection Name de la entidad, esto puesto que el valor es sensible a mayúsculas y minúsculas.
Si la URL se digita correctamente, el servicio devolverá como respuesta una cadena en notación json con los resultados de la siguiente forma
Se puede visualizar que son los mismos registros de prueba creados sobre la tabla de pruebas. Por tanto, la publicación de la entidad fue correcta y al menos la operación de consulta se encuentra operativa y disponible para realizar integraciones.
En el siguiente capítulo de este blog se completará el ciclo de integración al hacer una aplicación de prueba que ejecute operaciones de consulta y modificación de datos, donde se pueda ver varios conceptos útiles de OData para la creación de integraciones.
Christian Ruiz
Country IT Manager.
Attomo Essential Group S.A