String connection CRM

 

String connection

Las string connections son variables de tipo string que contienen los datos necesarios para realizar una conexión a un entorno. Se utilizan mucho para, por ejemplo, conectarse a una base de datos. Estas cadenas de texto contienen todos los datos necesarios para que el cliente que realiza la petición sepa a qué base de datos debe conectarse y bajo qué usuario y password debe realizarlo. Son muy útiles porque nos permiten definir todos los datos necesarios para conectarse en una única variable, lo que simplifica el mantenimiento de la aplicación.

CRM Dynamics no es distinto y nos ofrece la posibilidad de conectarnos a una instancia de CRM únicamente indicando la string connection de esa instancia. El procedimiento ha cambiando un poco desde la versiones antiguas de CRM y la nueva versión 365 pero en esencia es igual. Vamos a ver cómo utilizar una string connection desde una aplicación hecha en C#:

SDK CRM 2011, 2013, 2015 y 2016

 

SDK CRM 365

 

Las diferencias entre las versiones son simplemente en el objeto que se instancia y de qué clase proviene. En las versiones antiguas se generaba la interface IOrganizationService desde el objeto OrganizationService mientras que en la nueva versión 365 el IOrganizationService se instancia desde el objeto CrmServiceClient del namespace Microsoft.Xrm.Tooling.Connector. También observar que la string connection para 365 tiene el parámetro extra de Authtype.

Cómo construir nuestra propia String Connection

Las String Connection por desgracia no son siempre iguales. En función del tipo de instancia que tengamos, o del tipo de autentificación se construirán de un tipo u otro. Vamos a ver qué parámetros se pueden incluir y algunos ejemplos:

 

Nombre de parámetro Parámetro Descripción
Server, Url, or Service Uri Url, Server, ServiceUri  La URL de nuestro CRM.

  • Si es una instancia on premise, la URL debería incluir la organización. Por ejemplo http://servidorcrm:puerto/nombre-organizacion.
  • Si es una instancia online, la URL será la que utilizamos para acceder. Por ejemplo: http://nuestra-organizacion.crm4.dynamics.com/

Para la string connection, funcionará igual si utilizamos la palabra Url, Server o ServiceUri

Domain Domain  El dominio de nuestra organización. Estaría relacionado con el Active Directory si estamos hablando de una instancia on premise. Para los online no es necesario incluir este parámetro.
Username or User ID Username Nuestro nombre de usuario.
Password Password Nuestro password. Podemos incluir dobles comillas al inicio y al final si nuetro password incluye espacios u otros caracteres especiales.
Timeout Timeout Por defecto el timeout de las conexiones a CRM son 2 minutos, pero si lo deseamos podemos aumentar o reducir esta cantidad. El formato sería timespan del tipo “hh:mm:ss”.
 Authtype Authtype  Necesario solo para instancias CRM 365. Si tenemos un CRM Dynamics 365 la string connection deberá incluir este parámetro. Los valores que puede tomar son:

  • Authtype=”Office365″ si nuestro CRM 365 es Online
  • Authtype=”AD” si nuestro CRM es on premise y validamos los credenciales contra el Active Directory
  • Authtype=”IFD” si nuestro CRM es on premise y validamos los credenciales mediante IFD

Los parámetros deberán incluirse uno detrás de otro separados por punto y coma en formato texto dentro de nuestra String. No son necesarias las comillas para indicar un parámetro a no ser que el valor de éste incluya carácteres especiales o espacios. Para las versiones on premise es posible también conectarse utilizando seguridad integrada de Windows, no incluyendo los parámetros Username y Password en la string connection. Si hacemos esto, la ejecución de las peticiones se realizará con el usuario que esté ejecutando la sesión de windows.

Algunos ejemplos:

CRM 365 online

“ServiceUri=https://ourorganization.crm4.dynamics.com/; Username=name@ourorganization.onmicrosoft.com; Password=OurPassw0rd; Authtype=Office365;”

 

CRM 365 on premise

“ServiceUri=http://ipcrm:5555/OrganizationName; Domain=ourdomain; Username=username; Password=OurPassw0rd; Authtype=AD;”

 

CRM 2011/2013/2015/2016 online

“ServiceUri=https://ourorganization.crm4.dynamics.com/; Username=name@ourorganization.onmicrosoft.com; Password=OurPassw0rd;”

 

CRM 2011/2013/2015/2016 on premise

“ServiceUri=http://ipcrm:5555/OrganizationName; Domain=ourdomain; Username=username; Password=OurPassw0rd;”

 

CRM 365 on premise con seguridad integrada

“ServiceUri=http://ipcrm:5555/OrganizationName; Authtype=AD;”

 

CRM 2011/2013/2015/2016 on premise con seguridad integrada

“ServiceUri=http://ipcrm:5555/OrganizationName;”

 

Fuentes: Microsoft, Ax3Group

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: