Actions

As actions are the core building block for most concepts in the Globus automation services, action invocation takes on a central role in the definition of flows. Actions are invoked from a flow using the state type Action. We describe the structure of an Action state via the following example which is described in detail below:

{
  "Type": "Action",
  "ActionUrl": "<URL to the action, as defined above for various actions>",
  "InputPath": "$.Path.To.Action.Body",
  "Parameters": {
    "constant_val": 10,
    "reference_value.$": "$.Path.To.Value",
    "expression_value.=": "'Constant string ' + Path.To.SuffixString",
    "nested_value": {
      "child_const_val": true,
      "child_ref_val.$": "$.Child.Val.Path"
    },
    "secret_value": "MyPassword",
    "__Private_Parameters": [
      "secret_value"
    ]
  },
  "ResultPath": "$.ActionOutput",
  "WaitTime": 3600,
  "ExceptionOnActionFailure": true,
  "RunAs": "User",
  "Catch": [
    {
      "ErrorEquals": [
        "ActionUnableToRun"
      ],
      "Next": "RunFailureHandler"
    },
    {
      "ErrorEquals": [
        "ActionFailedException"
      ],
      "Next": "ActionFailureHandler"
    }
  ],
  "Next": "FollowingState",
  "ActionScope": "<Scope String for the action, as defined above for various actions>",
  "End": true
}

The properties on the Action state are defined as follows. In some cases, we provide additional discussion of topics raised by specific properties in further sections below this enumeration.

Type (required): As with other States defined by the States Language, the Type indicates the type of this state. The value Action indicates that this state represents an action invocation.
ActionUrl (required): The base URL of the action. As defined by the Action Interface, this URL has methods such as /run, /status, /cancel and so on defined to manage the life-cycle of an action. The Action flow state manages the life-cycle of the invoked action using these methods and assumes that the specific operations are appended to the base URL defined in this property. For Globus operated actions, the base URLs are as defined previously in this document.
InputPath or Parameters (mutually exclusive options, at least one is required): Either InputPath or Parameters can be used to identify or form the input to the action to be run as passed in the body of the call to the action /run operation.
- Parameters: The Parameters property is defined as an object that becomes the input to the action. As such, it becomes relatively plain in the Action state definition that the structure of the Parameters object matches the structure of the body of the input to the action being invoked. Some fields in the Parameters object can be protected from introspection later so that secret or sensitive information, such as credentials, can be encoded in the parameter values without allowing visibility outside the flow, including by those running the Flow. The private parameter functionality is described in Protecting Secrets. Values in Parameters can be specified in a variety of ways:
  - Constants: Simply specify a value which will always be passed for that property. Constants can be any type: numeric, string, boolean or other objects should an action body specify sub-objects as part of their input. When an object is used, each of the properties within the object can also be any of the types enumerated here.
  - References: Copies values from the state of the flow to the name given. The name must end with the sequence .$ to indicate that a reference is desired, and the string-type value must be a Json Path starting with the characters $. indicating the location in the flow run-time state that values should be retrieved from.
  - Expressions: Allow values to be computed as a combination of constants and references to other state in the flow’s run-time. This provides a powerful mechanism for deriving parameter values and is defined more fully in Expressions.
- InputPath: Specifies a path within the existing state of the flow here the values to be passed will be present. Thus, use of InputPath requires that the proper input be formed in the flow state.
ResultPath: Is a Reference Path indicating where the output of the action will be placed in the state of the flow run-time. The entire output returned from the action will be returned including the action_id, the final status of the action, the start_time and completion_time and, importantly, the details containing the action-specific result values. If ResultPath is not explicitly provided, the default value of simply $, indicating the root of the flow state, is assumed and thus the result of the action will become the entire flow state following the Action state’s execution. Typically, this is not the desired behavior, so a ResultPath should almost always be included.
WaitTime (optional, default value 300): The maximum amount time to wait for the action to complete in seconds. Upon execution, the flow will monitor the execution of the action for the specified amount of time, and if it does not complete by this time it will abort the action. See Action Execution Monitoring for additional information on this. The default value is 300 or Five Minutes.
ExceptionOnActionFailure (optional, default value true): When an action is executed but is unable to complete successfully, it returns a status value of FAILED. It is commonly useful to treat this "Action Failed" occurrence as an Exception in the execution of the flow. Setting this property to true will cause a ActionFailedException run-time exception to be raised which can be managed with a Catch statement (as shown in the example). Further details on discussion of the Catch property of the action state and in the Handling Exceptions section. If the value is false, the status of the action, including the value of FAILED for the status value will be placed into the flow state as referenced by ResultPath.
RunAs (optional, default value User): When the flow executes the action, it will, by default, execute the action using the identity of the user invoking the flow. Thus, from the perspective of the action, it is the user who invoked the flow who is also invoking the action, and thus the action will make authorization decisions based on the identity of the User invoking the flow. In some circumstances, it will be beneficial for the action to be invoked as if from a user identity other than the user who invoked the flow. See Performing Actions as Different Users for additional information and a discussion of use cases for providing different RunAs values.
Catch: When actions end abnormally, an Exception is raised. A Catch property defines how the Exception should be handled by identifying the Exception name in the ErrorEquals property and identifying a Next state to transition to when the Exception occurs. If no Catch can handle an exception, the flow execution will abort on the Exception. A variety of exception types are defined and are enumerated in Handling Exceptions.
ActionScope (optional): The scope string to be used when authenticating to access the action. In most cases, this values is unneeded because the required scope can be determined by querying the action provider using the provided ActionUrl. If you are using a non-standard compliant action which does not publish its scope, this can be provided to avoid attempting to query the non-compliant action provider.
Next or End (mutually exclusive, one required): These indicate how the flow should proceed after the action state. Next indicates the name of the following state of the flow, and End with a value true indicates that the flow is complete after this state completes.

Action Execution Monitoring

Action states will block until the executed action reaches a completion state with status value either SUCCEEDED or FAILED or when the WaitTime duration is reached. Within this time, the flow will periodically poll the action to determine if it has reached a completion state. The interval between polls doubles after each poll ("exponential back-off") up to a maximum interval between polls of 10 minutes. Thus, detection of the completion will not be instantaneous compared to when the action "actually" completes and may be delayed up to the maximum poll interval of 10 minutes.

It is important to remember that this delay between an action’s actual completion and it being detected by the Flow service can occur. A user running a flow may observe or receive another form of notification(such as an email from Globus Transfer) that an action has completed prior to the Flows service polling to discover the same progress has occurred. This is an inherent property of the system.