Adding Dataflow Runtime Options

Dataflow runtime options enable you control the behavior of stages when you run the dataflow. This is useful when you want to have the ability to modify the behavior of the dataflow when it runs. For example, you may want to specify a source database for a Read from DB stage when you run the dataflow, rather than using the database specified in the Read from DB stage in the dataflow.

This procedure describes how to expose options that can be set at runtime. After performing this procedure you will be able to set dataflow options at runtime using these techniques:

  • For jobs, you will be able to specify runtime options using a dataflow options property file and job executor's -o argument.
  • For services, you will be able to specify runtime options as API options.
  • For services exposed as web service, you will be able to specify runtime options as parameters in the request.
  • For subflows, runtime options will be inherited by the parent dataflow and exposed through one of the above means, depending on the parent dataflow type (job, service, or service exposed as a web service).

To add runtime options to a dataflow,

  1. Open the dataflow in Enterprise Designer.
  2. If you want to configure runtime options for a stage in an embedded dataflow, open the embedded dataflow.
  3. Click the Dataflow Options icon on the toolbar or click Edit > Dataflow Options. The Dataflow Options dialog box appears.
  4. Click Add. The Define Dataflow Options dialog box appears.
  5. In the Option name field, specify the name you want to use for this option. This is the option name that will have to be specified at runtime in order to set this option.
  6. In the Label field, you can specify a different label or keep it the same as the option name.
  7. Enter a description of the option in the Description field.
  8. In the Target field, chose whether you want this option to be applied to all stages in the dataflow or only certain stages.
    Selected stage(s)
    Select this option if you want the option to only be applied to the stages you specify.
    All stages
    Select this option if you want the option to be applied to all stages in the dataflow.
    Includes transforms
    Select this option if you want the runtime option to be made available to custom transforms in Transformer stages in the dataflow. If you choose this option you can access the value specified at run time in the Groovy script of a custom transform by using the following syntax:
    options.get("optionName")
    For example, to access an option named casing, you would include this in your custom transform script:
    options.get("casing")
  9. If you chose Selected stage(s) in the Target field, the Map dataflow options to stages table displays a list of the stages in the dataflow. Select the option that you want to expose as a dataflow option. You will see the Default value and Legal values fields be completed with data when you select your first item.
    Note: You can select multiple options so that the dataflow option can control multiple stages options. If you do this, each of the stage options you select must share legal values. For example, one option has values of Y and N, each of the additional options must have either Y or N in their set of values, and you can only allow the value in common to be available at runtime. So, if you select an option with Y and N values, you cannot select an option with the values of E, T, M, and L, but you could select an option with the values of P, S, and N because both options share "N" as a value. However, only "N" would be an available value for this option, not "Y", "P", or "S".
  10. If you want to limit the values that can be specified at runtime, edit the options in the Legal values field by clicking on the icon just to the right of the field.
  11. If you want to change the default value, specify a different value in the Default value field.
    Note: For a service, you can only modify default values before exposing the service for the first time. Once you expose the service you can no longer modify default values using Enterprise Designer. Instead, you must use Management Console. For more information, see Specifying Default Service Options.
  12. Click OK.
  13. Continue adding options as desired.
  14. Click OK in the Dataflow Options dialog box when you are done adding options.
  15. If you added a runtime option to an embedded dataflow, you must define the runtime option parent dataflow as well as all ancestor dataflows in order to make the options available at runtime. To do this, open the dataflow that contains the embedded dataflow and expose the option you just created. If necessary, open the parent of that dataflow and define the option there, and so on until all ancestors have the dataflow option defined.

    For example, say you had a dataflow named "A" that contained an embedded dataflow named "B" which contained an embedded dataflow named "C", so that you have an embedded dataflow hierarchy like this: A > B > C. If you wanted to expose an option named Casing in a stage in embedded dataflow "C", you would open embedded dataflow "C" and define it. Then, you would open embedded dataflow "B" and define the option. Finally, you would open dataflow "A" and define the option, making it available at runtime.

The dataflow is now configured to allow options to be specified at runtime.