2 Author Workflows
A workflow defines a series of tasks or activities that can be automated using Oracle Orchestration. A workflow may consist of one or more steps and may use multiple workers or call upon other workflows to complete its tasks.
To learn more about workflows, how they are structured and how they work; see About Workflows.
Note:
This book has two versions of workflow syntax: V1.0 and V2.0. Currently V1.0 is only included in this document for remediation action support. Oracle Orchestration requires the use of V2.0 syntax and definitions going forward for all workflows authored.About Workflows
Depending on the complexity of the activity, a workflow may consist of one or more steps. The general execution model for workflows combines parallel and serial actions to allow for any level of serial/parallel actions to be combined.
Some Important Terms
Before looking at how workflows are structured, you need to understand some workflow-related terms and concepts.
- Workflow : Defines a set of orchestrated tasks or activities that can be automated using Oracle Orchestration, being executed by one or more workers.
- Workflow Name: This name is an identifier you can use to search for a workflow submission for status and results. All workflows in Orchestration must have a unique name.
- Workflow Library: A persistent storage area where you can store and retrieve workflows. Workflows can have one or more versions associated with them, and can also be in a published or draft state. Workflow Library supports the complete life cycle management of workflows enabling the users to reuse the workflows by publishing and managing these workflows. Workflows can be updated and published as a newer version; only the latest version will be active, meaning there can only be one active version of a workflow. Workflows are accessed via the Workflow Library UI .
- Workflow Submission: An immediate or scheduled execution of a specific workflow.
- Workflow Submission Name: Users can provide a custom name for the workflow submission, helping identify it. The workflow submission name is not the name of the workflow itself and does not need to be unique.
Example: Run the Patch DBCS workflow
- Workflow Declaration: The workflow declaration contains the code that defines the workflow’s logical execution. Defining them as input and output definitions, including their validation rules., with appropriate properties, which can then be referenced within the plan section using UEL expressions.
- Plan : Describes all the steps and the input for a workflow. Supports the user, abstracting out the run time context of a workflow.
- Step: Defines an individual unit of activity (step) that executes as part of the workflow execution. Example steps types include ENTITY, REST and WAIT.
- Operation Stage: Defines the main action of the step.
- PRE, POST, OPERATION, PUBLISH: Optional stages defined as part of the Step Execution Flow.
Workflow Structure
Figure 2-1 Orchestration Workflow Structure
Workflow Execution
Workflows executions combine parallel and serial actions to allow for any level of serial/parallel step action. Additionally, workflow steps may reference other workflows, which lets you componentize or modularize workflows; and for a workflow administrator to assemble complex activities from smaller well-defined workflow building blocks.
Workflow Characteristics and Behaviors
- A workflow may instantiate one or more workflow workers. The number of workflow workers defines the level of parallelism for the entire workflow.
- Each workflow worker runs its own instance of the workflow in parallel. There is no "crosstalk" or synchronization of data between workflow worker instances.
- Each workflow may have one or more steps.
- Each step runs in serial with every other step in the same workflow plan.
- Each step may have one or more step workers (like a workflow).
- Each step worker runs its own instance of the step in parallel. There is no crosstalk or synchronization of data between other step instances.
- Steps may combine the results of all completed steps per step worker into one single result.
- Workflows may combine the results of all completed workflows into one single result.
- Workflows may publish the results of the entire workflow (this is critical for embedded workflows, the result of a workflow publish is synonymous with the results of a published step).
Author Workflows Using UI
A workflow defines tasks or activities that can be automated using Oracle Orchestration.
- Navigate to the Workflow Library on the left hand hamburger menu. The main Workflow Library screen will appear.
- Click on the plus "+" sign on the left hand corner. A new screen will appear with the workflow editor.
- Select a unique name for your workflow and enter a brief description of what your workflow does. Once done, click Next
- In the JSON definition screen, enter your workflow code in JSON format.
- Once completed you can save the workflow as either Draft or Publish. To submit or run a published workflow please view Manage Orchestration Workflows.
Note:
It is recommended that you author workflows using the V2.0 syntax. V1.0 syntax is currently deprecated and only noted for legacy purposes. V1.0 workflows cannot be created using the UI interphase.Author Workflows Using V2.0 Syntax
A workflow is the fundamental building block for a business activity that can be automated using Orchestration. Workflows allow you to automate tasks and activities; in this topic we will show you the main elements of a workflow, how a workflow is structured and JSON code examples. Providing you with the ability to:
- Define multiple steps within a single workflow plan. See: Example 8: Two Step Workflow Execute and Validate REST Calls
- Increase workflow re-usability, allowing the use of input variables. See: Example 6: Single Step REST Call with Variable Inputs
- Allow the workflow to reference variables via Workflow Variables and Data Passing.
- Chain and nest workflows, users can call another workflow from within a step execution.
V2.0 Workflow Elements
- Workflow Name: A name given to the workflow. This name is a unique identifier of the workflow in the library.
- Plan: A plan is a list of steps where each step is a task that needs to be performed on an ENTITY. A plan can also contain an input declaration to define workflow inputs.
Input Declaration: Allows the workflow author to define the workflow inputs to be referenced within the workflow through parametrization. The workflow author can also, specify the input types like string, integer and boolean. Input types can also be marked as required based on the author's needs.
Types of Steps:
- REST: Used for REST URI workflows. This step type has 3 parameters:
- URI, the REST URI to use, this is a required parameter.
- Method, either GET or POST, this is a required parameter.
- Headers are a map of key/value pairs, this is an optional parameter.
- ENTITY: A type of step that executes actions within a discovered entity. Its parameters have the following properties:
- Credential: Credentials are required to authenticate against the entity where the command will be executed. You will need to reference the name of the credential created in the agent credential store associated with the entity.
- Command: To be executed on agent.
- Arguments: Inputs to be sent to the command. Multiple inputs can be sent as comma separated values.
- stdin : Input sent to the command via standard input.
- Entity: where the command needs to be run. An agent monitored host or database.
- stdout: standard output from the command execution.
- commandTimeout is used when a custom timeout in an entity workflow is needed to terminate a step. Time is expressed in left-to-right granularity h: hours, m: minutes and s: seconds; valid examples: 5m, 1h 10m, 30s. Timeouts cannot exceed 24 hours in length, must not have negative components, or spaces between number and unit.
- WAIT: A wait type allows a user intended delay in the execution flow with the command.
- waitInSeconds. Minimum wait time of 5 seconds and maximum wait time of 1800 seconds can be entered (decimals are not allowed).
- WORKFLOW: A workflow type allows workflows to be nested in a parent-child manner. A nested workflow needs the following design specifications:
- name: Name of the nested workflow (different from parent name).
- workflowName: Name of the workflow to be called in the Workflow Library
- workflowVersion: Version of the workflow in the Workflow Library. This parameter is optional.
- input: Input to be sent to the nested workflow. This input is needed when variables from the parent workflow need to be passed to the child workflow. Input variables entered here will be overridden by variables defined in the Workflow Library.
Step Components:
- PRE: Prerequisites that need to be completed or guaranteed for the step to start execution. Supported commands:
- Skip, if the prerequisites are not met a step can be skipped.
- POST: Validates step condition, by verifying if the step successfully did what it was intended to do. Supported Commands:
- Retry retries the step until successful execution.
- Abort aborts the step if the post condition is not met.
- Skip skips the step entirely if the step conditions are not met.
- OPERATION: Actions to be performed by the step. This is based on the step type defined (REST, ENTITY, WAIT or WORKFLOW).
- PUBLISH: Information to be passed on to the subsequent steps to use via variables.
- REST: Used for REST URI workflows. This step type has 3 parameters:
- Input: The input section allows the author to specify any default inputs to the workflow corresponding with the workflow input declaration. User inputs provided during workflow submission will be automatically passed upon workflow submission. Input may contain two elements:
- vars: Is a JSON object for defining variables, whose keys will be made available as global variables for the workflow.
- workerVars: Is a JSON object, the number of workers and their names are defined by the keys. Every key must have a value. workerVars has the same structure as vars defining local worker variables. The values defined in workerVars override the values defined in the global vars object for any key that shares the same name. An empty object must be provided if there are no intended overrides.
- Workers: Each workflow worker runs its own instance of the workflow in parallel. There is no "crosstalk" or synchronization of data between workflow worker instances. For a sample worker workflow please view: Example 7: Single Step REST call with Workers
- Notification:A list of email addresses that will receive workflow status updates.
Author Workflows Using V1.0 Syntax
A workflow is the fundamental building block for a business activity that can be automated using Orchestration it allows you to automate tasks and activities.
Note:
Currently V1.0 syntax is only included in this book for remediation action support. Oracle requires using V2.0 syntax and definitions going forward for all workflows authored. Version 1.0 is not supported via the UI.The following is the standard V1.0 JSON structural format to define a workflow:
name
workflow
plan
name
steps
step
step payload
uploadToLA
logSource
input
workflow workers (multiple workers are supported)
workflowProperties
property 1
property 2
...
property n
schedule
notificationTable 2-1 Workflow Elements
| Element | Description |
|---|---|
| Name | A name given to the workflow submission. The name is an identifier you can use to search for a workflow submission for status and results.
Note: The workflow submission name does not have to be unique within a given tenant scope. |
| Plan |
A list of steps where each step is a task that needs to be performed on an entity or a REST call.
When defining a step, you can also specify that workflow details be sent to Oracle Log Analytics by setting the uploadToLA property to true. Additionally, you can have the uploaded logs associated with an existing log source known to Log Analytics by setting the logSource property. |
| Workflow Properties |
A map of key-value pairs that can be associated with the workflow submission. These key-value pairs let you associate keywords that will help in searching for the workflow submission at some later point in time.
Note: You can specify up to five tags using the names property1, property2, property3, property4, and property5. |
| Input | The input for the workflow. Input may consist of vars and workerVars. |
| Workers |
Workers define the level of parallelism for the entire workflow: Consider a use case (ENTITY) where a set of steps needs to be executed across 10 different hosts. Similarly, consider a use case (REST) where a REST call needs to be made to 10 different endpoints. For both cases, the same set of steps needs to be executed with different host names/port numbers. Each execution is a worker. All steps specified in the plan (for the current release, only one step is permitted) would be executed for each worker using the specified input values. |
| Schedule |
The time when a workflow should be executed. For example, say a workflow needs to be executed every day at 9:00 PM or every Saturday at 10:30 PM. For both cases, schedule information is passed in the workflow submission so that the workflow can be executed at the scheduled time. |
| Notification | A list of email addresses that will receive workflow status updates. |
{
"name": "Patch Hosts Demo",
"workflow": {
"plan": {
"name": "Patch_Hosts_WF",
"steps": [{
"name": "patch",
"type": "ENTITY",
"input": {
"command": "/bin/sh",
"arguments": ["/scratch/patch.sh"],
"credential": "emcosTestCred"
}
}]
},
"input": {
"workers": {
"thread1": {
"entity": {
"entityByName": {
"name": "example.com",
"type": "omc_host_linux"
}
}
}
}
}
}
}Workflow Variables and Data Passing
Workflows allow the use of variables both with internal data and from external output data.
"${workflow.omc.startTime}"The following examples illustrate templating language expressions:
"${steps['REST step'].result.body}"
"${steps.provisioning.result}"
"${retry[0].vars.result}" "${2 + 2}" // => 4
"${'foo' + 'bar'}" // => myoutput- For JSON result types:
"${steps.step1.result.myPublish.<json node name>}" - For REGEX case:
"${steps.step1.result.myPublish[0]}"