nifi-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From GitBox <...@apache.org>
Subject [GitHub] [nifi] markap14 commented on a change in pull request #3725: NIFI-6558 Added Parameters to User Guide and Sys Admin Guide
Date Thu, 12 Sep 2019 19:20:29 GMT
markap14 commented on a change in pull request #3725: NIFI-6558 Added Parameters to User Guide
and Sys Admin Guide
URL: https://github.com/apache/nifi/pull/3725#discussion_r323903724
 
 

 ##########
 File path: nifi-docs/src/main/asciidoc/user-guide.adoc
 ##########
 @@ -711,15 +711,187 @@ whatever comments are appropriate for this component. Use of the Comments
tab is
 image::comments-tab.png["Comments Tab"]
 
 
-=== Additional Help
+==== Additional Help
 
 You can access additional documentation about each Processor's usage by right-clicking on
the Processor and selecting 'Usage' from the context menu. Alternatively, select Help from
the Global Menu in the top-right corner of the UI to display a Help page with all of the documentation,
including usage documentation for all the Processors that are available. Click on the desired
Processor to view usage documentation.
 
+[[Parameters]]
+=== Parameters
+The values of properties in the flow, including sensitive properties, can be parameterized
using Parameters. Parameters are created and configured within the NiFi UI. Any property can
be configured to reference a Parameter with the following conditions:
+
+ - A sensitive property can only reference a Sensitive Parameter
+ - A non-sensitive property can only reference a non-Sensitive Parameter
+ - Properties that reference Controller Services can not use Parameters
+
+NOTE: NiFi automatically picks up new or modified parameters.
+
+[[parameter-contexts]]
+==== Parameter Contexts
+Parameters are created within Parameter Contexts. Parameter Contexts are globally defined/accessible
to the NiFi instance. Access policies can be applied to Parameter Contexts to determine which
users can create them. Once created, policies to read and write to a specific Parameter Context
can also be applied (see <<accessing-parameters>> for more information).
+
+===== Creating a Parameter Context
+To create a Parameter Context, select Parameter Contexts from the Global Menu:
+
+image:parameter-contexts-selection.png["Global Menu - Parameter Contexts"]
+
+In the Parameter Contexts window, click the `+` button in the upper-right corner and the
Add Parameter Context window opens. The window has two tabs: Settings and Parameters.
+
+image:parameter-contexts-settings.png["Parameter Contexts - Settings"]
+
+On the "Settings" tab, add a name for the Parameter Context and a description if desired.
 Select "Apply" to save the Parameter Context or select the "Parameters" tab to add parameters
to the context.
+
+==== Adding a Parameter to a Parameter Context
+Parameters can be added during Parameter Context creation or added to existing Parameter
Contexts.
+
+During Parameter Context creation, select the "Parameters" tab. Click the `+` button to open
the Add Parameter window.
+
+image:add-parameter-during-parameter-context-creation.png[Add Parameter]
+
+To add parameters to an existing Parameter Context, open the Parameter Context window and
click the Edit button (image:iconEdit.png["Edit"]) in the row of the desired Parameter Context.
+
+image:edit-parameter-context.png[Edit Parameter Context]
+
+On the "Parameters" tab, click the `+` button to open the Add Parameter window.
+
+The Add Parameter window has the following settings:
+
+- *Name* - A name that is used to denote the Parameter. Only alpha-numeric characters (a-z,
A-Z, 0-9), hyphens ( - ), underscores ( _ ), periods ( . ), and spaces are allowed.
+
+- *Value* - The value that will be used when the Parameter is referenced.
+
+- *Set empty string* - Check to explicity set the value of the Parameter to an empty string.
Unchecked by default.
+
+- *Sensitive Value* -  Set to "Yes" if the Parameter's Value should be considered sensitive.
If sensitive, the value of the Parameter will not be shown in the UI once applied. The default
setting is "No".
+
+- *Description* - A description that explains what the Parameter is, how it is to be used,
etc. This field is optional.
+
+Once these settings are configured, select "Apply". Add additional Parameters or edit any
existing Parameters.
+
+image:update-parameter-context.png[Update Parameter Context]
+
+To complete the process, select "Apply" from the Parameter Context window. The following
operations are performed to validate all components that reference the added or modified parameters:
Stopping/Restarting affected Processors, Disabling/Re-enabling affected Controller Services,
Updating Parameter Context.
+
+image:parameters-validate-affected-components.png[Validate Affected Components]
+
+The Referencing Components section lists any components referencing the parameters in the
parameter context organized by process group.
+
+[[assigning_parameter_context_to_PG]]
+==== Assigning a Parameter Context to a Process Group
+For a component to reference a Parameter, its Process Group must first be assigned to a Parameter
Context. Once assigned, processors and controller services within that Process Group may only
reference Parameters within that Parameter Context.
+
+NOTE: A user can only set the Parameter Context of a Process Group to one of the Parameter
Contexts that the user has the view policy for. Additionally, in order to set the Parameter
Context, the user must have the modify policy for the Process Group. See <<accessing-parameters>>
for more information.
+
+To assign a Parameter Context to a Process group, click Configure, either from the Operate
Palette or from the Process Group context menu.
+
+image:process-group-configuration-parameters.png[Configure Process Group Parameter Context]
+
+In the Flow Configuration window, select the "General" tab. From the Process Group Parameter
Context drop-down menu, select an existing Parameter Context or create a new one.
+
+image:process-group-parameter-context-menu.png[Process Group Parameter Context Menu]
+
+Select "Apply" to save the configuration changes. The Process Group context menu now includes
a "Parameters" option which allows quick access to the Update Parameter Context window for
the assigned Parameter Context.
+
+image:context-menu-parameters-option.png[Context Menu Parameters Option]
+
+If the Parameter Context for a Process Group is changed, all components that reference any
Parameters in that Process Group will be stopped, validated, and restarted (assuming the changes
are valid).
+
+NOTE: If a Parameter Context is unset from a Process Group, it does *NOT* inherit the Parameter
Context from the parent Process Group. Instead, no Parameters can be referenced. Any component
that does already reference a Parameter will become invalid.
+
+==== Referencing Parameters
+
+===== Parameter Reference Syntax
+To configure an eligible property to reference a Parameter, use the `#` symbol as the start,
with the Parameter's name enclosed in curly braces:
+
+`#{Parameter.Name}`
+
+This can be escaped using an additional `#` character at the beginning. To illustrate this,
assume that the Parameter `abc` has a value of `xxx` and Parameter `def` has a value of `yyy`.
Then, the following user-defined property values will evaluate to these effective values:
+
+|================================================================================================================================================================
+| *User-Entered Literal Property Value* | *Effective Property Value*                 | *Explanation*
+| `#{abc}`                              | `xxx`                                      | Simple
substitution
+| `+#{abc}/data+`                       | `xxx/data`                                 | Simple
substitution with additional literal data
+| `+#{abc}/#{def}+`                     | `xxx/yyy`                                  | Multiple
substitution with additional literal data
+| `+#{abc+`                             | `+#{abc+`                                  | No
{ } for parameter replacement
+| `+#abc+`                              | `+#abc+`                                   | No
{ } for parameter replacement
+| `+##{abc}+`                           | `+#{abc}+`                                 | Escaped
# for literal interpretation
+| `+###{abc}+`                          | `#xxx`                                     | Escaped
# for literal interpretation, followed by simple substitution
+| `+####{abc}+`                         | `+##{abc}+`                                | Escaped
# for literal interpretation, twice
+| `+#####{abc}+`                        | `+##xxx+`                                  | Escaped
# for literal interpretation, twice, followed by simple substitution
+| `+#{abc/data}+`                       | Exception thrown on property set operation | `/`
not a valid parameter name character
+|================================================================================================================================================================
+
+When referencing a Parameter from within link:expression-language-guide.html[Expression Language],
the Parameter reference is evaluated first. As an example, to replace `xxx` with `zzz` for
the `abc` Parameter:
+
+`${ literal('#{abc}'):replace('xxx', 'zzz') }`
+
+===== Referencing and Creating Parameters During Component Configuration
+Parameters can be easily referenced or created as you configure the components in your flow.
For example, assume a process group  has the Parameter Context "Kafka Settings" assigned to
it. "Kafka Settings" contains the parameters `kafka.broker` and `kafka.topic1`.
+
+image::existing-parameters-example.png[Existing Parameters]
+
+To reference `kafka.broker` as the value for the "Kafka Brokers" property in the PublishKafka
processor, clear the default value and begin a new entry with the start delimiter `#{`. Next
use the keystroke `control+space` to show the list of available parameters:
+
+image::autocomplete-parameter-example.png[Autocomplete Parameter Example]
+
+Select `kafka.broker` and complete the entry with a closing curly brace `}`.
+
+image:existing-parameter-selected.png[Existing Parameter Selected]
+
+Help text describing this process is displayed when hovering over the Expression Language
and Parameters eligibility indicators.
+
+image::el-param-support-help-text.png[Expression Language and Parameters Help Text]
+
+Parameters can also be created on the fly. For example, to create a parameter for the "Topic
Name" property, select the "Convert to Parameter" icon (image:iconConvertToParameter.png["Convert
to Parameter"]) in that property's row.
+
+image::convert-property-to-parameter.png[Convert Property to Parameter]
+
+The Add Parameter dialog will open. Configure the new parameter as desired.
+
+image::configure-parameter-on-the-fly.png[Configure Parameter On the Fly]
+
+Select "Apply". The process group's Parameter Context will be updated and the new parameter
will be referenced by the property with the proper syntax applied automatically.
+
+image::new-parameter-referenced.png[New Parameter Referenced]
+
+
+===== Using Parameters with Sensitive Properties
+Sensitive Properties may only reference sensitive Parameters. This is important for <<versioning_dataflow,
versioned flows>> as it indicates to the Flow Registry that the property references
a Parameter by including the value of a Sensitive Property if and only if the value is a reference
to a sensitive Parameter.
+
+The value of a sensitive property must be set to a single Parameter reference. For example,
values of `+#{password}123+` and `+#{password}#{suffix}+` are not allowed. Sending `+#{password}123+`
would lead to exposing part of the Sensitive Property's value.
 
 Review comment:
   Would point out that this is in contrast to non-sensitive properties, where a value of
`#{path}/child/file.txt` is valid, just to avoid confusion.

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services

Mime
View raw message