Integración de Power Automate con sitios web y aplicaciones

Inserte Power Automate en su aplicación o sitio web mediante flow widgets para ofrecer a los usuarios una manera sencilla de automatizar sus tareas personales o profesionales.

Los widgets de Flow son iframes ubicados en un documento de host. Este documento enlaza con una página del diseñador de Power Automate. Estos widgets integran la funcionalidad específica de Power Automate en la aplicación que no es de Microsoft.

Los widgets pueden ser sencillos. Por ejemplo, un widget que representa una lista de plantillas sin comunicación alguna entre el host y el iframe. Los widgets también pueden ser complejos. Por ejemplo, un widget que aprovisiona un flujo de nube a partir de una plantilla y, después, lo desencadena a través de una comunicación bidireccional entre el host y el widget.

Prerrequisitos

• Una cuenta Microsoft o bien
• Una cuenta profesional o educativa

Uso del widget sin autenticar

Para usar el widget de plantillas no autenticadas, insértelo directamente en la aplicación host mediante un iframe. No se necesita el SDK de JS ni un token de acceso.

Presentación de plantillas para sus escenarios

Para empezar, agregue este código para mostrar las plantillas de Power Automate en su sitio web:

<iframe src="https://make.powerautomate.com/{locale}/widgets/templates/?q={search term}
&pagesize={number of templates}&destination={destination}&category={category}"></iframe>

Si el parámetro de destino es new, el diseñador de Power Automate se abre cuando los usuarios seleccionan una plantilla. Después, los usuarios pueden crear un flujo de nube en el diseñador. Si quiere tener la experiencia completa desde el widget, vea la sección siguiente.

Pasar más parámetros a la plantilla de flujo

Si el usuario está en un contexto determinado en el sitio web o la aplicación, es posible que quiera pasar ese contexto al flujo. Por ejemplo, un usuario podría abrir una plantilla para Cuando se crea un elemento mientras examina una lista determinada en SharePoint. Siga estos pasos para pasar el identificador de la lista como parámetro al flujo:

1. Defina el parámetro de la plantilla de flujo antes de publicarlo. Así es un parámetro @{parameters('parameter_name')}.
2. Pase el parámetro en la cadena de consulta del iframe src. Por ejemplo, agregue &parameters.listName={the name of the list} si tiene un parámetro denominado listName.

Ejemplo completo

Para mostrar las cuatro plantillas de SharePoint principales en alemán e iniciar al usuario con myCoolList, use este código:

<iframe src="https://make.powerautomate.com/de-de/widgets/templates/?q=sharepoint%20&pagesize=4&destination=details&parameters.listName=myCoolList"></iframe>

Uso de widgets de flujo autenticados

En la tabla siguiente se muestra la lista de Power Automate widgets que admiten la experiencia completa dentro del widget mediante el token de acceso de autenticación de usuario. Debe usar el Kit para desarrolladores de software de JavaScript (SDK de JS) de Power Automate para insertar los widgets y proporcionar el token de acceso de usuario necesario.

Use el SDK de Flow autenticado para permitir a los usuarios crear y administrar flujos directamente desde su sitio web o aplicación (en lugar de navegar a Power Automate). Debe iniciar sesión el usuario con su cuenta Microsoft o Microsoft Entra para usar el SDK autenticado.

Arquitectura de widget

Power Automate widgets funcionan insertando un iframe que hace referencia a Power Automate en una aplicación host. El host proporciona el token de acceso que requiere el widget de Power Automate. el SDK de JS de Power Automate permite que la aplicación host inicialice y administre el ciclo de vida del widget.

Detalles del SDK de JS

El equipo de Power Automate proporciona el SDK de JS para facilitar la integración de widgets de Flow en aplicaciones que no son de Microsoft. El SDK de JS de Flow está disponible como un vínculo público en el servicio Flow y permite que la aplicación host administre eventos del widget e interactúe con la aplicación Flow mediante el envío de acciones al widget. Las acciones y los eventos de widget son específicos del tipo de widget.

Inicialización del widget

Es necesario agregar la referencia del SDK de JS de Flow a la aplicación host antes de inicializar el widget.

<script src="https://flow.microsoft.com/Content/msflowsdk-1.1.js"></script>

Para crear una instancia del SDK de JS, pase los valores opcionales de hostName y locale en un objeto JSON.

var sdk = new MsFlowSdk({
    hostName:'https://make.powerautomate.com',
    locale:'en-US'
}); 

Una vez creada la instancia del SDK de JS, puede inicializar e insertar un widget de Power Automate en un elemento primario de la aplicación host. Para ello, agregue una etiqueta div de HTML:

<div id="flowDiv" class="flowContainer"></div>

A continuación, inicialice el widget de Power Automate con el método JS SDK renderWidget(). Asegúrese de proporcionar el tipo de widget y los valores correspondientes.

var widget = sdk.renderWidget('<widgettype>', {
        container: 'flowDiv',
        flowsSettings: {},
        templatesSettings: {},
        approvalCenterSettings: {},
        widgetStyleSettings: {}
});

Este es un estilo de ejemplo para el contenedor que se puede modificar para hacerlo coincidir con las dimensiones de la aplicación host.

<head>
    <style>
        .flowContainer iframe {
            width: 400px;
            height: 1000px;
            border: none;
            overflow: hidden;
    }
    </style>
</head>

Estos son los parámetros para renderWidget():

Tokens de acceso

Una vez que se ejecuta el SDK renderWidget() de JS, el SDK de JS inicializa un iframe, que apunta a la dirección URL del widget de Power Automate. Esta dirección URL contiene toda la configuración en los parámetros de cadena de consulta. La aplicación host debe obtener un token de acceso de Power Automate para el usuario (Microsoft Entra ID token JWT con audiencia https://service.flow.microsoft.com) antes de inicializar el widget. El widget genera un evento GET_ACCESS_TOKEN para solicitar un token de acceso al host. El host debe controlar el evento y pasar el token al widget:

widget.listen("GET_ACCESS_TOKEN", function(requestParam, widgetDoneCallback) {
    widgetDoneCallback(null, {
        token:  '<accesstokenFromHost>'
    });
});

La aplicación host es responsable de mantener el token y de pasarlo con una fecha de caducidad válida al widget cuando se solicite. Si el widget está abierto durante períodos más largos, el host debe comprobar si el token ha caducado y actualizarlo si es necesario antes de pasarlo al widget.

Requisitos de acceso condicional para widgets incrustados

Si su organización usa directivas de acceso condicional (MFA, Términos de uso o cumplimiento de dispositivos), la aplicación host que inserta el widget de Power Automate debe tener requisitos de acceso condicional coherentes con Power Automate.

Cuando se carga el widget, la aplicación host intercambia su token de autenticación para un token de servicio de Microsoft Flow. Si las directivas de acceso condicional para la aplicación host y Power Automate tienen requisitos diferentes, este intercambio produce un error y el widget muestra un error de autenticación. Las directivas de términos de uso son especialmente problemáticas porque el widget no puede presentar la página de aceptación durante un intercambio silencioso de tokens.

Para evitar este problema:

• Tenga como destino la aplicación de Office 365 o Todas las aplicaciones en la nube en la directiva de acceso condicional para una aplicación coherente.
• Si debe tener como destino aplicaciones individuales, asegúrese de que el servicio Microsoft Flow (id. de aplicación: 7df0a125-d3be-4c96-aa54-591f83ff541c) se incluye junto con la aplicación host con requisitos coincidentes.
• Si la directiva incluye Términos de Uso, excluya las cuentas de servicio y los propietarios de conexiones de flujo: las conexiones actualizan los tokens silenciosamente y no pueden aceptar los Términos de Uso de forma interactiva.

Obtenga más información en Acceso condicional y autenticación multifactor en Power Automate.

Detección de si el widget está listo

Después de una inicialización correcta, el widget genera un evento para notificar que está listo. El host puede escuchar al evento WIDGET_READY y ejecutar cualquier código de host adicional.

widget.listen("WIDGET_READY", function() {
    console.log("The flow widget is now ready.");
    // other host code on widget ready
});

Configuración del widget

FlowsSettings

FlowsSettings se puede usar para personalizar la funcionalidad del widget de Power Automate.

flowsSettings?: {
    createFromBlankTemplateId?: string;
    flowsFilter?: string;sc
    tab?: string;
};

TemplatesSettings

Se aplica a todos los widgets que permiten crear flujos a partir de una plantilla, incluidos Flows, FlowCreation y Templates.

templatesSettings?: {
    defaultParams?: any;
    destination?: string;
    pageSize?: number;
    searchTerm?: string;
    templateCategory?: string;
    useServerSideProvisioning?: boolean;
    enableDietDesigner?: boolean;
};

ApprovalCenterSettings

Se aplica a widgets ApprovalCenter.

approvalCenterSettings?: {
   approvalsFilter?: string;
   tab?: string;but
   showSimpleEmptyPage? boolean;
   hideLink?: boolean
};

Eventos de widget

El widget Power Automate admite eventos que permiten al host escuchar eventos del ciclo de vida del widget. El widget Power Automate admite dos tipos de eventos: eventos de notificación unidireccionales (por ejemplo, Widget_Ready) y eventos generados desde el widget para capturar datos del host (Get_Access_Token). El host debe usar el método widget.listen() para escuchar eventos específicos generados desde el widget.

Uso

widget.listen("<WIDGET_EVENT>", function() {
    console.log("The flow widget raised event");
});

Eventos admitidos por el tipo de widget

Widget de tiempo de ejecución

Widget de creación de flujos

Widget de aprobación

El evento GET_STRINGS permite personalizar el texto de algunos de los elementos de interfaz de usuario que aparecen en el widget. Se pueden personalizar las cadenas siguientes:

Ejemplo

Llamada a widgetDoneCallback pasando un objeto JSON con pares clave-valor de clave de cadena y texto para reemplazar el valor predeterminado.

widget.listen("GET_STRINGS", function(requestParam, widgetDoneCallback) {
    widgetDoneCallback(null, {
         "FLOW_CREATION_HEADER": "<string override would go here>",
        "INVOKE_FLOW_RUN_FLOW_BUTTON":  "<string override would go here>"
    });
});

Acciones de widget

El host usa las acciones de widget para enviar un mensaje o una acción específica al widget. El SDK de JS del widget proporciona el método notify() para enviar un mensaje o una carga JSON al widget. Cada acción de widget admite una firma de carga específica.

Uso

widget.notify('<WIDGET_ACTION>', parameterMatchingParameterInterface)
    .then(result => console.log(result))
    .catch(error => console.log(error))

Ejemplo

Invocación de un flujo de nube mediante el envío del comando siguiente a un widget de tiempo de ejecución.

widget.notify('triggerFlow', { flowName: flowName, implicitData:implicitData });  

Widget de tiempo de ejecución

Widget de creación de flujos

Widget de aprobación

Configuración de la aplicación cliente

Debe configurar la aplicación cliente con ámbitos de servicio de flujo (permisos delegados). Si la aplicación Microsoft Entra (Microsoft Entra ID) que se usa para la integración del widget usa un flujo de autorización de "concesión de código", la aplicación Microsoft Entra debe estar preconfigurada con permisos delegados compatibles con Power Automate. Esto proporciona permisos delegados que permiten a la aplicación:

• Administrar aprobaciones
• Revisar aprobaciones
• Leer actividades
• Administrar flujos
• Leer flujos

Siga estos pasos para seleccionar uno o varios permisos delegados:

1. Ir a https://portal.azure.com
2. Seleccione Microsoft Entra ID.
3. Seleccione App registrations en Administrar.
4. Escriba la aplicación que no es de Microsoft que se va a configurar para los ámbitos de servicio de Flow.
5. Seleccione Configuración. ! [Captura de pantalla en la que se localiza el icono de configuración de la aplicación.(.. /media/embed-flow-dev/Microsoft Entra ID-App-Settings.png)
6. Seleccione Permisos necesarios en Acceso de API/
7. Seleccione Agregar.
8. Elija Seleccionar una API. 
9. Busque el servicio Power Automate y selecciónalo. Nota: Antes de ver el servicio Power Automate, tu inquilino debe tener al menos un usuario de Microsoft Entra que esté iniciado sesión en el portal de Flow (https://make.powerautomate.com).
10. Elija los ámbitos de Flow necesarios para la aplicación y después haga clic en Guardar. ! [Captura de pantalla que muestra los permisos delegados.](.. /media/embed-flow-dev/Microsoft Entra ID-App-DelegatedPermissions.png)

La aplicación ahora obtiene un token del servicio de Flow que contiene permisos delegados en la reclamación "scp" del token JWT.

Aplicación de ejemplo en la que se insertan widgets de Flow

Se proporciona un ejemplo de aplicación de página única (SPA) de JavaScript en la sección de recursos para que pueda experimentar con la inserción de widgets de Flow en una página de host. El uso de la aplicación de ejemplo requiere registrar una aplicación de Microsoft Entra con el flujo de concesión implícito habilitado.

Registro de una aplicación de Microsoft Entra

1. Inicie sesión en el portal Azure.
2. En el panel de navegación izquierdo, seleccione Microsoft Entra y seleccione App registrations (versión preliminar) > Nuevo registro.
3. Cuando aparezca la página Registrar una aplicación, escriba un nombre para la aplicación.
4. En Tipos de cuenta compatibles, seleccione Cuentas en cualquier directorio organizativo.
5. En la sección URL de redireccionamiento, seleccione la plataforma web y establezca el valor en la dirección URL de la aplicación en función del servidor web. Establezca este valor en http://localhost:30662/ para ejecutar la aplicación de ejemplo.
6. Seleccione Registrar.
7. En la página Información general de la aplicación, anote el valor de identificador (cliente) de la aplicación.
8. En el ejemplo es necesario habilitar el flujo de concesión implícito. En el panel de navegación de la izquierda de la aplicación registrada, haga clic en Autenticación.
9. En Configuración avanzada, en Concesión implícita, active las casillas Tokens de id. y Tokens de acceso. Los tokens de id. y los de acceso son necesarios, ya que en esta aplicación se debe iniciar la sesión de los usuarios y llamar a la API de Flow.
10. Haga clic en Guardar.

Ejecución del ejemplo

1. Descargue el ejemplo y cópielo en una carpeta local del dispositivo.
2. Abra el archivo index.html de la carpeta FlowSDKSample y modifique applicationConfig para actualizar el valor clientID con el identificador de aplicación que ha registrado antes.
3. La aplicación de ejemplo está configurada para usar los ámbitos Flow.Read.All y Flow.Manage.All. Puede configurar más ámbitos actualizando la propiedad flowScopes en el objeto applicationConfig .
4. Ejecute estos comandos para instalar la dependencia y ejecutar la aplicación de ejemplo:

   > npm install > node server.js

5. Abra el explorador y, después, escriba http://localhost:30662
6. Seleccione el botón Sign in para autenticarse en Microsoft Entra y adquirir un token de acceso de flujo de nube.
7. El cuadro de texto Token de acceso contiene el token de acceso.
8. Seleccione Cargar widget de flujos o Cargar widget de plantillas para insertar los widgets correspondientes.

Recursos

Los siguientes recursos incluyen páginas de prueba de widgets y locales de widgets admitidos.

Páginas de prueba de widgets

Obtenga más información sobre la configuración y la integración de widgets:

• Widget de plantillas: <https://make.powerautomate.com/test/templateswidget/>
• Widget FlowCreation: <https://make.powerautomate.com/test/flowcreationwidget/>
• Widget de tiempo de ejecución: <https://make.powerautomate.com/test/runtimewidget/>
• Widget de centro de aprobaciones: <https://make.powerautomate.com/test/approvalcenterwidget/>
• Widget de flujos: <https://make.powerautomate.com/test/managewidget/>

Configuraciones regionales de widget admitidas

Si la configuración regional inicializada no aparece, Flow tiene como valor predeterminado la configuración regional admitida más cercana.

El uso del SDK de inserción de Power Automate se trata en los términos de licencia de software de Microsoft.