Trabajar en flujos de escritorio con código

Artículo
02/19/2024

Los desarrolladores pueden agregar la funcionalidad de flujos de escritorio a sus aplicaciones, incluida la activación y cancelación programática de flujos de escritorio. Estas capacidades se ofrecen como parte de la plataforma Microsoft Dataverse.

Requisitos previos

Conocimiento de API web Dataverse, autenticación con Dataverse y el uso de OAuth con Dataverse.
Conocimiento del entorno de Dataverse, nociones de organización y cómo recuperar la URL de organización manualmente o programáticamente.
Conocimiento de nociones de flujos de escritorio y de lo que son las conexiones y cómo crearlas..

Importante

En este artículo, debe reemplazar todos los corchetes [...] en las URL y los datos de entrada/salida con valores específicos para su escenario.

Lista de flujos de escritorio disponibles

Todos los scripts de flujos de escritorio están en Dataverse como parte de la entidad de flujo de trabajo.

Filtre la lista de flujos de trabajo según la categoría para identificar los flujos de escritorio.

Solicitud para obtener flujos de escritorio

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/workflows?$filter=category+eq+6&$select=name,workflowid&$orderby=name HTTP/1.1

Respuesta a la solicitud para obtener flujos de escritorio

{
    "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#workflows(name,workflowid)",
    "value": [
        {
            "@odata.etag": "W1069462",
            "name": "Desktop flow 1",
            "workflowid": "f091ffab-58bb-4630-a115-659453d56f59",
        },
        {
            "@odata.etag": "W1028555",
            "name": "Desktop flow 2",
            "workflowid": "eafba1a2-e8d4-4efa-b549-11d4dfd9a3d1",
        }
    ]
}

Obtenga el esquema para los flujos de escritorio

Si necesita recuperar el esquema de flujo para entradas o salidas, puede usar el campo clientData para el flujo de trabajo de destino.

Solicitar el esquema de entradas para los flujos de escritorio

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/workflows([Workflow Id])/inputs/$value HTTP/1.1

Respuesta a la solicitud para obtener el esquema de entradas de flujos de escritorio

{
    "schema": {
        "properties": {
            "inputText": {
                "default": "",
                "description": "",
                "format": null,
                "title": "inputText",
                "type": "string",
                "value": ""
            },
            "inputInteger": {
                "default": "",
                "description": "",
                "format": null,
                "title": "inputInteger",
                "type": "number",
                "value": "0"
            }
        },
        "type": "object"
    }
}

Solicitar el esquema de salidas para los flujos de escritorio

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/workflows([Workflow Id])/outputs/$value HTTP/1.1

Respuesta a la solicitud para obtener el esquema de salidas de flujos de escritorio

{
    "schema": {
        "properties": {
            "outputText": {
                "default": "",
                "description": "",
                "format": null,
                "title": "outputText",
                "type": "string",
                "value": null
            },
            "outputInteger": {
                "default": "",
                "description": "",
                "format": null,
                "title": "outputInteger",
                "type": "number",
                "value": null
            }
        },
        "type": "object"
    }
}

Obtener el estado de una ejecución de flujo de escritorio

Dataverse todas las ejecuciones de flujo de escritorio en la entidad de sesión de flujo.

Solicitar el estado de una ejecución de flujo de escritorio

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/flowsessions([Flow session ID])?$select=statuscode,statecode,startedon,completedon HTTP/1.1

Respuesta para el estado de una ejecución de flujo de escritorio

{
    "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#flowsessions(statuscode,statecode,startedon,completedon)/$entity",
    "@odata.etag": "W1276122",
    "statuscode": 8,
    "statecode": 0,
    "startedon": "2022-06-16T12:54:40Z",
    "completedon": "2022-06-16T12:57:46Z",
}

Obtener salidas de flujo de escritorio

Si el flujo de escritorio tiene salidas, puede consultar el campo de salidas para recuperarlas.

Solicitar las salidas de flujos de escritorio

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/flowsessions([Flow session ID])/outputs/$value HTTP/1.1

Respuesta a la solicitud de salidas de flujos de escritorio

{
    "Output1": "My output value"
}

Desencadenar una ejecución de flujo de escritorio

Al usar Dataverse, puede agregar la funcionalidad de activar un flujo de escritorio a través de su aplicación. Para implementar esta funcionalidad, necesita usar la acción RunDesktopFlow.

Para llamar a la acción, necesitará la siguiente información.

El ID del flujo de escritorio que desea ejecutar. Puede obtener este ID a través de la API, como se explica en la sección Lista de flujos de escritorio disponibles, anteriormente en este artículo.

Propina

Como alternativa, puede recuperar la ID manualmente desde la URL de detalles del flujo de escritorio en Power Automate. El formato de URL es: https://make.powerautomate.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

Para obtener más información, consulte Administrar flujos de escritorio.
El name de la conexión de flujo de escritorio (máquina/grupo de máquinas de destino) que se usará para ejecutar su flujo. El nombre se puede recuperar en la URL de la misma página de conexión en Power Automate. El formato de URL es:
https://make.powerautomate.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

Nota

Para más información, consulte Crear conexiones de flujo de escritorio.

Propina

Como alternativa, puede utilizar el nombre lógico de una referencia de conexión como entrada de la conexión en lugar del nombre de la conexión (ejemplo de uso que se describe a continuación). Las referencias de conexión se almacenan en la tabla de Dataverse de referencia de conexión y se pueden enumerar programáticamente de la misma manera que los flujos de escritorio detallados en la sección Lista de flujos de escritorio disponibles.

Para más información, consulte Usar una referencia de conexión en una solución y tabla de referencia de conexión/referencia de entidad.

Solicitud para desencadenar un flujo de escritorio

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

POST https://[Organization URI]/api/data/v9.2/workflows([Workflow ID])/Microsoft.Dynamics.CRM.RunDesktopFlow HTTP/1.1  
{
    "runMode": "attended",
    "runPriority": "normal",
    "connectionName": "[Connection Name]",
    "timeout": 7200,
    "inputs": "{\"Input1\":\"Value\", \"Input2\":\"Value\"}"
}

Solicitud para desencadenar un flujo de escritorio con una referencia de conexión

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

POST https://[Organization URI]/api/data/v9.2/workflows([Workflow ID])/Microsoft.Dynamics.CRM.RunDesktopFlow HTTP/1.1  
{
    "runMode": "attended",
    "runPriority": "normal",
    "connectionName": "[Connection Reference Logical Name]",
    "connectionType": 2,
    "timeout": 7200,
    "inputs": "{\"Input1\":\"Value\", \"Input2\":\"Value\"}"
}

Respuesta a la solicitud para desencadenar un flujo de escritorio

{
    "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.RunDesktopFlowResponse",
    "flowsessionId": "d9687093-d0c0-ec11-983e-0022480b428a"
}

Las entradas del script se pueden ver en la página de detalles de la ejecución en el portal Power Automate (en versión preliminar).

Advertencia

Al utilizar la API, existen algunas limitaciones que debe tener en cuenta:

La activación de una ejecución de flujo de escritorio con una cuenta que tenga privilegios de "Usuario" funcionará. Sin embargo, cancelar la ejecución y consultar el estado requiere privilegios de "Propietario".
La suplantación de Dataverse no es compatible.
El tamaño del contenido del campo de entrada está limitado a 2 MB.

Recibir notificación sobre la finalización del script

Un parámetro opcional "callbackUrl" está disponible en el cuerpo de la acción RunDesktopFlow. Puede usarlo si desea que se le notifique la finalización de su script. Se enviará una solicitud POST a la URL proporcionada cuando se complete el script.

Solicitud recibida por la devolución de llamada punto de conexión

User-Agent: EnterpriseConnectors/1.0
Content-type: application/json; charset=utf-8
x-ms-workflow-id: [Workflow ID]
x-ms-run-id: [Flow session ID]

POST [yourCallbackURL]

{
    "statuscode": 4,
    "statecode": 0,
    "startedon": "2022-09-05T08:04:11Z",
    "completedon": "2022-09-05T08:04:41Z",
    "flowsessionid": "d9687093-d0c0-ec11-983e-0022480b428a"
}

Si no se proporciona ningún parámetro de URL de devolución de llamada, el estado de la sesión de flujo se debe sondear desde Dataverse (se refiere a Obtener el estado de una ejecución de flujo de escritorio).

Nota

Todavía puede usar el sondeo de estado como un mecanismo alternativo incluso si proporciona un parámetro de URL de devolución de llamada.
Su operación de devolución de llamada punto de conexión debe ser idempotente.
La solicitud POST se volverá a intentar tres veces con un intervalo de un segundo si su punto de conexión responde con una respuesta de Error del servidor (código 500 y superior) o una respuesta de "Tiempo de espera de solicitud" (código 408).

Requisitos para el parámetro de URL de devolución de llamada

El servidor debe tener la versión actual de TLS y conjuntos de cifrado.
Solo se permite el protocolo HTTPS.
El acceso a localhost (bucle invertido) no está permitido.
Las direcciones IP no se pueden usar. Debe usar una dirección web con nombre que requiera resolución de nombres DNS.
Su servidor debe permitir las conexiones desde los valores de dirección IP de los servicios de Power Platform Dynamics 365 especificados en la etiqueta de servicio de AzureCloud.

Propina

Como la devolución de llamada no está autenticada, se deben tomar algunas precauciones

Compruebe la validez del Id. de la sesión de flujo cuando se reciba la notificación de devolución de llamada. Dataverse es la fuente de la verdad.
Implemente una estrategia de límite de tasa en su lado del servidor.
Intente limitar el uso compartido de URL de devolución de llamada entre varias organizaciones.

Cancelar una ejecución de flujo de escritorio

Similar a lo que sucede con la funcionalidad Desencadenador, también puede cancelar un flujo de escritorio en cola o en ejecución. Para cancelar un flujo de escritorio, utilice la acción CancelDesktopFlowRun.

Solicitud para cancelar una ejecución de flujo de escritorio

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

POST https://[Organization URI]/api/data/v9.2/flowsessions(d9687093-d0c0-ec11-983e-0022480b428a)/Microsoft.Dynamics.CRM.CancelDesktopFlowRun HTTP/1.1

Responder a la solicitud para cancelar un flujo de escritorio

HTTP/1.1 204 No Content

Errores

Cuando ocurre un error, la respuesta tiene un formato diferente que coincide con los mensajes de error de Dataverse. El código de error http y el mensaje deben proporcionar suficiente información como para comprender el problema.

HTTP/1.1 403 Forbidden

{
    "error": {
        "code": "0x80040220",
        "message": " Principal user (Id=526..., type=8) is missing prvReadworkflow privilege (Id=88...*)”
    }
}

Limitaciones conocidas

Actualmente admitimos hasta 70 ejecuciones de flujos de escritorio por minuto para cada conexión.