Configurar controles personalizados en Dynamics
Esta guía explica la configuración de los servicios web de DQE One en un entorno de Microsoft Dynamics 365 o Power Apps. Cada servicio web requiere dos niveles de configuración: ajustes a nivel de aplicación (se realizan una sola vez) y ajustes a nivel de formulario (se realizan por entidad: Cuenta, Contacto, Lead/Prospecto).
Agregar un control PCF
Todos los servicios web de DQE se configuran colocando un control PCF en el campo de destino dentro del editor de formularios. El proceso es el mismo para cada tipo de control, en cualquier entidad, ya sea estándar (Cuenta, Contacto, Lead/Prospecto) o personalizada.
- Abra el formulario de la entidad de destino en el editor de formularios de Power Apps.
- Seleccione el campo a configurar (calle, ciudad, correo electrónico, teléfono, etc.).
- En el panel derecho, haga clic en + Components y, a continuación, seleccione el control DQE correspondiente.
- Asigne los parámetros necesarios. Los parámetros obligatorios deben estar vinculados a un campo existente; los parámetros opcionales pueden dejarse sin definir. Consulte la sección de cada servicio web para ver la referencia completa de parámetros.
- Guarde y publique el formulario. Repita el proceso para cada entidad y cada bloque de dirección en el que deba estar activo el servicio web.
Nota: cada control debe configurarse de forma independiente en cada formulario de entidad. Los ajustes a nivel de aplicación (DQE DataQ Settings) se aplican de forma global y solo es necesario configurarlos una vez.
Opciones de código de país
Varios controles aceptan parámetros de código de país para preseleccionar el país en las consultas a la API. Tres opciones mutuamente excluyentes:
- Deje sin definir tanto countrycode como countryiso3: no hay preselección de país, el usuario selecciona el país manualmente.
- Establezca countrycode en el campo de búsqueda DQE Country: el país se preselecciona dinámicamente a partir del registro.
- Establezca countrycode en una búsqueda de tabla de países personalizada y establezca countryfield en el nombre lógico del campo ISO3 de esa tabla.
- Establezca countryiso3 en un valor ISO3 fijo (p. ej.,
FRA): el país queda fijado para todos los registros de este formulario.
Atención: los PCF antiguos tienen el prefijo [Legacy], mientras que los PCF nuevos no llevan ningún prefijo [].
1. Direcciones
El servicio web de direcciones proporciona autocompletado y validación de direcciones en tiempo real. Puede activarse en las entidades Cuenta, Contacto y Lead/Prospecto.
1.1 Ajustes de la aplicación
En DQE DataQ Settings → General, configure los interruptores correspondientes en Yes:
- Enable Address Autocomplete: activa el menú desplegable de sugerencias de dirección en los campos de dirección.
- Enable Address Validation: activa el cuadro de diálogo de validación RNVP al guardar.
A continuación, vaya a la pestaña Address Setup:
- Autofill Address Complement: actívelo para rellenar el campo de complemento (nombre del edificio, piso…) a partir de la respuesta de la API.
- Address Default Country: preselecciona un país en el campo de búsqueda. No restringe la validación internacional.
- Contact / Account / Lead Address List: conjunto de opciones de selección múltiple por entidad. Seleccione en qué bloques de dirección (Address 1, Address 2…) debe estar activo el servicio web.
1.2 Validación de direcciones (RNVP)
La validación de direcciones se activa mediante el interruptor Enable Address Validation en los ajustes de la aplicación (§1.1). Cuando está activada, al guardar un registro cuyos campos de dirección se hayan editado manualmente (sin seleccionarlos del autocompletado), se abre un cuadro de diálogo RNVP en el que el usuario puede aceptar o rechazar cada corrección sugerida campo por campo.
Nota: RNVP y el autocompletado de direcciones se controlan mediante dos interruptores independientes y pueden activarse por separado.
1.2.1 AddressFieldControl — Campo de calle
AddressFieldControl · Custom API: DQE - Address - Search
| Parámetro | Tipo | Uso | Obligatorio | Descripción |
|---|---|---|---|---|
line |
SingleLine.Text |
bound | Obligatorio | Línea de dirección postal (el campo en el que se coloca el control). |
city |
SingleLine.Text |
bound | Obligatorio | Campo de ciudad: se actualiza al seleccionar una sugerencia. |
postalcode |
SingleLine.Text |
bound | Obligatorio | Campo de código postal: se actualiza al seleccionar una sugerencia. |
complement |
SingleLine.Text |
bound | Opcional | Campo de complemento de dirección (nombre del edificio, piso…). Requiere que Autofill address complement esté activado en Address Setup. |
saidplace |
SingleLine.Text |
bound | Opcional | Campo de lugar dicho / caserío (lieu-dit). Asígnelo a un campo personalizado para recibir el valor de localidad devuelto por la API. |
dqecodedetail |
SingleLine.Text |
bound | Opcional | Almacena el código de retorno RNVP tras la validación de la dirección. Puede utilizarse en flujos de Power Automate o reglas de negocio. |
countrycode |
Lookup.Simple |
bound | Opcional | Búsqueda en la tabla DQE Country (o en una tabla de países personalizada). Se utiliza para preseleccionar el país. |
countryfield |
SingleLine.Text |
input | Opcional | Si se utiliza una tabla de países personalizada, el nombre lógico del campo que contiene el código ISO3 en esa tabla. |
countryiso3 |
SingleLine.Text |
input | Opcional | Código de país ISO3 fijo (p. ej., FRA). Se utiliza en lugar de countrycode cuando el país es fijo. |
addressColumns |
Multiple |
input | Opcional | JSON que define columnas personalizadas en el menú desplegable de sugerencias de dirección. |
complementColumns |
Multiple |
input | Opcional | JSON que define columnas personalizadas en el menú desplegable de sugerencias de complemento. |
1.2.2 CityFieldControl — Campo de ciudad
CityFieldControl · Custom API: DQE - Address - Search
| Parámetro | Tipo | Uso | Obligatorio | Descripción |
|---|---|---|---|---|
city |
SingleLine.Text |
bound | Obligatorio | Campo de ciudad (el campo en el que se coloca el control). |
postalcode |
SingleLine.Text |
bound | Obligatorio | Campo de código postal: se actualiza al seleccionar una sugerencia. |
countrycode |
Lookup.Simple |
bound | Opcional | Búsqueda en la tabla DQE Country (o en una tabla de países personalizada). |
countryfield |
SingleLine.Text |
input | Opcional | Si se utiliza una tabla de países personalizada, el nombre lógico del campo ISO3 en esa tabla. |
countryiso3 |
SingleLine.Text |
input | Opcional | Código de país ISO3 fijo. |
customColumns |
Multiple |
input | Opcional | JSON que define columnas personalizadas en el menú desplegable de sugerencias de ciudad. |
1.2.3 PostalcodeFieldControl — Campo de código postal
PostalcodeFieldControl · Custom API: DQE - Address - Search
| Parámetro | Tipo | Uso | Obligatorio | Descripción |
|---|---|---|---|---|
postalcode |
SingleLine.Text |
bound | Obligatorio | Campo de código postal (el campo en el que se coloca el control). |
city |
SingleLine.Text |
bound | Obligatorio | Campo de ciudad: se actualiza al seleccionar una sugerencia. |
countrycode |
Lookup.Simple |
bound | Opcional | Búsqueda en la tabla DQE Country (o en una tabla de países personalizada). |
countryfield |
SingleLine.Text |
input | Opcional | Si se utiliza una tabla de países personalizada, el nombre lógico del campo ISO3 en esa tabla. |
countryiso3 |
SingleLine.Text |
input | Opcional | Código de país ISO3 fijo. |
customColumns |
Multiple |
input | Opcional | JSON que define columnas personalizadas en el menú desplegable de sugerencias de código postal. |
1.3 Resultados esperados
Cuando Enable Address Autocomplete está activo y los controles PCF están configurados:
- Al escribir una dirección: aparecen sugerencias mientras el usuario escribe en el campo de calle.
- Al escribir un código postal: las sugerencias se filtran según las ciudades y calles coincidentes.
- Al seleccionar una sugerencia se rellenan automáticamente los campos de ciudad, código postal y cualquier otro campo asignado.
2. Correos electrónicos
El servicio web de correo electrónico valida direcciones de correo electrónico en tiempo real y puede sugerir correcciones basadas en el nombre del contacto. Disponible en Cuenta, Contacto y Lead/Prospecto.
2.1 Ajustes de la aplicación
En DQE DataQ Settings → General, configure Enable Email Validation en Yes.
A continuación, vaya a la pestaña Email Setup:
- Contact / Account / Lead Email List: conjunto de opciones de selección múltiple por entidad. Seleccione en qué campos de correo electrónico debe estar activo el servicio web.
Nota: las sugerencias de correo electrónico basadas en el nombre se activan a nivel de PCF asignando los parámetros firstnamevalue y lastnamevalue en EmailFieldTextControl. El almacenamiento del código de retorno también se configura a nivel de PCF mediante el parámetro returncode.
2.2 Configuración del formulario
En el editor de formularios, seleccione el campo Email, haga clic en + Components, seleccione EmailFieldTextControl, asigne los parámetros y, a continuación, guarde y publique.
EmailFieldTextControl · Custom API: DQE - Email - Validation
| Parámetro | Tipo | Uso | Obligatorio | Descripción |
|---|---|---|---|---|
emailvalue |
Email |
bound | Obligatorio | Campo de correo electrónico (el campo en el que se coloca el control). |
firstnamevalue |
SingleLine.Text |
bound | Opcional | Campo de nombre. Se utiliza para las sugerencias de correo electrónico basadas en el nombre. Para las entidades de Cuenta, asígnelo al campo del nombre de la empresa. |
lastnamevalue |
SingleLine.Text |
bound | Opcional | Campo de apellido. Se utiliza para las sugerencias de correo electrónico basadas en el nombre. |
returncode |
SingleLine.Text |
bound | Opcional | Campo de salida que almacena el código de retorno de la API de DQE tras la validación. Puede utilizarse en flujos de Power Automate o reglas de negocio. |
countrycode |
Lookup.Simple |
bound | Opcional | Búsqueda en la tabla DQE Country (o en una tabla de países personalizada). |
countryfield |
SingleLine.Text |
input | Opcional | Si se utiliza una tabla de países personalizada, el nombre lógico del campo ISO3 en esa tabla. |
countryiso3 |
SingleLine.Text |
input | Opcional | Código de país ISO3 fijo. |
2.3 Resultados esperados
- Tras introducir un correo electrónico, aparece un indicador de validación junto al campo.
- Si los campos de nombre y apellido están asignados, el servicio web sugiere posibles direcciones de correo electrónico y nombres de dominio.
- Si returncode está asignado, se actualiza tras cada validación y puede activar lógica posterior en Power Automate.
3. Teléfonos
El servicio web de teléfono valida números de teléfono en tiempo real y los formatea según el país. Disponible en Cuenta, Contacto y Lead/Prospecto.
3.1 Ajustes de la aplicación
En DQE DataQ Settings → General, configure Enable Phone Validation en Yes.
A continuación, vaya a la pestaña Phone Setup:
- Address Default Country: preselecciona un prefijo telefónico de país. No restringe la validación internacional.
- Contact / Account / Lead Phone List: conjunto de opciones de selección múltiple por entidad. Seleccione en qué campos de teléfono debe estar activo el servicio web.
Nota: el almacenamiento del código de retorno se configura a nivel de PCF mediante el parámetro returncode en PhonefieldControl.
3.2 Configuración del formulario
En el editor de formularios, seleccione el campo Main Phone, haga clic en + Components, seleccione PhonefieldControl, asigne los parámetros y, a continuación, guarde y publique.
PhonefieldControl · Custom API: DQE - Phone - Validation
| Parámetro | Tipo | Uso | Obligatorio | Descripción |
|---|---|---|---|---|
name |
Phone |
bound | Obligatorio | Campo de teléfono (el campo en el que se coloca el control). |
returncode |
SingleLine.Text |
bound | Opcional | Campo de salida que almacena el código de retorno de la API de DQE tras la validación. Puede utilizarse en flujos de Power Automate o reglas de negocio. |
countrycode |
Lookup.Simple |
bound | Opcional | Búsqueda en la tabla DQE Country (o en una tabla de países personalizada). Determina el prefijo telefónico utilizado para la validación. |
countryfield |
SingleLine.Text |
input | Opcional | Si se utiliza una tabla de países personalizada, el nombre lógico del campo ISO3 en esa tabla. |
countryiso3 |
SingleLine.Text |
input | Opcional | Código de país ISO3 fijo. |
3.3 Resultados esperados
- Tras introducir un número de teléfono, aparece un indicador de validación y el número se reformatea según el estándar del país.
- Si returncode está asignado, se actualiza tras cada validación y puede activar lógica posterior en Power Automate.
4. Nombre
El servicio web de nombre sugiere tratamientos (Sr./Sra./…) según el nombre de pila y puede validar la coherencia entre nombre y género. Disponible en cualquier entidad que tenga un campo de nombre (normalmente Contacto, Lead/Prospecto).
4.1 Ajustes de la aplicación
En DQE DataQ Settings → General, configure Enable Firstname Validation en Yes.
A continuación, vaya a la pestaña Firstname Setup:
- Address Default Country: preselecciona un país predeterminado para el servicio web.
- Firstname Configuration: abre el WebResource de asignación de nombres (véase §4.2).
4.2 Asignación de nombres
Haga clic en el botón Firstname Configuration de la pestaña Firstname Setup para abrir el WebResource FieldMapping. Aquí es donde se asignan los códigos de género de DQE a los valores de opción de su conjunto de opciones de Dynamics.
- DQE devuelve tres valores de género:
H(hombre),F(mujer),I(desconocido/indeterminado). - Para cada valor, establezca el valor de opción entero correspondiente de su campo de conjunto de opciones de Dynamics.
- Las asignaciones se almacenan en la tabla
dqe_field_mappingde Dataverse.
Obligatorio si se utiliza genderchoice: si el parámetro genderchoice está asignado en FirstNameFieldControl pero no se ha configurado ninguna asignación aquí, el campo de género no se actualizará tras la selección del nombre.
4.3 Configuración del formulario
En el editor de formularios, seleccione el campo First Name, haga clic en + Components, seleccione FirstNameFieldControl, asigne los parámetros y, a continuación, guarde y publique. Configure primero la asignación de género en el §4.2 si utiliza el parámetro genderchoice.
FirstNameFieldControl · Custom API: DQE - Name - Search by firstName
| Parámetro | Tipo | Uso | Obligatorio | Descripción |
|---|---|---|---|---|
firstnamevalue |
SingleLine.Text |
bound | Obligatorio | Campo de nombre (el campo en el que se coloca el control). |
gendervalue |
SingleLine.Text |
bound | Opcional | Cadena de género fija: H (hombre), F (mujer) o I (desconocido). Mutuamente excluyente con genderchoice. |
genderchoice |
OptionSet |
bound | Opcional | Campo de conjunto de opciones que contiene el valor de género/tratamiento. La asignación de los valores de DQE (H/F/I) a los valores de opción de CRM debe configurarse en el WebResource FieldMapping. Mutuamente excluyente con gendervalue. |
countrycode |
Lookup.Simple |
bound | Opcional | Búsqueda en la tabla DQE Country (o en una tabla de países personalizada). |
countryfield |
SingleLine.Text |
input | Opcional | Si se utiliza una tabla de países personalizada, el nombre lógico del campo ISO3 en esa tabla. |
countryiso3 |
SingleLine.Text |
input | Opcional | Código de país ISO3 fijo. |
Configuración del género: elija una de estas tres opciones: (1) deje sin definir tanto gendervalue como genderchoice, (2) establezca gendervalue en una cadena fija, o (3) establezca genderchoice en un campo de conjunto de opciones y configure la asignación de valores en el WebResource FieldMapping.
5. B2B
El servicio web B2B proporciona autocompletado de empresas a partir de la base de datos francesa SIRENE (INSEE). Disponible únicamente en la entidad Cuenta.
5.1 Ajustes de la aplicación
En DQE DataQ Settings → General, configure Enable Company Verification en Yes.
A continuación, vaya a la pestaña Company Setup:
- Company Mapping: abre el WebResource FieldMapping (véase §5.2).
5.2 Asignación de campos
Haga clic en el botón Company Mapping de la pestaña Company Setup para abrir el WebResource FieldMapping. Aquí se define qué campos de datos de SIRENE se asignan a qué campos de Dynamics en la entidad Cuenta.
- Las asignaciones se almacenan en la tabla
dqe_field_mappingde Dataverse. - Haga clic en Initialize Default Records para rellenar previamente una asignación estándar. Se puede ejecutar varias veces sin riesgo: solo crea los registros que faltan y no sobrescribe los existentes.
5.3 Configuración del formulario
Añada los dos controles B2B al formulario de Cuenta: CompanyField en el campo del nombre de la empresa y CompanyNumberField en el campo del número de empresa.
CompanyField — Campo de nombre de empresa
CompanyField · Custom API: DQE - Company - Search
| Parámetro | Tipo | Uso | Obligatorio | Descripción |
|---|---|---|---|---|
name |
SingleLine.Text |
bound | Obligatorio | Campo de nombre de empresa (el campo en el que se coloca el control). |
countrycode |
Lookup.Simple |
bound | Obligatorio | Búsqueda en la tabla DQE Country. Determina en qué base de datos SIRENE del país se realiza la consulta. |
filter |
SingleLine.Text |
input | Opcional | Cadena de filtro que se pasa a la API RECSIRET (p. ej., solo empresas activas, difusibles, asociaciones). Consulte a su gestor de proyecto DQE los valores disponibles. |
columns |
Multiple |
input | Opcional | JSON que define columnas personalizadas en el menú desplegable de sugerencias de empresa (véase la sección 5.4). |
outputtrigger |
SingleLine.Text |
output | Opcional | Se establece en "autocomplete" cuando la salida se activa mediante una selección del usuario (no un cambio manual). Se utiliza en el Integrator Method para detectar eventos de autocompletado. |
outputdata |
Object |
output | Opcional | Objeto completo de datos de la empresa devuelto por el servicio web. Se utiliza en el Integrator Method para leer y aplicar valores de campo de forma programática. |
CompanyNumberField — Campo de número de empresa
CompanyNumberField · Custom API: DQE - CompanyNumber - Search
| Parámetro | Tipo | Uso | Obligatorio | Descripción |
|---|---|---|---|---|
accountnumber |
SingleLine.Text |
bound | Obligatorio | Campo de número de empresa / SIRET (el campo en el que se coloca el control). |
accountid |
SingleLine.Text |
bound | Obligatorio | ID de registro de la Cuenta actual. Se utiliza para evitar la detección de auto-duplicados. |
filter |
SingleLine.Text |
input | Opcional | Cadena de filtro que se pasa a la API RECSIRET (p. ej., solo empresas activas, difusibles, asociaciones). |
outputtrigger |
SingleLine.Text |
output | Opcional | Se establece en "autocomplete" cuando la salida se activa mediante una selección del usuario. |
outputdata |
Object |
output | Opcional | Objeto completo de datos de la empresa devuelto por el servicio web. |
5.4 Columnas del menú desplegable
Puede sobrescribir las columnas predeterminadas del menú desplegable de CompanyField estableciendo el parámetro columns como JSON en el XML del formulario.
[
{"label": "Company", "propertyName": "CompanyName", "minWidth": 150, "maxWidth": 250},
{"label": "Zip Code", "propertyName": "ZIP_Code", "minWidth": 150, "maxWidth": 250},
{"label": "SIRET", "propertyName": "CompanyNumber", "minWidth": 150, "maxWidth": 250},
{"label": "Ref", "propertyName": "Ref", "minWidth": 150, "maxWidth": 250}
]
Nombres de propiedad disponibles:
CompanyName CompanyNumber ZIP_Code CompanyAddress1 CompanyAddress2 CompanyAddress3 Locality Phone Email Activity1 Activity2 StaffCount TurnOver LegalStructureCode LegalStructureLabel IncorporationDate DissolutionDate Country CompanyStatus MainCompanyFlag Ref
Consejo: un plugin editor de XML de formularios de XrmToolBox puede facilitar la exportación y edición del XML del formulario.
5.5 Parámetro de filtro
Tanto CompanyField como CompanyNumberField aceptan un parámetro opcional filter que se pasa directamente a la API RECSIRET. Puede establecerse de forma estática en Component Properties o de forma dinámica a partir del valor de un campo. Consulte a su gestor de proyecto DQE las cadenas de filtro disponibles.
5.6 Resultados esperados
- El usuario abre un registro de Cuenta y empieza a escribir un nombre de empresa o un SIRET.
- Aparece un menú desplegable con las empresas coincidentes de la base de datos SIRENE.
- El usuario selecciona una empresa: los campos asignados (dirección, SIRET, forma jurídica…) se rellenan automáticamente.
- Al guardar, si Dynamics detecta un duplicado, aparece la ventana emergente nativa de detección de duplicados.
Importante: es obligatorio seleccionar un país antes de realizar la búsqueda.
Relacionada con