Integración Continua en Salesforce (2): descripción de la Metadata

Esta entrada pertenece a una serie:

1. Introducción
2. Descripción de la metadata (esta entrada)
3. Proceso y uso de la herramienta de despliegue
4. Orquestación y visión completa
5. Conclusiones Finales y recomendaciones

En esta segunda entrada, conoceremos las nociones básicas de la Metadata API.

Nociones básicas sobre la Metadata API de Salesforce

Salesforce describe la mayoría de los objetos, lo que llamamos Metadata, mediante estructuras XML, definidas y documentadas en la Metadata API (documentación mantenida por Salesforce).

No todos los objetos tienen representación en la Metadata API, y están perfectamente listados en este enlace: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_unsupported_types.htm.

Es decir, aquellas configuraciones/programaciones que llevan a cabo los Admins/Developers, se representan en estructuras XML almacenadas en ficheros, bajo una especficación pública de Salesforce.

Por tanto, y dado que las herramientas de control de versiones trabajan en base a ficheros, vamos por el buen camino, esto rula.

Como define Salesforce la Metadata

Por tanto, parece claro que, debemos familiarizarnos con estos ficheros XML, y la estructura de directorios que se usa para ordenarlos.

Estructura de directorios

Empezemos pues viendo un ejemplo de la estructura:

Este árbol de directorios parece tener una relación entre objetos y carpetas, pero de una observación detalla se concluye que:

• No hay una convención de nombres (nombre compuestos, plurales, singulares, Camel-Case, etc.) establecida
• No todos los objetos tienen una carpeta

Tipo de Objeto	Carpeta contenedora
CustomApplication	applications
AppMenu	appMenus
ApprovalProcess	approvalProcesses
AssignmentRules	assignmentRules
AutoResponseRules	autoResponseRules
ApexClass	classes
Certificate	certs
CleanDataService	cleanDataServices
Community	communities
ApexComponent	components
ConnectedApp	connectedApps
CustomApplicationComponent	customApplicationComponents
CustomObjectTranslation	¿?*
CustomPageWebLink	¿?*
Dashboard	dashboards
Document	documents
DuplicateRule	duplicateRules
EmailTemplate	email
EscalationRules	escalationRules
FlexiPage	flexipages
FlowDefinition	flowDefinitions
Flow	flows
GlobalValueSet	globalValueSets
Group	groups
HomePageComponent	homePageComponents
HomePageLayout	homePageLayouts
InstalledPackage	installedPackages
CustomLabels	labels
Letterhead	letterhead
ManagedTopics	managedTopics
Layout	layouts
LeadConvertSettings	LeadConvertSettings
MatchingRules	matchingRules
NamedCredential	namedCredentials
Network	networks
CustomObject	objects
CustomObjectTranslation	objectTranslations
ApexPage	pages
PermissionSet	permissionsets
Profile	profiles
QuickAction	quickActions
RemoteSiteSetting	remoteSiteSettings
Report	reports
ReportType	reportTypes
Role	roles
SamlSsoConfig	samlssoconfigs
Settings	settings
SiteDotCom	siteDotComSites
CustomSite	sites
SharingRules	sharingRules
StaticResource	staticresources
CustomTab	tabs
Translations	translations
ApexTrigger	triggers
CustomPageWebLink	weblinks
Workflow	workflows

Por tanto estas carpetas y nomenclatura se han establecido según el criterio de los ingenieros de Salesforce, sin seguir una convención (si la encontraras por favor enviámela). Sin una convención, las adiciones o cambios que decidan los ingenieros de Salesforce pueden afectar a nuestro procedimiento automatizado de Integración Continua.

A partir de aquí denominaré Debilidad a este tipo de situaciones, donde se observe que, nuestro procedimiento de automatización puede verse afectado.

Debilidad: no existe una convención ni documentación oficial al respecto de la organización y nomenclatura de los directorios de los objetos.

Descripción de los objetos en sus estructuras XML

Analicemos ahora como Salesforce describe los objetos en las estructuras XML.

Del análisis, resulta que Salesforce, no utiliza un único mecanismo para describir los objetos, sino 3, veamos.

Tipo 1: Descripción en 1 único fichero

Es el modelo más simple y usado, consiste en utilizar 1 único fichero XML para describir un único objeto de forma completa. Muy sencillo.

Tipo 2: Descripción utilizando varios ficheros

Para los objetos, Dashboards, Documents, Email Templates y Reports, la descripción de su Metadata se realiza de la siguiente manera:

• Si el usuario creó carpetas adicionales para clasificar estos objetos, Salesforce crea un fichero XML descriptor de la carpeta cuyo nombre contiene el sufijo -meta.xml.
• Si en la carpeta creada, el usuario ubicó objetos (sería lo esperado aunque no deba ser siempre así – porque dejó la carpeta vacía), Salesforce crea otro directorio donde ubica los objetos. En esta carpeta se encuentran los ficheros XML que los objetos.
  • Adicionalmente si el objeto descrito, contiene un objeto binario, este fichero se describe con un fichero nombreObjeto-meta.xml (un ejemplo típico es el objeto Documents)
• Si en la carpeta creada, el usuario no ubicó objetos, existe el fichero –meta.xml descriptor de la carpeta, pero no un directorio, dado que no hay objetos que ubicar
• Si el usuario creó elementos y los ubicó en la raíz (es decir no los ubicó en carpetas), Salesforce proporciona una carpeta con nombre unfiled$public, de la que no existe un fichero descriptivo -meta.xml.

Por tanto:

• Todos los ficheros XML de los objetos están ubicados en algún directorio, fueren las creadas por el usuario o sea $unfiled$public
• Todas las carpetas creadas por el usuario tienen un fichero descriptivo –meta.xml
• Si el usuario creó una carpeta, pero no ubicó ficheros en su interior, existe un fichero –meta.xml descriptor pero no un directorio
• Si el objeto, contiene contenido binario, este contenido se describe en otro fichero -meta.xml

Tipo 3: Descripción de varios objetos relacionados en un único fichero XML

Corresponde al uso de 1 único fichero XML para describir varios objetos que tienen relación, cuyo ejemplo más claro quizá sean los Worfklows, que aglutina en un único fichero: Workflow Alerts, Workflow Field Updates, Workflow Rules y las Workflow Tasks.

El nombre del fichero proviene del nombre del objeto, es decir, el nombre que recibió el objeto principal, es el nombre del fichero. Así, por ejemplo, todos los Workflows (Alerts, Field Updates, etc.) definidos para Account, se encuentran en el fichero Account.workflow.

Debilidad: la descripción de los objetos no es única, y en ciertos casos compleja, y además dependiente de ciertas acciones que haya realizado el usuario.

Debilidad: para técnicos con background en integración de sistemas, es usual usar ficheros XSD que definan las estructuras a usar para sean instanciadas en XML. En este caso Salesforce no proporciona estos ficheros XSD (o al menos yo no los he encontrado).

Conclusiones

Parece ser que el camino al uso de un procedimiento de Integración Continua con la Metadata API, no es un camino directo, y se empiezan a deslumbrar ciertas dificultades, ya que:

• aún teniendo ficheros, estos se no se organizan/nombran en base a convenciones
• existen distintas estructuras XML usadas
• no existe una relación de qué objetos siguen qué estructuras
• no existen XSD de definición de las estructuras como documentación o para validación

Pero no nos desanimemos, veamos en la próxima entrada – Integración Continua Salesforce – Herramienta de despliegue  – si ya hemos pasado por lo peor del camino … o no.

Enlaces de interés

• Página principal de la documentación de Metadata API: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_intro.htm
• Tipos de metadatos soportados: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_types_list.htm
• (Añadido Agosto-2018): Se ha publicado una lista de todos los objetos soportados por Metadata mucho más comprensible: https://developer.salesforce.com/docs/metadata-coverage/44
• Consideraciones especiales: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_special_behavior.htm

Anuncio publicitario