Obtener el OrganizationService heredado del USD

Cuando queremos meter algún tipo de funcionalidad específica en nuestro USD lo realizamos mediante un Custom Hosted Control. Este control se realizaría desde Visual Studio extendiendo la clase DynamicsBaseHostedControl del compilado Microsoft.Crm.UnifiedServiceDesk. Esta clase a su vez implementa varias interfaces como son IDesktopUserActionsConsumer, IUsdControl y ISessionInfoConsumer. Estas interfaces incluyen funciones  como el DoAction –que se utiliza para recibir ActionsCalls del USD en nuestra clase- , el DesktopReady –que se ejecuta cuando el USD ha cargado-  o el NotifyContextChange –evento de cambio en alguna variable del contexto- entre otras. Dentro de todas estas funciones es muy probable que necesitemos interactuar con nuestro CRM. Como siempre, la API de CRM nos permitirá hacerlo utilizando el objeto OrganizationService. Como ya sabréis este objeto se puede instanciar utilizando una cadena de conexión con la IP de nuestro CRM y el usuario y contraseña de un usuario del CRM.

Pero puesto que en USD ya nos hemos tenido que identificar para poder acceder al mismo introduciendo unos credenciales al inicio –o en su defecto utilizando los credenciales del Active Directory- no sería práctico volver a instanciar el objecto OrganizationService puesto que deberíamos volver a preguntar al usuario sus credenciales.

El USD por dentro utiliza un objecto OrganizationService de igual modo que cuando realizamos un programa nosotros. Este objeto OrganizationService se instancia de los credenciales iniciales que se introducen en la pantalla de inicio del USD –la clásica pantalla azul de USD- y se utiliza internamente para descargar toda la configuración del agente al PC desde donde se está ejecutando el USD.

Probablemente existan varios métodos para obtener este objeto instanciado en nuestro código. Yo únicamente conozco dos.

El primero es heredar en nuestra clase la clase AifServiceBase. Esta clase que está en la librería Microsoft.Uii.AifServices, en el contexto de USD hereda el objeto OrganizationService para poder utilizarlo. El esquema que yo utilizaría sería, por un lado, la clase principal de la dll -la que incluiremos como Hosted Control en nuestra configuración- que hereda del  DynamicsBaseHostedControl  y por otro lado una clase que actúe de interface entre USD y CRM que herede del AifServiceBase. Dentro de la primera clase instanciaremos la segunda una sola vez pudiendo acceder al objeto a partir de ese momento.

Ejemplo estructura clases Custom Hosted Control con AifService

Ejemplo estructura clases Custom Hosted Control con AifService



Como lado negativo de este método comentar que a mi únicamente me ha funcionado con la versión 1.2 de USD y sospecho que es debido a que el AifService requiere la dll Microsoft.Crm.Sdk.Proxy que únicamente está incluida en la SDK de 2015 y por algún motivo no funciona en versiones de compilados superiores.

El segundo método y el más sencillo es obtener el IOrganizationService directamente del objeto Global Manager.

El USD siempre requiere de tres objetos principales y que son, podríamos decir, obligatorios: El Global Manager, el  Connection Manager y el Panel Layout. La idea es obtener en nuestra clase el Global Manager del USD y extraer el OrganizationService de dentro del objeto.

Para ello únicamente necesitamos conocer el nombre del Hosted Control de tipo Global Manager. El nombre lo obtenemos de la configuración del Unified Service Desk de nuestro CRM. Si durante la instalación del USD seleccionamos la opción de incluir datos de ejemplo, este Hosted Control ya estaría creado en nuestro primer USD. Si por el contrario hicimos una instalación limpia, tuvimos que crearlo nosotros mismos en algún momento. Lo que necesitamos es el nombre del Hosted Control, esto es, el string que se ve en la configuración.

Nombre del Hosted Control Global Manager

Nombre del Hosted Control Global Manager

En nuestro caso el Hosted Control se llama “Global Manager” por lo que para obtener el OrganizationService simplemente deberíamos de ejecutar la siguiente línea:

 

 

Instalación Unified Service Desk en entorno CRM y PC

El Unified Service Desk es una herramienta que nos ofrece Microsoft para todos los usuarios de CRM que nos brinda la oportunidad de integrarnos con nuestro entorno desde una aplicación de escritorio, que además es 100% administrable desde nuestra configuración en CRM. En este post veremos como realizar la instalación en nuestro CRM.

La filosofía de USD es la siguiente: En tu PC tendrás instalada una DLL que incluya el código fuente de un Botón (por ejemplo), con su interfaz gráfica, su propiedades, métodos y eventos. Ahora bien, si quieres que en tu USD aparezca un botón tendrás que ir a CRM e indicarlo en la configuración definida para ti.
Cuando inicia el USD, siempre lo hará con las credenciales de un usuario (o agente) de CRM. Este agente, por lo general tendrá definido en su ficha de agente de CRM una configuración, y dentro de esa configuración en CRM estará definido un botón. Así pues, cuando abras el USD toda esta información relativa a tu configuración se descargará y se guardará en caché. Si en esa configuración (definida en CRM) se indica que tu USD tiene un botón, entonces USD te pintará un botón. Además ese botón tendrá todas las características que le hayas indicado en la propia configuración del botón en CRM como pueden ser su texto para mostrar, acciones asociadas, eventos, etc.

El ejemplo indicado trata de un botón pero existen muchos otros tipos de objetos que se definen desde CRM y que cambian el comportamiento del USD como pueden ser navegadores, paneles, barras de botones, imágenes etc.

Sobre esto podemos hablar y extendernos mucho, no obstante para este post nos interesa sólo saber que existen dos mitades que necesitan la una de la otra y que completan el USD: DLLs en nuestro PC y configuración en nuestro CRM.

Partes fundamentales USD instalación

Partes fundamentales USD instalación

Vamos entonces a instalar las dos partes. Lo primero de todo que necesitamos es descargarnos los paquetes de la página. Los paquetes necesarios son el PackageDeployer y la versión de USD que queramos instalar en nuestro PC (32 o 64bits).

Descargamos los paquetes y los descomprimimos.

Primero vamos a instalar el PackageDeployer. Este paquete lo que hará será instalar en nuestro CRM todas las entidades que son necesarias para definir los elementos del USD, además de sus relaciones, reglas, imagenes etc. Además nos creará los formularios en CRM para interactuar con la configuración de nuestro USD y poder definir cada uno de sus elementos.

Abrimos el archivo CRM2016-USD-2.1.0-PackageDeployer.exe.

Instalacion Package Deployer Step 1

Instalacion Package Deployer Step 1

Click en aceptar y Continue

Instalacion Package Deployer Step 2

Instalacion Package Deployer Step 2

Tendremos que seleccionar una carpeta donde extraer los archivos de instalación. En esta carpeta no se instalará nada, solo es una carpeta de extracción para la instalación.

Instalacion Package Deployer Step 3

Instalacion Package Deployer Step 3

Una vez que se termine de extraer se nos abrirá el instalador

Instalacion Package Deployer Step 4

Instalacion Package Deployer Step 4

En la siguiente pantalla nos pedirá un login. El proceso es distinto si nuestra instancia es online u onpremise. Si es el caso de una instalación onpremise el login debería ser parecido al de la siguiente imagen:

Instalacion Package Deployer Step 5. Login on premise

Instalacion Package Deployer Step 5. Login on premise

Por el contrario, si nuestro CRM es online solo debemos indicar nuestro usuario y contraseña, el mismo con el que nos logueamos en el portal de Microsoft

Instalacion Package Deployer Step 5. Login online

Instalacion Package Deployer Step 5. Login online

Una vez iniciada sesión nos pedirá que seleccionemos un tipo de instalación. Esta instalación es una instalación nueva de cero. Eso significa que en el CRM que queremos instalar el Unified Service Desk no hay ninguna otra versión previa instalada. Si fuese así, deberíamos de actualizar y no instalar de cero.

Instalacion Package Deployer Step 6. Selección tipo instalación

Instalacion Package Deployer Step 6. Selección tipo instalación

Aceptamos los términos de la licencia

Instalacion Package Deployer Step 7

Instalacion Package Deployer Step 7

Aceptamos en la siguiente ventana y comenzará la instalación

Instalacion Package Deployer Step 8

Instalacion Package Deployer Step 8

La primera parte de la instalación es recapitular toda la información que hemos introducido

Instalacion Package Deployer Step 9

Instalacion Package Deployer Step 9

La segunda parte, y la más larga, es la carga en el CRM de las soluciones con sus entidades, formularios y relaciones.

Instalacion Package Deployer Step 10. Instalando

Instalacion Package Deployer Step 10. Instalando

Este proceso puede durar varios minutos en función de tu conexión. Al final deberíamos tener algo como lo siguiente:

Instalacion Package Deployer Step 10. Instalación completada

Instalacion Package Deployer Step 10. Instalación completada

Una vez terminado esto, finalizamos la instalación

Instalacion Package Deployer Step 11

Instalacion Package Deployer Step 11

Una vez terminada la instalación podemos comprobar que se nos ha habilitado un menú en la barra superior de CRM, en el menú de configuración, donde podremos acceder a la configuración de USD.

Acceder al menú de configuración de Unified Service Desk desde CRM

Acceder al menú de configuración de Unified Service Desk desde CRM

Nota: Si no ha aparecido el botón es probable que sea porque tenías el CRM abierto durante la instalación. La barra superior de menús no se recarga al navegar entre formularios por lo que para que aparezca prueba a recargar la página entera mediante Control + F5.

Nota:  una vez terminada esta instalación podemos eliminar la carpeta de extracción que creamos en el segundo paso.

Ya tenemos la primera mitad del USD instalada. Ahora necesitamos que esta configuración de CRM sea efectiva en nuestra aplicación de escritorio.

Procedemos a instalar la segunda parte. Esta instalación deberá realizarse en todos y cada uno de los ordenadores en los que un usuario quiera acceder al CRM mediante el Unified Service Desk. También puede instalarse en un escritorio virtual VDI al que accederán distintos usuarios.

Abrimos el archivo CRM2016-USD-2.1.1-amd64.exe

Instalación Unified Service Desk. Step 1

Instalación Unified Service Desk. Step 1

Dejamos el directorio por defecto para la instalación

Instalación Unified Service Desk. Step 2

Instalación Unified Service Desk. Step 2

Para que Unified Service  Desk funcione correctamente es necesario tener también instalados el .NET Framework 4.5.2 y el Windows Identify Foundation. Ambos están incluidos en el instalador y si los seleccionamos nos los instalará antes del USD.

Instalación Unified Service Desk. Step 3

Instalación Unified Service Desk. Step 3

Comenzamos la instalación

Instalación Unified Service Desk. Step 4

Instalación Unified Service Desk. Step 4

Cuando termine esta instalación, de modo automático nos abrirá el Unified Service Desk. La imagen que se ve a continuación es la pantalla inicia del USD donde, pulsando sobre Cambiar credenciales nos permitirá configurar a qué CRM queremos que nuestro USD se conecte.

Ventana de inicio Unified Service Desk

Ventana de inicio Unified Service Desk

Las opciones de login son las mismas que en el Package deployer. Podemos conectarnos al CRM online u onpremise.

Ventana de login Unified Service Desk. On premise

Ventana de login Unified Service Desk. On premise

Ventana de login Unified Service Desk. Online

Ventana de login Unified Service Desk. Online

Una vez que introducimos los credenciales e iniciamos sesión el USD se quedará cargando y finalmente nos mostrará la ventana principal. Es en este periodo de carga después de iniciar sesión cuando se produce en background la operación de descarga de información del CRM donde hemos indicado, y descarga de configuración de nuestro agente para pintarnos la interfaz gráfica del modo indicado en el CRM.

Ventana principal Unified Service Desk

Ventana principal Unified Service Desk

Con esto ya tenemos nuestro USD operativo tanto en nuestro PC como en nuestro CRM.

Paneles de USD: dónde se encuentran y cómo saber los que hay

Cuando añadimos un hosted control a nuestro USD, uno de los campos que tenemos que rellenar es el Display Group. En este campo hay que indicar dónde va a ir nuestro hosted control dentro del esquema general del USD, o lo que es lo mismo, en cual de los paneles se mostrará cuando abramos nuestra aplicación.

El USD al final es una aplicación como cualquier otra, diseñada con un esquema XAML predeterminado que han organizado los desarrolladores de Microsoft y que nos dibuja sobre la aplicación lo que ya todos conocemos: los paneles laterales que se contraen y expanden, la barra superior con el logo de Unified service desk etc.

Cada uno de estos paneles recibe un nombre definido en el esquema XAML y este es el nombre que se tendrá que poner en el campo Display Group para que una aplicación se cargue exactamente en ese panel. El esquema por defecto que trae el USD contiene varios paneles donde situar nuestros hosted controls.

En la siguiente figura pongo todos los paneles que podremos usar normalmente:

Posición de paneles dentro de USD

Posición de paneles dentro de USD

A estos esquemas habría que añadir el HiddenPanel que nos servirá para incluir hosted control que queremos que trabajen en tiempo de ejecución pero que no se muestren al usuario.

Como vemos la organización es bastante intuitiva. Normalmente nosotros utilizaremos unos pocos de todos estos paneles. El MainPanel es obligado puesto que será donde normalmente veamos el contenido de las páginas CRM que visitemos. Además si queremos integración telefónica, el CtiPanel es ideal para colocar nuestra botonera con los botones de colgar, llamar, transferir etc. Otra cosa importante es que los paneles de la izquierda, uno sobre el otro, tienen definido un Height auto, de modo que podremos usar cualquiera normalmente y aparecerá arriba del todo, si no se ha utilizado ninguno superior. Finalmente añadir que el RightPopupPanel se trata de un panel PopUp que está pensado para ver “Article Preview”. Yo personalmente no lo he dado uso nunca.

 

Cómo saber a que DLL corresponde un Hosted Control

Existe un método muy sencillo y que no requiere de ninguna instalación especial para conocer el namespace y el tipo de cada uno de los hosted controls que hay definidos en la configuración de USD en CRM.

Muchas veces necesitaremos en nuestro código hacer referencia a uno de estos objetos especiales para modificar algún atributo o para captar un evento. Estos ojbetos especiales son los que aparecen listados en la configuración de USD cuando creamos un nuevo hosted control, en el campo USD Component Type.

Tipos de hosted controls predefinidos

Tipos de hosted controls predefinidos

Como ya hemos visto en otras entradas a veces necesitamos hacer referencia a alguno de estos objetos (en esta entrada al Debugger por ejemplo). Para capturar la instancia del objeto necesitamos dos cosas: el nombre del hosted control y el tipo. El nombre es el que elijamos en la configuración del USD en CRM. El tipo es en principio desconocido.

Bien pues vamos a ver cómo consultar el tipo de la manera más sencilla. Lo primero de todo es irnos a la configuración del USD en CRM y crear un nuevo hosted control (como en la imagen de arriba).

Luego en el desplegable de USD Component Type seleccionamos el objeto que queremos averiguar. En nuestro caso queremos averiguar por ejemplo la DLL y el tipo del objeto Debugger:

Selección de Hosted Control Debugger

Selección de Hosted Control Debugger

A continuación lo único que deberemos hacer es volver a pinchar sobre el campo USD Component Type y seleccionar la opción USD Hosted Control. Como veremos cuando hagamos esto, aparecerán debajo dos campos: Assembly URI y Assembly Type. Además aparecerán rellenos con el tipo del objeto que hayamos seleccionado en primer lugar (en nuestro caso el objeto Debugger).

Selección de USD Hosted Control

Selección de USD Hosted Control

Una vez que conocemos el tipo, en nuestro Custom Hosted Control podremos obtener la instancia del objeto del siguiente modo:

Con esto ya somos capaces de modificar cualquier atributo de la instancia cargada en nuestro USD de este objeto.

El motivo por el que ocurre esto es que al seleccionar cualquier tipo especial en el campo USD Component Type los campos Assembly URI y Assembly Type se auto rellenan y además se ocultan. El fallo está en que al cambiar el desplegable no se resetean estos valores.

Unified Service Desk (USD): Utilizar debugger para trazas

Todos los que hemos tenido que desarrollar un USD sabemos que es una tarea bastante engorrosa. Algunos motivos son que no somos dueños del proyecto y por lo tanto no podemos añadir trazas donde queramos. Otro motivo es que el USD tiene unos tiempos de inicialización bastante grandes y todo lo que sea evitar cerrar la aplicación es bienvenido.

Para facilitarnos un poco la vida, en Microsoft desarrollaron un objeto llamado Debugger. Este objeto se añade por configuración a nuestro USD mediante un Hosted Control de tipo Debugger. Lo ideal sería ponerlo en el MainPanel como se muestra en la imagen:

Declaración de Debugger en configuración del USD en CRM

Declaración de Debugger en configuración del USD en CRM

Ya hemos hablado sobre las bondades del Debugger y cómo configurarlo en nuestra aplicación para poder acceder a él en esta otra entrada. En este caso nos centraremos en una de las pestañas, la de Resultados de Depuración:

Pestaña de Resultados de Depuración del Debugger

Pestaña de Resultados de Depuración del Debugger

Dentro de esta pestaña tenemos dos objetos: un Textbox multiline y un Botón para borrar el contenido. En general en este campo de texto se añadirán algunos resultados de depuración así como errores referentes a hosted controls. Este Textbox es el que voy a utilizar para monitorizar nuestras variables.

Para acceder a este Textbox vamos a utilizar la librería Reflection (System.Reflection).  Con esta librería seremos capaces de acceder a atributos privados de objetos para instancias previamente creadas. Básicamente nos permite saltarnos la decisión de un programador de declarar un objeto private o public. Es importante entender que si un programador decidió poner un objeto como private existiría un buen motivo por lo que este procedimiento es totalmente desaconsejable para entornos de producción.

No obstante antes de llegar al entorno de producción pasaremos por muchas etapas en nuestro USD en entornos de laboratorio, de desarrollo o incluso de pre producción. Con esta idea seremos capaces de obtener muestreo de datos en ejecución de un modo sencillo y que pueda ser invocado desde cualquier elemento del USD.

Dicho esto, vamos a pasar a ver el código.

La idea es introducir unas lineas de código en cualquiera de nuestros Custom Hosted Control (o hosted control creados por código). A mi personalmente me gusta tener siempre un hosted control global, situado en el HiddenPanel que sirva de controlador central de funciones, FireActions y en general de gestionar la interacción con el usuario. En el ejemplo llamaré a este hosted control como Controlador Central.  No obstante podemos declarar la función en cualquier otro hosted control que hayamos programado.

En este hosted control vamos a añadir unas lineas al DesktopReady y una UIAction en la función DoAction.

Recordar que para que funcione esta UIAction es necesario declararla en la configuración del USD en CRM para el hosted control Controlador Central.

Para probar que funciona correctamente podremos hacerlo de dos modos: mediante una ActionCall declarada en la configuración del USD en CRM que apunte al hosted control “Controlador Central”, la UIAction “addTraza” y como datos “Prueba traza”; o ejecutando en nuestro código un FireRequestAction como el siguiente:

El resultado será el siguiente:

Resultado al ejecutar el FireRequestAction

Resultado al ejecutar el FireRequestAction

Como vemos ya tenemos acceso libre a este TextBox para introducir lo que deseemos (variables, respuestas de servicios, estado de conexion etc) y poder consultar en cualquier momento de la ejecución del USD.