markap14 commented on a change in pull request #3725: NIFI-6558 Added 
Parameters to User Guide and Sys Admin Guide

 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
+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
+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 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 
+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:
+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 
+| `+#{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:
 Review comment:
   I believe this is inaccurate. I think it was like this when the initial 
commit landed but was changed to make things easier to understand. If you use 
the below EL, it will evaluate to the literal value "#{abc}". If you wanted to 
actually reference the parameter, then change the xxx to zzz you'd just use `${ 
#{abc}:replace('xxx', 'zzz') }`

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:

With regards,
Apache Git Services

Reply via email to