Crear y administrar aplicaciones de negocio personalizadas en Customer Engagement mediante código

Las aplicaciones de negocio de Dynamics 365 Customer Engagement son aplicaciones modulares especialmente diseñadas que proporcionan funcionalidad basada en roles que es relevante para un área de trabajo específica. Estas aplicaciones permiten que los usuarios encuentren de forma rápida y sencilla lo que necesitan hacer cada día mediante una simple e intuitiva. Por ejemplo, la aplicación de negocio Sales proporciona un mapa del sitio más sencillo y más pequeño con solo el conjunto adecuado de formularios, vistas, paneles y flujos de proceso que sean relevantes para el personal de ventas.

Los personalizadores y los administradores del sistema pueden proporcionar a los usuarios acceso a estas aplicaciones de negocio mediante los roles de seguridad; los usuarios solo pueden acceder a las aplicaciones para las que tienen permiso.

Nota

Las aplicaciones de negocios personalizadas en Dynamics 365 Customer Engagement son las mismas que las aplicaciones basadas en modelos de Power Apps; ambas se basan en la misma plataforma subyacente. Más información: ¿Qué son las aplicaciones basadas en modelo?

Además de crear aplicaciones de negocio personalizadas mediante el diseñador de aplicaciones, puede crear y administrar aplicaciones de negocio personalizadas mediante programación en Dynamics 365 Customer Engagement (on-premises).

Importante

No tiene que escribir código para crear aplicaciones de negocio personalizadas si no es necesario. El diseñador de aplicaciones proporciona una experiencia más sencilla e intuitiva para la creación de aplicaciones de negocio personalizadas sin necesidad de escribir código mediante el suministro de una estructura de información basada en ventanas y una interfaz simplificada. Consúltelo aquí: Diseñar aplicaciones de negocio personalizadas mediante el diseñador de aplicaciones

La creación de una aplicación de negocio personalizada implica los pasos siguientes:

1. Crear una instancia entidad AppModule para definir la aplicación y sus propiedades.
2. Agregar o quitar componentes de la aplicación como la entidad, el mapa del sitio y otros componentes de su aplicación personalizada mediante las acciones AddAppComponents y RemoveAppComponents.
3. Comprobar que la aplicación tenga todos los componentes necesarios que faltan mediante la función ValidateApp.
4. Publicar la aplicación.
5. Asociar roles de seguridad adecuados a la aplicación de negocio personalizada para proporcionar acceso a los usuarios.

Crear la aplicación de negocio y definir sus propiedades

Para poder crear una aplicación debe disponer del rol de seguridad de Administrador del sistema o de Personalizador del sistema o permisos equivalentes.

Especifique como mínimo las siguientes propiedades para crear una aplicación:

• name: único para la aplicación
• uniquename: puede ser diferente del nombre de la aplicación y solo puede tener caracteres en inglés y números. Al crear esta aplicación, el nombre se antepone automáticamente con su prefijo de editor de soluciones (por ejemplo, 'new_').
• webresourceid: identificador de los recursos web que desea establecer como el icono de imagen de la aplicación. El sistema proporciona un recurso web predeterminado (identificador: 953b9fac-1e5e-e611-80d6-00155ded156f) que puede usar como icono de la aplicación.

La siguiente solicitud de API web crea un tipo de interfaz unificada de una aplicación:

POST [Organization URI]/api/data/v9.1/appmodules HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "name": "SDKTestApp",
    "uniquename":"SDKTestApp",
    "webresourceid":"953b9fac-1e5e-e611-80d6-00155ded156f"    
}

El encabezado OData-EntityId de respuesta contiene el URI de la aplicación creada.

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.1/appmodules(dd621d4a-d898-e711-80e7-00155db763be)

Agregar o quitar componentes de la aplicación de negocio

Puede agregar o quitar componentes de una aplicación como el mapa del sitio, la entidad, el panel, los flujos de procesos empresariales, las vistas y los formularios que desea incluir en su aplicación de negocio. Para obtener información detallada sobre los componentes que se pueden agregar a una aplicación de negocio, vea Agregar o editar componentes de la aplicación en el diseñador de aplicaciones.

Utilice la acción AddAppComponents o el mensaje AddAppComponentsRequest para agregar componentes a la aplicación de negocio. La acción requiere que especifique lo siguiente:

• AppId: identificador de la aplicación en la que desea agregar componentes
• Components Una colección de componentes que se va a agregar. Debe especificar el identificador y el tipo de entidad del componente que desea agregar. Para obtener una lista de los tipos de entidad en la API web de Customer Engagement, consulte Web API Entity Type Reference.

La siguiente solicitud de la API web agrega una vista (savedquery) y un formulario (systemform) a la aplicación:

POST [Organization URI]/api/data/v9.1/AddAppComponents HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
	"AppId":"dd621d4a-d898-e711-80e7-00155db763be",
	"Components":[
		{
			"savedqueryid":"00000000-0000-0000-00aa-000000666000",
			"@odata.type":"Microsoft.Dynamics.CRM.savedquery"
		},
		{
			"formid":"c9e7ec2d-efca-4e4c-b3e3-f63c4bba5e4b",
			"@odata.type":"Microsoft.Dynamics.CRM.systemform"
		}
	]
}

Para quitar un componente de una aplicación, utilice la acción RemoveAppComponents o el mensaje RemoveAppComponentsRequest. Esta acción tiene el mismo conjunto de parámetros que la acción AddAppComponents.

La siguiente solicitud de la API web quita una vista (savedquery) de la aplicación:

POST [Organization URI]/api/data/v9.1/RemoveAppComponents HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
	"AppId":"dd621d4a-d898-e711-80e7-00155db763be",
	"Components":[
		{
			"savedqueryid":"00000000-0000-0000-00aa-000000666000",
			"@odata.type":"Microsoft.Dynamics.CRM.savedquery"
		}
	]
}

Validar la aplicación de negocio

Validar una aplicación implica comprobar las dependencias de los componentes que ha agregado a la aplicación de negocio para asegurarse de que la aplicación funciona correctamente. Es lo mismo que hacer clic en Validar en el diseñador de la aplicación. Más información: Validar la aplicación

Utilice la función ValidateApp o el mensaje ValidateAppRequest para validar la aplicación. La siguiente solicitud de la API web muestra cómo validar la aplicación empresarial con identificador dd621d4a-d898-e711-80e7-00155db763be:

GET [Organization URI]/api/data/v9.1/ValidateApp(AppModuleId=dd621d4a-d898-e711-80e7-00155db763be)

Si no hay ningún error de validación, la respuesta es la siguiente:

HTTP/1.1 200 OK
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.ValidateAppResponse",
    "AppValidationResponse": {
        "ValidationSuccess": true,
        "ValidationIssueList": []
    }
}

Si hay problemas de validación en la aplicación, la respuesta muestra errores o advertencias en la colección ValidationIssueList:

HTTP/1.1 200 OK
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.ValidateAppResponse",
    "AppValidationResponse": {
        "ValidationSuccess": false,
        "ValidationIssueList": [
            {
                "ErrorType": "Error",
                "Message": "App does not contain Site Map",
                "DisplayName": null,
                "ComponentId": "00000000-0000-0000-0000-000000000000",
                "ComponentType": 0,
                "ComponentSubType": 0,
                "ParentEntityId": "00000000-0000-0000-0000-000000000000",
                "ParentEntityName": null,
                "CRMErrorCode": -2147155684,
                "RequiredComponents": []
            },
            {
                "ErrorType": "Warning",
                "Message": "Account doesn’t reference a form or view. App users will see all forms and views.",
                "DisplayName": null,
                "ComponentId": "00000000-0000-0000-0000-000000000000",
                "ComponentType": 0,
                "ComponentSubType": 0,
                "ParentEntityId": "00000000-0000-0000-0000-000000000000",
                "ParentEntityName": null,
                "CRMErrorCode": -2147155691,
                "RequiredComponents": []
            }
        ]
    }
}

Publicar la aplicación de negocio

Después de agregar los componentes necesarios a la aplicación de negocio personalizada y validarla, debe publicarla para que esté disponible para los usuarios.

Utilice la acción PublishXml o el mensaje PublishXmlRequest para publicar la aplicación de negocio personalizada. La siguiente solicitud muestra cómo publicar la aplicación empresarial con identificador dd621d4a-d898-e711-80e7-00155db763be:

POST [Organization URI]/api/data/v9.1/PublishXml HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{  
  "ParameterXml":"<importexportxml><appmodules><appmodule>dd621d4a-d898-e711-80e7-00155db763be</appmodule></appmodules></importexportxml>"
}

Administrar el acceso a la aplicación de negocio mediante roles de seguridad

Para proporcionar a los usuarios acceso a las aplicaciones de forma que puedan acceder a ellas desde su área Configuración>Mis aplicaciones o desde la página de inicio de Dynamics 365 Customer Engagement (on-premises), puede asociar roles de seguridad a las aplicaciones de negocio. Los usuarios asignados a los roles de seguridad asociados pueden ver y usar las aplicaciones de negocio en Customer Engagement.

Utilice la propiedad de navegación appmoduleroles_association de la entidad Entidad AppModule para asociar una aplicación de negocio con un rol de seguridad. La siguiente solicitud muestra cómo asociar una aplicación de negocio con un rol de seguridad:

POST [Organization URI]/api/data/v9.1/appmodules(dd621d4a-d898-e711-80e7-00155db763be)appmoduleroles_association/$ref HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{  
  "@odata.id":"[Organization URI]/api/data/v9.1/roles(<roleId>)"
}

Para desvincular un rol de seguridad de una aplicación de negocio, use la solicitud DELETE con la misma propiedad de navegación. Por ejemplo:

DELETE [Organization URI]/api/data/v9.1/appmodules(dd621d4a-d898-e711-80e7-00155db763be)/appmoduleroles_association/$ref?$id=[Organization URI]/api/data/v9.1/roles(<roleId)

Administrar las aplicaciones de negocio y sus componentes

En esta sección se ofrece información acerca de cómo recuperar las aplicaciones, actualizar las propiedades de la aplicación, recuperar los componentes de la aplicación y eliminar aplicaciones.

Recuperar aplicaciones publicadas

Para recuperar las aplicaciones publicadas, utilice la solicitud siguiente:

GET [Organization URI]/api/data/v9.1/appmodules?$select=name

Recuperar aplicaciones no publicadas

Para recuperar aplicaciones no publicadas, utilice la función RetrieveUnpublishedMultiple. Por ejemplo:

GET [Organization URI]/api/data/v9.1/appmodules/Microsoft.Dynamics.CRM.RetrieveUnpublishedMultiple()?$select=name

Recuperar componentes de una aplicación de negocio publicada

Para recuperar componentes de una aplicación de negocio, utilice la función RetrieveAppComponents o el mensaje RetrieveAppComponentsRequest. Por ejemplo:

GET [Organization URI]/api/data/v9.1/RetrieveAppComponents(AppModuleId=dd621d4a-d898-e711-80e7-00155db763be)

Recuperar roles de seguridad asociados con aplicaciones de negocio publicadas

Para recuperar los roles de seguridad asociados con la aplicación de negocio, utilice la opción consulta del sistema $expand con la propiedad de navegación appmoduleroles_association. Por ejemplo, esta es la solicitud para recuperar todos los roles de seguridad asociados con una aplicación empresarial con identificador: dd621d4a-d898-e711-80e7-00155db763be:

GET [Organization URI]/api/data/v9.1/appmodules(dd621d4a-d898-e711-80e7-00155db763be)?$expand=appmoduleroles_association&$select=name,appmoduleroles_association

Eliminar aplicaciones de negocio

Utilice la solicitud DELETE para eliminar una aplicación de negocio. Por ejemplo:

DELETE [Organization URI]/api/data/v9.1/appmodules(dd621d4a-d898-e711-80e7-00155db763be)

Compatibilidad de la API de cliente para aplicaciones de negocio

Puede usar las siguientes API de cliente para trabajar con aplicaciones de negocio:

• getCurrentAppName
• getCurrentAppProperties
• getCurrentAppUrl

Vea también

Diseñar aplicaciones de negocio personalizadas mediante el diseñador de aplicaciones