<start> and <end>

The <start> node is the starting point of a workflow. When Oozie starts a workflow, it looks for the <start> node and transitions to the node specified in the to attribute.

The <end> node is the completion point of the workflow. When a workflow transitions to an <end> node, it completes its execution with a SUCCEEDED status.

The preceding workflow example has a <start> node that transitions to a <shell> action echoA, then transitions to the <shell> action echoB, and then transitions to the done <end> node, which ends the workflow successfully. This simple workflow is captured in Figure 5-1.

Figure 5-1. Simple workflow example

<fork> and <join>

Simple workflows execute one action at a time. In the previous section, we saw that the echoA action is executed first and the echoB action is not executed until after echoA completes successfully.

When actions don’t depend on the result of each other, it is possible to execute actions in parallel using the <fork> and <join> control nodes to speed up the execution of the workflow.

When Oozie encounters a <fork> node in a workflow, it starts running all the paths defined by the fork in parallel. These parallel execution paths run independent of each other. All the paths of a <fork> node must converge into a <join> node. A workflow does not proceed its execution beyond the <join> node until all execution paths from the <fork> node reach the <join> node. Example 5-2 captures the <fork>-<join> syntax.

<workflow-app xmlns="uri:oozie:workflow:0.5" name="forkJoinNodeWF">            
  <global>
    ...
  </global>
  <start to="forkActions"/>
  <fork name="forkActions">
    <path name="echoA"/>
    <path name="echoB"/>
  </fork>
  <action name="echoA">
    <shell xmlns="uri:oozie:shell-action:0.2">
        ...
    </shell>
    <ok to="joinActions"/>
    <error to="joinActions"/>
  </action>
  <action name="echoB">
    <shell xmlns="uri:oozie:shell-action:0.2">
        ...
    </shell>
    <ok to="joinActions"/>
    <error to="joinActions"/>
  </action>
  <join name="joinActions" to="done"/>
  <end name="done"/>            
</workflow-app>

The <path> elements within the <fork> node define the parallel execution paths of the <fork> node. Each <path> element indicates the first node in the parallel execution path being created. In the example above, each parallel path happens to have only one action node. But in reality, it could be a sequence of nodes. The last node of each such execution path should transition to the <join> node.

It is possible to have nested <fork> and <join> nodes. The only constraint is that <fork> and <join> nodes always go in pairs and all execution paths starting from a given <fork> must end in the same <join> node. Figures 5-2 and 5-3 depict both invalid and valid nesting of <fork> and <join> nodes.

Figure 5-2. Workflow with invalid nesting of <fork> and <join> nodes

Figure 5-3. Workflow with valid nesting of <fork> and <join> nodes

<decision>

In programming languages, if-then-else and switch-case statements are usually used to control the flow of execution depending on certain conditions being met or not. Similarly, Oozie workflows use <decision> nodes to determine the actual execution path of a workflow.

A <decision> node behavior is best described as an if-then-else-if-then-else... sequence, where the first predicate that resolves to true will determine the execution path. Unlike a <fork> node where all execution paths are followed, only one execution path will be followed in a <decision> node.

Figure 5-4 is a pictorial representation of a workflow that executes a MapReduce, Hive, or Pig job (depending on the value of a workflow parameter).

Figure 5-4. Workflow with a <decision> node

The corresponding workflow XML definition is shown in Example 5-3.

<workflow-app xmlns="uri:oozie:workflow:0.5" name="decisionNodeWF">
  <start to="decision"/>
  <decision name="decision">
    <switch>
      <case to="mapReduce">${jobType eq "mapReduce"}</case>
      <case to="hive">${jobType eq "hive"}</case>
      <case to="pig">${jobType eq "pig"}</case>
      <default to="mapReduce"/>
    </switch>
  </decision>
  <action name="mapReduce">
    ...
    <ok to="done"/>
    <error to="done"/>
  </action>
  <action name="hive">
    ...
    <ok to="done"/>
    <error to="done"/>
  </action>
  <action name="pig">
    ...
    <ok to="done"/>
    <error to="done"/>
  </action>
  <end name="done"/>            
</workflow-app>

Each <case> element has a to attribute indicating the execution path to follow if the content of the <case> element (${jobType eq "mapReduce"} in the example) evaluates to true. If none of the <case> contents evaluates to true, the execution path specified by the <default to> attribute will be followed.

<kill>

The <kill> node allows a workflow to kill itself. If any execution path of a workflow reaches a <kill> node, Oozie will terminate the workflow immediately, failing all running actions (it could be multiple running actions if the workflow execution is currently within a <fork>-<join> block) and setting the completion status of the workflow to KILLED. It is worth noting that Oozie will not explicitly kill the currently running MapReduce jobs on the Hadoop cluster that corresponds to those actions. They will be allowed to complete, though the action will be set to FAILED and no downstream actions of those jobs in their respective <fork>-<join> block will be run. Example 5-4 illustrates the use of a <kill> node.

<workflow-app xmlns="uri:oozie:workflow:0.4" name="killNodeWF">
  <start to="mapReduce"/>
  <action name="mapReduce">
    ...
    <ok to="done"/>
    <error to="error"/>
  </action>
  <kill name="error">
    <message>The 'mapReduce' action failed!</message>
  <end name="done"/>            
</workflow-app>

Using a <kill> node in a workflow is similar to doing a System.exit(1) (any non-zero exit code) in Java. We have already seen in previous examples that action nodes have two possible transitions: <ok> and <error>. Typically, <error> transitions to a <kill> node indicating that something went wrong.

<OK> and <ERROR>

When an action completes, its status is typically in either OK or ERROR status depending on whether or not the execution was successful. If an action ends in OK status, the workflow execution path transitions to the node specified in the <ok> element. If the action ends in ERROR status, the workflow execution path transitions to the node specified in the <error> element. Even when the action exit status is ERROR, the workflow still continues to execute. Typically, the node specified for transition in case of an ERROR is the <kill> node, but it’s not required to be. In that case, the workflow will stop running and it will end up in the KILLED.

If desired, you have the option to continue the workflow execution even in case of an ERROR state for an action. There are legitimate reasons to continue running the workflow even after an action ends with an error. For example, you might want to transition to an <email> action on an error and send mails to a group of people before actually failing the workflow. In some use cases, there might be expected errors that can be handled and you may chose to transition to an action that cleans up or recovers some state and retries the failed action again. In short, just because an action ended up in the ERROR state doesn’t mean the containing workflow also exits with an error right away.

Figure 5-5 captures the typical flow of control from an action node.

Figure 5-5. Workflow action node

Global Configuration

Most actions in a workflow need several of the same settings (e.g., the JobTracker URI, NameNode URI, Hadoop scheduler queue, etc.). Users can avoid repeating all these settings and job configuration values in every action of the workflow by defining them once in the workflow’s <global> section. The properties defined in the <global> section are available to all actions of the workflow. The sample workflow we saw in Example 5-1 introduced this <global> section, but Example 5-5 provides a more detailed example. As you can see, this makes the individual action definitions short and sweet.

<workflow-app name="globalConfigurationWF" xmlns="uri:oozie:workflow:0.5">
  <global>
    <job-tracker>localhost:8032</job-tracker>
    <name-node>hdfs://localhost:8020</name-node>
    <configuration>
        <property>
            <name>mapred.job.queue.name</name>
            <value>development</value>
        </property>
    </configuration>
  </global>

  <action>
    <java>
        <main-class>org.apache.oozie.MyJavaMainClass</main-class>
        <arg>argument1</arg>
        <capture-output/>
    </java>
  </action>
  ...
</workflow-app>

Readers are strongly encouraged to use the <global> section liberally in their workflows to reduce clutter and confusion.

Job XML

Most actions supports a <job-xml> element, which is specifically meant for passing in Hadoop job configuration in XML format. This file has to be packaged with the workflow app and deployed on HDFS. Different action nodes in the workflow can include different job-xml file(s). With the later versions of the Oozie schema (version 0.4 and above), multiple <job-xml> elements are supported, which means that an action can have multiple files packaged and made available with the job configuration information split across them. Example 5-6 shows multiple job XMLs listed for a single action.

<map-reduce>
    <job-tracker>${jobTracker}</job-tracker>
    <name-node>${nameNode}</name-node>
    <job-xml>/conf_A_job.xml</job-xml>
    <job-xml>/conf_B_job.xml</job-xml>
    <job-xml>/conf_C_job.xml</job-xml>
...

Inline Configuration

Inline configuration in the body of the workflow action holds higher priority than the <global> section and the <job-xml> files. Example 5-7 shows a <configuration> section. The format and syntax are the same regardless of whether these properties are defined in the body of the action in the workflow XML or in a separate job XML file. It’s only the priority and precedence that will be different.

    <configuration>
        <property>
            <name>hive.metastore.local</name>
            <value>true</value>
            <description>controls whether to connect to a remote metastore 
                                       server</description>
        </property>
        <property>
            <name>javax.jdo.option.ConnectionURL</name>
            <value>jdbc:postgresql://localhost/hive</value>
            <description>JDBC connect string for a JDBC metastore</description>
        </property>
    </configuration>

Launcher Configuration

We saw in “Action Execution Model” how the Oozie launcher job itself is a MapReduce job. You can specify the configuration settings for this launcher job in the action by prefixing oozie.launcher to any Hadoop configuration property. This way, you can override the default settings Oozie uses for the launcher job. Hadoop configuration properties like the job queue specified for the action are applied as defaults to the launcher job as well. These defaults help keep the action definition short and clean by avoiding specifying several redundant properties, but they can be explicitly overridden using the oozie.launcher.* properties.

EL Variables

The most common technique for parameterization in Oozie is through EL variables. Various settings like NameNode, JobTracker, Hadoop queue, application path, and the date for the datasets can all be defined and parameterized using EL variables. We have seen user-defined variables in a workflow as early as Example 1-1; this is reproduced here:

<job-tracker>${jobTracker}</job-tracker>
<name-node>${nameNode}</name-node>

The values for these user-defined variables ${jobTracker} and ${nameNode}) need to be specified before the job submission. These variables are valid throughout the entire life of the workflow.

${hadoop:counters("myMRNode")["FileSystemCounters"]["FILE_BYTES_READ"]}

${hadoop:counters("myPigNode")["RECORD_WRITTEN"]}

EL Functions

Applications also have a need for handling dynamic values during runtime that cannot be statically defined through variables. For example, you may want to print the workflow ID as part of some <shell> action. This ID is available only at runtime and the developer had no way to specify the value when she was writing the workflow or even when she was submitting it. This is where Oozie’s EL functions come in handy. They are convenience functions that are available for a lot of common use cases. For instance, Oozie has a wf:id() function that returns the ID of the current workflow execution. The workflow can be parameterized using the ${FUNC} syntax ${wf:id()} for this use case. While Oozie verifies the syntax of any function during job submission, it eventually evaluates the functions during the workflow execution.

There are several built-in EL functions that Oozie supports and they are all listed in the Oozie documentation. They are roughly classified as basic, Hadoop, HDFS, and HCatalog functions and constants. We will now look at a few common and useful ones.

EL Expressions

In addition to the EL variables and functions, EL expressions are supported as well. A common use case for this is the decision nodes in a workflow. It’s not uncommon to check the output of the previous action against some condition and branch the workflow based on that. But that’s not the only use for EL expressions and they can be used wherever the EL variables and functions are supported. Example 5-3 illustrates the use of EL expressions in the context of a decision node.

As you can see, EL variable, function, and expression substitution are a very powerful and fundamental feature of Oozie and users are encouraged to make good use of it. This will make their workflows more flexible and dynamic.

Command-Line Option

Passing parameter values using the -D command-line option is pretty much the same as defining them through the job.properties, except the -D overrides the properties file and is of the highest priority. Example 5-10 contains an example of using -D on the command line to pass in a variable.

oozie job -oozie http://localhost:4080/oozie/ -DqueueName=research 
  -config job.properties –run

The config-default.xml File

The optional config-default.xml file can be packaged with the workflow and deployed in the workflow app directory on HDFS. This file has default values for variables that are not defined via the job.properties file or the -D option. You can use the same job.properties file for all invocations of the workflow or use a different properties file for different runs. But the config-default.xml file is valid for all invocations of the workflow and serves as the default for all missing variables in other places. A sample is shown here:

<configuration>
    <property>
        <name>queueName</name>
        <value>default</value>
    </property>
</configuration>

The <parameters> Section

Another convenient feature for parameterization is the <parameters> section at the top of the workflow. This optional section allows users to declare the EL variables in the workflow XML. This lets Oozie validate the XML and the parameters before submission to the server rather than after. This is similar to a compile time check versus a runtime check in programming languages. Users can declare just a <name> or also specify a <value>. If there is just a name, Oozie will check for the value defined either in the job.properties file or through -D . It will throw an error if the variable is not defined. If the <parameters> section also includes a <value> element, that value will be used as the default value if the variable is not defined elsewhere. It is similar to the config-default.xml and can be used for handling defaults, though the <parameters> section is confined to only that workflow file.

Example 5-11 contains an example of a <parameters> usage in a workflow.

...
<workflow-app name="parametersWF" xmlns="uri:oozie:workflow:0.5">
<parameters>
    <property>
        <name>queueName</name>
        <value>production</value>
    </property>
    <property>
        <name>outputDir</name>
    </property>
</parameters>
...

Action States

Much like the workflow, individual actions go through their own state transitions, too. We won’t cover the action states in detail because users don’t usually manage the action states at that level of granularity. It’s more practical to manage complete workflows or even coordinators or bundles. The list of action states is captured here just for your reference:

• DONE

• END_MANUAL

• END_RETRY

• ERROR

• FAILED

• KILLED

• OK

• PREP

• RUNNING

• START_MANUAL

• START_RETRY

• USER_RETRY

In this chapter, we saw the various practical aspects of writing an Oozie workflow application. This chapter, combined with the coverage of various action types in Chapter 4, should give you enough ammunition for writing efficient, production-quality workflow applications. We will now move on to the Oozie coordinator in the next chapter.