tablas Catalog y CatalogAssignment

Utilice las tablas Catalog y CatalogAssignment para crear una estructura para exponer las acciones utilizadas en su solución como eventos de negocio. Los eventos empresariales de Microsoft Dataverse permiten crear integraciones con otras aplicaciones en muchos escenarios a través de Dataverse. Más información: Eventos empresariales de Microsoft Dataverse

Su catálogo describirá aquellos eventos que son relevantes para su solución para que las personas puedan usarlos. Si no cataloga los eventos relevantes para su solución, es posible que no estén disponibles para las personas que utilizan su solución.

Usa la tabla Catalog para crear una jerarquía de dos niveles. Esto creará un grupo Catálogo y Categoría donde el catálogo de segundo nivel representa la categoría.

El catálogo de primer nivel debe representar su solución. Utilice varios catálogos de segundo nivel relacionados con su catálogo de primer nivel para agrupar diferentes categorías de funcionalidades dentro de su solución.

Para cada catálogo de segundo nivel que represente las categorías dentro de su solución, utilizará la tabla CatalogAssignment para especificar las acciones de Tablas, API personalizadas o Procesos personalizados que desee que estén disponibles como eventos.

Importante

Los usuarios con el rol de seguridad Creador de entorno pueden ver los datos del catálogo en el conector Dataverse de Power Automate, en el desencadenador Cuando se realiza una acción. Otros roles de seguridad deben tener el privilegio de lectura de nivel adecuado para estas tablas: API personalizada, Proceso, Mensaje de SDK.

Más información:

Ejemplo: Contoso Customer Management

Para presentar la idea de un catálogo, comencemos con un ejemplo.

La solución de administración de clientes de Contoso contiene muchos componentes. Los únicos componentes que interesan aquí son:

  • Tablas
  • API personalizada
  • Acción de proceso personalizada (flujo de trabajo)

Tablas

La administración de clientes de Contoso es una solución que incluye las siguientes tablas:

SchemaName Nombre para mostrar Descripción
Account Cuenta Una tabla del sistema de Dataverse
Contact CONTACTO Una tabla del sistema de Dataverse
contoso_Membership Membresía Una tabla personalizada propiedad de la organización

API personalizada

También han creado una serie de acciones de API personalizadas a las que llama su sistema de punto de venta, su sitio web y los sistemas ERP para notificar a Dataverse de eventos que no se originan en Dataverse:

UniqueName Nombre para mostrar
contoso_CustomerEnteredStore Tienda visitada
contoso_CustomerVisitWebSite Visitar el sitio web
contoso_CustomerPurchasedProduct Producto comprado
contoso_CustomerReturnedProduct Producto devuelto

Estructura del catálogo

El catálogo de soluciones de administración de clientes de Contoso tiene este aspecto:

Catálogo Descripción
Gestión de clientes de Contoso Catálogo principal
    Tablas Categoría de catálogo de segundo nivel
            Cuenta CatalogAssignment: Entity
            CONTACTO CatalogAssignment: Entity
            Membresía CatalogAssignment: Entidad
    Eventos del cliente Categoría de catálogo de segundo nivel
            Tienda visitada CatalogAssignment: CustomAPI
            Visitar el sitio web CatalogAssignment: CustomAPI
            Comprar el producto CatalogAssignment: CustomAPI
            Devolver el producto CatalogAssignment: CustomAPI

Eventos disponibles

Cuando realiza un CatalogAssignment en una tabla, algunas operaciones vinculadas al sistema para esa tabla están disponibles como eventos.

Con este catálogo estarán disponibles los siguientes eventos:

Tabla Evento Por qué disponible
Cuenta Crear
Actualización
Eliminar		 Operación de datos estándar
Cuenta Conceder acceso
Modificar acceso
Revocar acceso		 La entidad propiedad del usuario se puede compartir.
CONTACTO Crear
Actualización
Eliminar		 Operación de datos estándar
CONTACTO Conceder acceso
Modificar acceso
Revocar acceso		 La entidad propiedad del usuario se puede compartir.
Membresía Crear
Actualización
Eliminar		 Operación de datos estándar
N/D contoso_CustomerEnteredStore Asignación de catálogo explícita
N/D contoso_CustomerVisitWebSite Asignación de catálogo explícita
N/D contoso_CustomerPurchasedProduct Asignación de catálogo explícita
N/D contoso_CustomerReturnedProduct Asignación de catálogo explícita

La mayoría de las tablas admitirán los eventos de creación, actualización y eliminación. Hay algunas excepciones. Las tablas propiedad del usuario expondrán eventos para cambios en la compartición: GrantAccess, ModifyAccess y RevokeAccess

Nota

También se incluirá cualquier API personalizada o acciones de proceso personalizadas que estén vinculadas a la tabla.

Se mostrarán las acciones de proceso personalizadas que están deshabilitadas, pero el evento nunca ocurrirá hasta que estén habilitadas y utilizadas.

Crear un catálogo en Power Apps

Puede crear registros Catálogo y Asignación de catálogo en Power Apps (https://make.powerapps.com).

Siempre debe crear un catálogo como parte de una solución. Utilice las siguientes instrucciones para crear registros de catálogo:

  1. Inicie sesión en Power Apps.

  2. En el panel de navegación izquierdo, seleccione Soluciones.

  3. Cree o seleccione una solución que desee utilizar, luego haga clic en New.

  4. Seleccione Catálogo en el menú y se abrirá una nueva ventana.

  5. Introduzca los campos siguientes:

    Campo Descripción
    Catálogo de origen No establezca un catálogo padre para el catálogo raíz de la solución. De lo contrario, configure el catálogo raíz de la solución.
    Nombre único El nombre exclusivo debe tener un prefijo de personalización y no debe tener espacios. Este prefijo debería ser el mismo que el prefijo de personalización para el editor de soluciones.
    Nombre Escriba un nombre para el catálogo. Normalmente el mismo que el Nombre único, pero sin el prefijo de personalización y con espacios.
    Nombre para mostrar Normalmente es el mismo que el Nombre.
    Descripción Escriba una descripción relevante del catálogo.

  6. Guardar y cerrar el formulario.

Cree una Asignación de catálogo en Power Apps

Usando la misma solución que contiene el catálogo en Power Apps

  1. Haga clic en Nuevo.

  2. Seleccione Asignación de catálogo en el menú y se abrirá una nueva ventana.

  3. Escriba el Nombre. Este valor debe empezar con un prefijo de personalización y no debe tener espacios. Debería usar el mismo prefijo de personalización definido por su publicador de soluciones.

  4. Establezca el Objeto de asignación de catálogo. Esta búsqueda permite configurar tres tipos diferentes de registros:

    • API personalizada
    • Entidades
    • Procesos

    Debería poder descubrir el tipo que está buscando escribiendo el nombre.

  5. Seleccione un catálogo

    Nota

    El catálogo que seleccione debe ser un catálogo de segundo nivel que represente una categoría.

  6. Guardar y cerrar el formulario

Bloquear la personalización de los elementos del catálogo en su solución administrada

A menos que desee permitir que las personas que instalan su solución administrada puedan personalizar el catálogo y las asignaciones del catálogo, debe asegurarse de establecer la propiedad IsCustomizable en false, ya que el valor predeterminado permite personalizarlos.

Para establecer esto en la interfaz de usuario de Power Apps:

  1. Seleccione cada catálogo o asignación de catálogo dentro de su solución

  2. En el menú, haga clic en los puntos suspensivos (...) y seleccione Managed Properties.

    Haga clic en los puntos suspensivos para ver el botón Propiedades administradas.

  3. En la ventana que se abre, desmarque Permitir personalizaciones.

    Desmarque

  4. Haga clic en Listo

Diagrama de tablas

En el siguiente diagrama se muestran las relaciones entre las tablas Catalog y CatalogAssignment

Diagrama de tablas Catalog y CatalogAssignment

La relación autorreferencial usando ParentCatalogId es lo que permite crear la jerarquía de dos niveles entre un catálogo de soluciones y varios catálogos que representan categorías utilizando registros de catálogo.

Columnas de tabla de catálogo

Todas las columnas y relaciones están disponibles en Referencia de tabla o entidad de catálogo.

La siguiente tabla incluye columnas/atributos seleccionados de una tabla o entidad de catálogo que puede configurar.

Nombre para mostrar
SchemaName
LogicalName		 Tipo Descripción
Catálogo
CatalogId
catalogid		 Uniqueidentifier Identificador único de instancias del catálogo.
Descripción
Description
description		 String Descripción localizada de las instancias del catálogo.
Obligatorio
Nombre para mostrar
DisplayName
displayname		 String Nombre para mostrar localizado de las instancias del catálogo.
Obligatorio
Es personalizable
IsCustomizable
iscustomizable		 ManagedProperty Controla si el catálogo se puede personalizar o eliminar.
El valor predeterminado es verdadero. Más información: Bloquear la personalización de los ítems de catálogo en su solución administrada
Obligatorio
Nombre
Name
name		 String Nombre principal del catálogo.
Obligatorio
Catálogo padre
ParentCatalogId
parentcatalogid		 Buscar Identificador único del catálogo principal.
No se puede cambiar después de guardarlo.
Nombre único
UniqueName
uniquename		 String Nombre único para el catálogo.
Obligatorio
Debe comenzar con un prefijo de personalización.

Nota

Cuando asocie una asignación de catálogo a un catálogo, no podrá eliminar el catálogo hasta que elimine la asignación de catálogo.

Columnas de la tabla CatalogAssignment

Todas las columnas y relaciones están disponibles en Referencia de tabla o entidad de CatalogAssignment.

La siguiente tabla incluye columnas/atributos seleccionados de una tabla o entidad de CatalogAssignment que puede configurar.

Nombre para mostrar
SchemaName
LogicalName		 Tipo Descripción
Asignación de catálogo
CatalogAssignmentId
catalogassignmentid		 Uniqueidentifier Identificador único de las instancias de asignación de catálogo.
catálogo
CatalogId
catalogid		 Buscar Identificador único del catálogo asociado con la asignación de catálogo.
Obligatorio
Es personalizable
IsCustomizable
iscustomizable		 ManagedProperty Controla si el CatalogAssignment se puede personalizar o eliminar.
El valor predeterminado es verdadero. Más información: Bloquear la personalización de los ítems de catálogo en su solución administrada
Obligatorio
Nombre
Name
name		 String Nombre principal de la asignación de catálogo.
Objeto de asignación de catálogo
Object
object		 Buscar Identificador único del objeto asociado con la asignación de catálogo.
Obligatorio
No se puede cambiar después de guardarlo.
Esta búsqueda polimórfica se puede vincular a las siguientes tablas:
  customapi
  entidad
  flujo de trabajo

Al utilizar la API web para asociar esta relación polimórfica, debe utilizar los nombres de propiedad de navegación de un solo valor para cada relación.

Estos nombres son:
  CustomAPIId
  EntityId
  WorkflowId

Cuando se asocia a una tabla, una API personalizada o una acción de proceso personalizada, deberá obtener el valor respectiveid. Consulte Obtener el id. de los elementos de CatalogAssignment para más información.

Obtener el id. de los elementos de CatalogAssignment

Deberá obtener el id. de las entidades, las API personalizadas y las acciones de proceso personalizadas cuando las asocie con una `CatalogAssignment`.

Obtener el id. de una tabla

La tabla Entidad contiene una fila por cada entidad. Puede obtener el id. de una tabla específica, como la tabla Cuenta, mediante cualquiera de estas consultas mediante la API web:

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')?$select=MetadataId

GET [Organization URI]/api/data/v9.2/entities?$select=entityid&$filter=name eq 'Account'

Obtener el id. de una API personalizada

Esto se hace más fácilmente usando la API web. El siguiente ejemplo devolverá el customapiid de una api personalizada con el uniquename de your_CustomAPIName.

GET [Organization URI]/api/data/v9.2/customapis?$select=customapiid&$filter=uniquename eq 'your_CustomAPIName'

Obtener el id. de una acción de proceso personalizada

Esto se hace más fácilmente usando la API web. El siguiente ejemplo devolverá el workflowid de una acción de proceso personalizar con el uniquename de ExampleCustomProcessAction.

GET [Organization URI]/api/data/v9.2/workflows?$select=workflowid,uniquename&$filter=category eq 3 and type eq 1 and endswith(uniquename,'ExampleCustomProcessAction')

Nota

El uniquename del flujo de trabajo no incluye el prefijo de personalización que se antepone al nombre de la acción del proceso personalizado en la API web. Si la acción que llama desde la API web se llama new_ExampleCustomProcessAction, el nombre único del flujo de trabajo será ExampleCustomProcessAction.

Asegúrese de acceder a la fila donde Tipo sea 1. Este es la definición de flujo de trabajo.

Los flujos de trabajo de acciones de proceso personalizadas tienen el valor de Categoría de 3.

Recuperar asignaciones de catálogo existentes

Puede utilizar la siguiente consulta de OData para recuperar información sobre las asignaciones de catálogo, el tipo de asignación, el catálogo con el que están asociadas y el catálogo principal.

GET [Organization URI]/api/data/v9.2/catalogassignments?$select=name
    &$expand=CatalogId($select=uniquename;$expand=ParentCatalogId($select=uniquename)),
    EntityId($select=entityid),
    CustomAPIId($select=uniquename),
    WorkflowId($select=uniquename)
    &$filter=name ne null

Crear catálogos y asignaciones de catálogos con código

Puede crear catálogos y registros de asignación de catálogos utilizando la API web o el SDK para .NET.

Uso de la API web

Nota

En este momento no es posible crear catálogos y registros de asignación de catálogos usando 'deep-insert'.

Puede crear una jerarquía de registros de catálogo utilizando 'deep-insert', pero debe crear las asignaciones de catálogo individualmente.

La siguiente serie de operaciones de API web creará una jerarquía de catálogo y una CatalogAssignment en una solución con UniqueName: ContosoCustomerManagement. Tenga en cuenta el uso del encabezado de solicitud MSCRM.SolutionUniqueName para establecer la asociación a la solución cuando se crea el registro.

Consulte las secciones Crear un registro usando la API web: Creación básica y Asociar filas de tabla al crear para más información.

Crear el catálogo raíz

Solicitud:

POST [Organization URI]/api/data/v9.2/catalogs HTTP/1.1
MSCRM.SolutionUniqueName: ContosoCustomerManagement
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
    "name": "Contoso Customer Management",
    "uniquename": "contoso_CustomerManagement",
    "displayname": "Contoso Customer Management",
    "description": "The root catalog for the Contoso Customer Management solution",
    "iscustomizable": {
        "Value": false
    }
}

Respuesta:

HTTP/1.1 204 No Content
OData-EntityId: [Organization URI]/api/data/v9.2/catalogs(a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1)

Crear el subcatálogo de eventos de la tabla

Solicitud:

POST [Organization URI]/api/data/v9.2/catalogs HTTP/1.1
MSCRM.SolutionUniqueName: ContosoCustomerManagement
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
    "name": "Contoso Customer Management Table Events",
    "uniquename": "contoso_TableEvents",
    "displayname": "Tables",
    "description": "Groups Table events for the Contoso Customer Management Solution",
    "iscustomizable": {
        "Value": false
    },
    "ParentCatalogId@odata.bind": "catalogs(a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1)"
}

Respuesta:

HTTP/1.1 204 No Content
OData-EntityId: [Organization URI]/api/data/v9.2/catalogassignments(b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2)

Crear la asignación del catálogo de cuentas en el catálogo de tablas

Consulte Obtener el id. de una tabla para obtener información sobre el id. de una tabla.

Solicitud:

POST [Organization URI]/api/data/v9.2/catalogassignments HTTP/1.1
MSCRM.SolutionUniqueName: ContosoCustomerManagement
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
    "name": "Account",
    "EntityId@odata.bind": "entities(70816501-edb9-4740-a16c-6a5efbc05d84)",
    "iscustomizable": {
        "Value": false
    },
    "CatalogId@odata.bind": "catalogs(b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2)"
}

Respuesta:

HTTP/1.1 204 No Content
OData-EntityId: [Organization URI]/api/data/v9.2/catalogassignments(c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3)

Uso del SDK para .NET

El siguiente código muestra la creación de una jerarquía de catálogo y una asignación de catálogo en una solución con UniqueName: ContosoCustomerManagement.

Nota

Utilice el parámetro opcional SolutionUniqueName con la Clase CreateRequest para crear los registros en el contexto de esa solución. Más información: Pasar parámetros opcionales con una solicitud

string conn = $@"
Url = {url};
AuthType = OAuth;
UserName = {userName};
Password = {password};
AppId = 51f81489-12ee-4a9e-aaae-a2591f45987d;
RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97;
LoginPrompt=Auto;
RequireNewInstance = True";

var service = new CrmServiceClient(conn);
// var service = new ServiceClient(conn);

var solutionUniqueName = " ContosoCustomerManagement ";

//Create the root catalog
Catalog rootCatalog = new Catalog
{
    Name = "Contoso Customer Management",
    UniqueName = "contoso_CustomerManagement",
    DisplayName = "Contoso Customer Management",
    Description = "The root catalog for the Contoso Customer Management solution",
    IsCustomizable = new BooleanManagedProperty(false)
};

CreateRequest rootCatalogReq = new CreateRequest {
    Target = rootCatalog
};
rootCatalogReq["SolutionUniqueName"] = solutionUniqueName;

Guid rootCatalogId = ((CreateResponse)service.Execute(rootCatalogReq)).id;

//Create the Table Events Sub-catalog
Catalog tableEvents = new Catalog
{
    Name = "Contoso Customer Management Table Events",
    UniqueName = "contoso_TableEvents",
    DisplayName = "Tables",
    Description = "Groups Table events for the Contoso Customer Management Solution",
    IsCustomizable = new BooleanManagedProperty(false),
    ParentCatalogId = new EntityReference("catalog", rootCatalogId)
};

CreateRequest tableEventsReq = new CreateRequest
{
    Target = tableEvents
};
tableEventsReq["SolutionUniqueName"] = solutionUniqueName;

Guid tableEventsId = ((CreateResponse)service.Execute(tableEventsReq)).id;

//Create the Account Catalog Assignment on the Tables catalog
CatalogAssignment accountAssignment = new CatalogAssignment
{
    Name = "Account",
    IsCustomizable = new BooleanManagedProperty(false),
    Object = new EntityReference("entity",new Guid("70816501-edb9-4740-a16c-6a5efbc05d84")),
    CatalogId = new EntityReference("catalog", tableEventsId)

};

CreateRequest accountAssignmentReq = new CreateRequest
{
    Target = accountAssignment
};
accountAssignmentReq["SolutionUniqueName"] = solutionUniqueName;

Guid accountAssignmentId = ((CreateResponse)service.Execute(accountAssignmentReq)).id;

Crear catálogos y asignaciones de catálogos editando archivos de soluciones

Dentro de un archivo de solución, puede editar los archivos para crear catálogos y asignaciones de catálogos.

Utilice la Herramienta SolutionPackager para extraer una solución en archivos que se pueden administrar en el control de código de origen. A continuación, puede editar los archivos. A continuación, puede utilizar SolutionPackager para volver a empaquetar los archivos extraídos en una solución. Más información : Control de código fuente con archivos de solución

Consejo

Cree algunos catálogos y asignaciones de catálogos en una solución, luego exporte y extraiga la solución para ver algunos ejemplos.

Asegúrese de que está utilizando la última versión del Paquete Microsoft.CrmSdk.CoreTools NuGet

Crear un catálogo con archivos de solución

Dentro de una solución, todos los catálogos estarán en la carpeta catalogs. Puede crear, modificar o eliminar catálogos editando las carpetas y archivos en esta carpeta e importando la solución después de que se haya empaquetado usando el empaquetador de soluciones.

Cada catálogo se incluirá en una carpeta que coincida con el uniquename del catálogo, como contoso_CustomerManagement.

Dentro de la carpeta hay un archivo catalog.xml que contiene la definición del catálogo.

Por ejemplo: 

<catalog uniquename="contoso_CustomerManagement">
    <description default="The root catalog for the Contoso Customer Management solution">
        <label description="The root catalog for the Contoso Customer Management solution" languagecode="1033" />
    </description>
    <displayname default="Contoso Customer Management">
        <label description="Contoso Customer Management" languagecode="1033" />
    </displayname>
    <iscustomizable>0</iscustomizable>
    <name>Contoso Customer Management</name>
</catalog>

El atributo catalog del elemento uniquename debe coincidir con el nombre de la carpeta que contiene el archivo.

El elemento catalog incluye estos elementos:

Elemento Descripción
description Tiene un atributo default con el valor de la descripción predeterminada.
Contiene uno o más elementos label con atributos para description y languagecode cuando se definen varios idiomas.
displayname Tiene un atributo default con el valor del nombre para mostrar predeterminado.
Contiene uno o más elementos label con atributos para description y languagecode cuando se definen varios idiomas.
iscustomizable Si el catálogo es personalizable. 0 = false, 1 = true.
name El nombre del catálogo.

Si el catálogo representa una categoría, la relación con el catálogo principal se incluye mediante un elemento parentcatalogid que contiene un elemento uniquename que contiene el nombre único del catálogo principal.

Por ejemplo: 

<catalog uniquename="contoso_TableEvents">
    <description default="Groups Table events for the Contoso Customer Management Solution">
        <label description="Groups Table events for the Contoso Customer Management Solution" languagecode="1033" />
    </description>
    <displayname default="Tables">
        <label description="Tables" languagecode="1033" />
    </displayname>
    <iscustomizable>0</iscustomizable>
    <name>Contoso Customer Management Table Events</name>
    <parentcatalogid>
        <uniquename>contoso_CustomerManagement</uniquename>
    </parentcatalogid>
</catalog>

Crear una CatalogAssignment con archivos de solución

Dentro de una solución, en la carpeta Assets, encontrará un archivo catalogassignments.xml. Todas las asignaciones del catálogo se incluyen en el archivo. Puede crear o modificar asignaciones de catálogos editando este archivo e importando la solución después de que se haya empaquetado usando el empaquetador de soluciones.

Por ejemplo: 

<catalogassignments>
    <catalogassignment object.logicalname="account" catalogid.uniquename="contoso_TableEvents" objectidtype="entity">
        <iscustomizable>0</iscustomizable>
        <name>Account</name>
    </catalogassignment>
    <catalogassignment catalogid.uniquename="contoso_CustomerEvents" object.uniquename="contoso_CustomerEnteredStore" objectidtype="customapi">
        <iscustomizable>0</iscustomizable>
        <name>Customer Entered Store</name>
  </catalogassignment>
</catalogassignments>

Cada elemento catalogassignment tiene estos atributos:

Atributo Descripción
catalogid.uniquename Nombre único del sub-catálogo para el que es la asignación de catálogo.
objecttypeid Tipo del objeto. Los valores válidos son:
entity
customapi
workflow

Dependiendo del objectypeid, cada elemento catalogassignment debe tener uno de estos atributos correspondientes:

Atributo Descripción
object.uniquename Nombre único de la API personalizada.
object.logicalname El nombre lógico de la entidad.
object.workflowid El valor de identificación único de la acción del proceso personalizado.

El elemento catalogassignment incluye estos elementos:

Elemento Descripción
iscustomizable Si la asignación del catálogo es personalizable. 0 = false, 1 = true.
name Nombre de la asignación de catálogo

Consulte también

Eventos de negocio de Microsoft Dataverse
Crear un registro de entidad usando la API web
Recuperar un registro de entidad usando la API web
Crear entidades con SDK para .NET
Recuperar una entidad usando SDK para .NET

  • Última actualización el