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 (una sola vez) y ajustes a nivel de formulario (por entidad — Account, Contact, Lead).

Añadir un control PCF

Todos los servicios web de DQE se configuran colocando un control PCF en el campo de destino, en el editor de formularios. El proceso es el mismo para cada tipo de control, en cualquier entidad — estándar (Account, Contact, Lead) o personalizada.

1. Abra el formulario de la entidad de destino en el editor de formularios de Power Apps.
2. Seleccione el campo a configurar (calle, ciudad, email, teléfono, etc.).
3. En el panel derecho, haga clic en + Components y luego seleccione el control DQE correspondiente.
4. Asigne los parámetros requeridos. Los parámetros requeridos deben vincularse a un campo existente; los parámetros opcionales pueden dejarse sin definir. Consulte la sección de cada servicio web para la referencia completa de parámetros.
5. Guarde y publique el formulario. Repita para cada entidad y cada bloque de dirección donde el servicio web deba estar activo.

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 globalmente y solo deben establecerse 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:

1. Dejar sin definir tanto countrycode como countryiso3 — sin preselección de país, el usuario selecciona el país manualmente.
2. Establecer countrycode en el campo de búsqueda DQE Country — el país se preselecciona dinámicamente a partir del registro.
3. Establecer countrycode en una búsqueda a una tabla de países personalizada + establecer countryfield en el nombre lógico del campo ISO3 de esa tabla.
4. Establecer countryiso3 en un valor ISO3 fijo (por ej. FRA) — país fijo para todos los registros de este formulario.

Atención: los PCF antiguos llevan el prefijo [Legacy], mientras que los nuevos PCF 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 Account, Contact y Lead.

1.1 Ajustes de la aplicación

En DQE DataQ Settings → General, ponga en Yes los interruptores correspondientes:

• Enable Address Autocomplete — activa la lista 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.

Luego 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 — 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 dirección (RNVP)

La validación de dirección se activa con el interruptor Enable Address Validation en Ajustes de la aplicación (§1.1). Cuando está activado, guardar un registro cuyos campos de dirección se editaron manualmente (no seleccionados mediante autocompletado) activa un cuadro de diálogo RNVP — 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 Calle

AddressFieldControl · Custom API: DQE - Addresses - Search by address

1.2.2 CityFieldControl — Campo Ciudad

CityFieldControl · Custom API: DQE - Addresses - Search by address

1.2.3 PostalcodeFieldControl — Campo Código postal

PostalcodeFieldControl · Custom API: DQE - Addresses - Search by address

1.3 Resultado esperado

Cuando Enable Address Autocomplete está activo y los controles PCF están configurados:

• Al escribir una dirección: aparecen sugerencias a medida que el usuario escribe en el campo Calle.
• Al escribir un código postal: las sugerencias se filtran por ciudades y calles coincidentes.
• Al seleccionar una sugerencia se rellenan automáticamente Ciudad, Código postal y los demás campos asignados.

2. Emails

El servicio web de email valida las direcciones de correo en tiempo real y puede sugerir correcciones basadas en el nombre del contacto. Disponible en Account, Contact y Lead.

2.1 Ajustes de la aplicación

En DQE DataQ Settings → General, ponga Enable Email Validation en Yes.

Luego vaya a la pestaña Email Setup:

• Contact / Account / Lead Email List — selección múltiple por entidad. Seleccione en qué campos de email debe estar activo el servicio web.

Nota: las sugerencias de email 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 luego guarde y publique.

EmailFieldTextControl · Custom API: DQE - Email - Search by email

2.3 Resultado esperado

• Después de que el usuario introduzca un email, aparece un indicador de validación junto al campo.
• Si los campos de nombre/apellidos están asignados, el servicio web sugiere direcciones de email y dominios probables.
• Si returncode está asignado, se actualiza tras cada validación y puede desencadenar lógica de Power Automate posterior.

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 Account, Contact y Lead.

3.1 Ajustes de la aplicación

En DQE DataQ Settings → General, ponga Enable Phone Validation en Yes.

Luego vaya a la pestaña Phone Setup:

• Address Default Country — preselecciona un prefijo de país. No restringe la validación internacional.
• Contact / Account / Lead Phone List — 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 luego guarde y publique.

PhonefieldControl · Custom API: DQE - Phone - Search by phone number

3.3 Resultado esperado

• Después de que el usuario introduzca 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 desencadenar lógica de Power Automate posterior.

4. Nombre

El servicio web de nombre sugiere tratamientos (Sr./Sra./…) a partir del nombre y puede validar la coherencia entre nombre y género. Disponible en cualquier entidad con un campo de nombre (normalmente Contact, Lead).

4.1 Ajustes de la aplicación

En DQE DataQ Settings → General, ponga Enable Firstname Validation en Yes.

Luego vaya a la pestaña Firstname Setup:

• Address Default Country — preselecciona un país predeterminado para el servicio web.
• Firstname Configuration — abre el WebResource Name Mapping (ver §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 choice set de Dynamics.

• DQE devuelve tres valores de género: H (masculino), F (femenino), I (desconocido/indeterminado).
• Para cada valor, establezca el valor de opción entero correspondiente de su campo choice set de Dynamics.
• Las asignaciones se almacenan en la tabla dqe_field_mapping en Dataverse.

Requerido al usar genderchoice: si el parámetro genderchoice está asignado en FirstNameFieldControl pero no hay ninguna asignación configurada aquí, el campo de género no se actualizará tras seleccionar el 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 luego guarde y publique. Configure primero la asignación de género en el §4.2 si usa el parámetro genderchoice.

FirstNameFieldControl · Custom API: DQE - Name - Search by firstname

Configuración del género: elija una de tres opciones — (1) dejar sin definir tanto gendervalue como genderchoice, (2) establecer gendervalue en una cadena fija, o (3) establecer genderchoice en un campo choice set y configurar la asignación de valores en el WebResource FieldMapping.

4.4 Resultado esperado

• Al escribir un nombre: el servicio web busca el nombre y determina el género/tratamiento probable.
• Si genderchoice está asignado y la asignación de valores está configurada en el WebResource FieldMapping (§4.2), el campo choice set de género/tratamiento se actualiza automáticamente con la opción correspondiente.
• Si en su lugar está asignado gendervalue, se establece directamente con la cadena de género fija (H/F/I) devuelta por el servicio web, sin pasar por la asignación del choice set.
• Si genderchoice está asignado pero no hay ninguna asignación configurada en el §4.2, el campo de género no se actualiza tras seleccionar el nombre.

5. B2B

El servicio web B2B ofrece autocompletado de empresas a partir de la base de datos SIRENE francesa (INSEE). Disponible únicamente en la entidad Account.

5.1 Ajustes de la aplicación

En DQE DataQ Settings → General, ponga Enable Company Verification en Yes.

Luego vaya a la pestaña Company Setup:

• Botón Configure company mapping (esta fila no tiene etiqueta de campo visible) — abre el WebResource Field Mapping, cuya ventana emergente se titula Company Mapping (ver §5.2).

5.2 Asignación de campos

Haga clic en el botón Configure company mapping de la pestaña Company Setup para abrir el WebResource FieldMapping (su ventana emergente se titula Company Mapping). Esto define qué campos de datos de SIRENE se asignan a qué campos de Dynamics en la entidad Account.

• Las asignaciones se almacenan en la tabla dqe_field_mapping en Dataverse.
• Haga clic en Initialize Default Records para precargar una asignación estándar. Es seguro ejecutarlo varias veces — solo crea los registros que faltan, no sobrescribe los existentes.

5.3 Configuración del formulario

Añada los dos controles B2B al formulario Account: CompanyField en el campo de razón social y CompanyNumberField en el campo de número de empresa. Ambos controles llaman a la misma Custom API, DQE - Siretisation - Search.

CompanyField — Campo de razón social

CompanyField · Custom API: DQE - Siretisation - Search

CompanyNumberField — Campo de número de empresa

CompanyNumberField · Custom API: DQE - Siretisation - Search

5.4 Columnas de la lista desplegable

Sobrescriba las columnas predeterminadas de la lista desplegable de CompanyField estableciendo el parámetro columns como JSON en el form XML.

[
  {"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 propiedades disponibles:

CompanyName CompanyName2 CompanyCName CompanyNumber ZIP_Code CompanyAddress1 CompanyAddress2 CompanyAddress3 Locality Phone Fax Email Activity1 Activity2 StaffCount TurnOver LegalStructureCode LegalStructureLabel IncorporationDate DissolutionDate Country CompanyStatus CompanySIC IntraNumber MainCompanyFlag Ref

Consejo: un plugin editor de form XML de XrmToolBox puede simplificar la exportación y edición del form XML.

5.5 Parámetro de filtro

Tanto CompanyField como CompanyNumberField aceptan un parámetro opcional filter, pasado directamente a la API RECSIRET. Puede establecerse de forma estática en Component Properties o dinámicamente a partir de un valor de campo. Contacte con su gestor de proyecto de DQE para conocer las cadenas de filtro disponibles.

5.6 Resultado esperado

1. El usuario abre un registro Account y empieza a escribir una razón social o un SIRET.
2. Aparece una lista desplegable con las empresas coincidentes de la base de datos SIRENE.
3. El usuario selecciona una empresa — los campos asignados (dirección, SIRET, forma jurídica…) se rellenan automáticamente.
4. 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 buscar.