Logo
  1. Potens.io
  2. Magnus
  3. Remote Execution

Articles > Remote Workflow Execution v2

  • Remote API
  • Remote Workflow Execution
  • Remote Execution - Quick Start
  • Remote Workflow Execution v2
  • Get Workflow History
  • Lock / Unlock Workflows Remotely

Overview

Remote Workflow Execution v2 is an enhancement of version v1.  
Just like v1, users can execute Magnus Workflows remotely and asynchronously via HTTP. 
Requests made to Remote Workflow Execution v2 are queued and processed by the Fair Scheduler.  
Through v2, users can execute multiple instances of the same Workflow.  

v2 is also integrated into Magnus Workflows in such a way that users can asynchronously execute a Workflow via an API Task.

Here is a feature comparison between v1 and v2:

Feature v2 v1
Running a Workflow via direct HTTP request Yes Yes
Running a Workflow via an API Task Yes Yes
Running multiple instances of the same Workflow Yes, when queue attribute is set to true No

Here are the two ways to invoke Remote Workflow Execution v2 explicitly:

  1. Via direct HTTP request
  2. Via an API Task within a Workflow

Request

HTTP Request

POST https://[applicationURL]]/remote

Request Body

The maximum request size limit is 32 MB.  Exceeding this limit will cause invalid error.

{
    "jwt": string,
    "c":"713aa58d",
    "configuration": {
        "runWorkflow": {
            "l": string,
            "queue": boolean,
            "parameters": [
                {
                    "name": string,
                    "value": string or number or boolean
                }
            ],
            "billingProject": string,
            "cascadeBillingProject": boolean
        }
    }
}

 
Property name Value Description
jwt string [Required for direct HTTP request] JWT created using the Google service account that has been registered with Magnus
c 713aa58d [Required] Command for workflow run
configuration nested object [Required] Configuration of the request
configuration.runWorkflow nested object [Required] Run a workflow asynchronously
configuration.runWorkflow.l string [Required] Encoded workflow ID
User can obtain the encoded workflow ID from the permalink of the workflow:
01.png
02.png
configuration.runWorkflow.queue  boolean

[Optional] Specifies whether to queue this workflow execution or not.
Supported values: 

  • true: this request is queued and processed by the Fair Scheduler.  Multiple instances of the same Workflow is allowed to run. Workflow state is not saved after execution
  • false: this request is not queued, and only one instance of the Workflow is allowed to run.

The default value is false.

configuration.runWorkflow.parameters[] list

[Optional] The parameter overrides.
The overrides are passed to the workflow during execution.  Only Custom Parameters that are not owned by the workflow can be overridden.
For example:
03.png

The parameter var_myParameter2 can be overridden.  But the parameter var_myParameter1 cannot be overridden since it is owned by the workflow.

configuration.runWorkflow.parameters[].name string [Required] The parameter name.  It is case-sensitive; user must provide the parameter name as it appears in the Workflow Editor.
configuration.runWorkflow.parameters[].value string [Required] The parameter value.  NULL is treated as empty string.  
configuration.runWorkflow.billingProject string [Optional] The billing project to execute the workflow in.  If not specified, the default billing project setting from the workflow will be applied.
configuration.runWorkflow.cascadeBillingProject boolean

[Optional] Specifies whether to cascade the billing project to child and descendent workflows.  If set to true, during workflow execution, the running billing project ID will be passed down to child and descendent workflows. During the execution of the descendent workflows, the cascaded billing project will be used. This applies for descendent workflows that are executed via Execute Workflow Task or Remote Workflow Execution. The user who is running the workflows must have required permission in the cascaded billing project.

The default value is false.


Response

If the workflow has started successfully, the following response body will be returned:

{
    "status":"ok",
     "result": {
         "workflowId":"<workflowId>",
        "historyId":"<historyId>"
     }
}

User can then check the progress of the workflow execution in Magnus History Browser.  The historyId of the workflow execution can be accessed by the following steps in History Browser:

  1. Click Workflows History
  2. Click on the Details icon 05.png
  3. Click on the status icon on the bottom:
    06.png  
  4. The historyId is revealed:
    07.png 

If the workflow has failed to start, this response body will be returned:

{
    "status":"failed",
    "error":{
        "reason":"<reason>",
        "message":"<message>"
    }
}

Please see the Errors section for the list of error.

Workflow Execution Permission

The user must be owner or delegate of the Workflow.

If invoking via direct HTTP request, the Google service account must be the owner or delegate of the target workflow.  If invoking via an API Task within a parent Workflow, the run user must be the owner or delegate of the target Workflow.

Quota

A user cannot have more than 100 Remote Workflow Execution v2 requests waiting in the queue.  That is, if a user has already sent 100 Remote Workflow Executions with queue set to true, and at the moment these requests are waiting in the queue and have not been executed yet.  Any more requests with queue set to true from the same user will be rejected with an error code of 429 until one or more of the waiting request has been processed from the queue. 

Errors

Error reason HTTP code Description
invalid 400

This error is returned when:

  1. the input JWT is invalid
  2. the Google service account is not registered with Magnus
  3. the input encoded workflow ID is invalid
  4. the input command is invalid
  5. another instance of the workflow is already running
  6. the parameter override provided is invalid
notFound 404 This error is returned when the workflow is not found
accessDenied 403 This error is returned when the Google service account does not have permission to execute the workflow
backendError 500 This error is returned when there is backend error in Magnus
Potens.io
Launch Magnus | Goliath