This is an automated email from the ASF dual-hosted git repository.
mcgilman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nifi.git
The following commit(s) were added to refs/heads/master by this push:
new 4cf9616 NIFI-6558 Improved import/export versioned flows section and
also edited managing local changes section
4cf9616 is described below
commit 4cf961690acef8d41a55b0f928eb2532443bcf3e
Author: Andrew Lim <[email protected]>
AuthorDate: Wed Sep 18 11:15:48 2019 -0400
NIFI-6558 Improved import/export versioned flows section and also edited
managing local changes section
This closes #3753
---
.../main/asciidoc/images/nifi_pc1_parameters.png | Bin 0 -> 79044 bytes
.../asciidoc/images/nifi_pc1_parameters_new.png | Bin 0 -> 85571 bytes
.../src/main/asciidoc/images/pc1_parameters.png | Bin 0 -> 85249 bytes
nifi-docs/src/main/asciidoc/user-guide.adoc | 45 +++++++++++++++++----
4 files changed, 37 insertions(+), 8 deletions(-)
diff --git a/nifi-docs/src/main/asciidoc/images/nifi_pc1_parameters.png
b/nifi-docs/src/main/asciidoc/images/nifi_pc1_parameters.png
new file mode 100644
index 0000000..f006f44
Binary files /dev/null and
b/nifi-docs/src/main/asciidoc/images/nifi_pc1_parameters.png differ
diff --git a/nifi-docs/src/main/asciidoc/images/nifi_pc1_parameters_new.png
b/nifi-docs/src/main/asciidoc/images/nifi_pc1_parameters_new.png
new file mode 100644
index 0000000..c0b0524
Binary files /dev/null and
b/nifi-docs/src/main/asciidoc/images/nifi_pc1_parameters_new.png differ
diff --git a/nifi-docs/src/main/asciidoc/images/pc1_parameters.png
b/nifi-docs/src/main/asciidoc/images/pc1_parameters.png
new file mode 100644
index 0000000..b4bb379
Binary files /dev/null and
b/nifi-docs/src/main/asciidoc/images/pc1_parameters.png differ
diff --git a/nifi-docs/src/main/asciidoc/user-guide.adoc
b/nifi-docs/src/main/asciidoc/user-guide.adoc
index 2900035..89d1c41 100644
--- a/nifi-docs/src/main/asciidoc/user-guide.adoc
+++ b/nifi-docs/src/main/asciidoc/user-guide.adoc
@@ -873,7 +873,7 @@ Hovering over the question mark icon
(image:iconInfo.png["Info"]) displays the p
===== Using Parameters with Sensitive Properties
-Sensitive properties may only reference sensitive Parameters. This is
important for <<versioning_dataflow, versioned flows>>. The value of the
sensitive Parameter itself will NOT be sent to the flow registry, only the fact
that the property references the sensitive Parameter. For more information see
<<parameters-and-versioned-flows>>.
+Sensitive properties may only reference sensitive Parameters. This is
important for <<versioning_dataflow, versioned flows>>. The value of the
sensitive Parameter itself will NOT be sent to the flow registry, only the fact
that the property references the sensitive Parameter. For more information see
<<parameters-in-versioned-flows>>.
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. This is in contrast to a non-sensitive property,
where a value such as `+#{path}/child/file.txt+` is valid.
@@ -908,12 +908,6 @@ In order to modify a Parameter, a user must have view and
modify policies for an
See the <<administration-guide.adoc#component-level-access-policies,Component
Level Access Policies>> section in the System Administrator's Guide for more
information.
-[[parameters-and-versioned-flows]]
-==== Parameters and Versioned Flows
-When exporting a flow to a Flow Registry, the name of the Parameter Context is
sent for each process group that is stored. Additionally, the Parameters
(names, descriptions, values, whether or not sensitive) are stored with the
flow. Sensitive Parameter values are not stored.
-
-When a flow is imported, if no Parameter Context is set, NiFi will set the
Parameter Context with the same name as the one stored in Flow Registry. If
none exists with that name, NiFi will create one. If a Parameter Context has
been set and the imported flow contains a Parameter Context with the same name
and Parameters with the same names but different values, the existing Parameter
values will not be overwritten by those from the imported flow. However, any
Parameters missing from the [...]
-
[[Using_Custom_Properties]]
=== Using Custom Properties with Expression Language
@@ -2122,11 +2116,14 @@ The following actions are not considered local changes:
* modifying sensitive property values
* modifying remote process group URLs
* updating a processor that was referencing a non-existent controller service
to reference an externally available controller service
+* assigning, creating, modifying or deleting parameter contexts
* creating, modifying or deleting variables
+NOTE: Assigning or creating a parameter context does not trigger a local
change because assigning or creating a parameter context on its own has not
changed anything about what the flow processes. A component will have to be
created or modified that uses a parameter in the parameter context, which will
trigger a local change. Modifying a parameter context does not trigger a local
change because parameters are intended to be different in each environment.
When a versioned flow is imported [...]
+
NOTE: Creating a variable does not trigger a local change because creating a
variable on its own has not changed anything about what the flow processes. A
component will have to be created or modified that uses the new variable, which
will trigger a local change. Modifying a variable does not trigger a local
change because variable values are intended to be different in each
environment. When a versioned flow is imported, it is assumed there is a
one-time operation required to set those [...]
-WARNING: Variables do not support sensitive values and will be included when
versioning a Process Group. See <<Variables_in_Versioned_Flows>> for more
information.
+WARNING: Variables do not support sensitive values and will be included when
versioning a Process Group. Variables are still supported for compatibility
purposes but do not have the same power as Parameters such as support for
sensitive properties and more granular control over who can create, modify or
use them. Variables will be removed in a future release. As a result, it is
highly recommended to switch to Parameters.
==== Show Local Changes
The local changes made to a versioned process group can be viewed in the Show
Local Changes dialog by selecting "Version->Show local changes" from the
context menu.
@@ -2188,6 +2185,38 @@
image::process-group-version-control-stopped.png["Version Control Stopped on Pro
=== Nested Versioned Flows
A versioned process group can contain other versioned process groups.
However, local changes to a parent process group cannot be reverted or saved if
it contains a child process group that also has local changes. The child
process group must first be reverted or have its changes committed for those
actions to be performed on the parent process group.
+[[parameters-in-versioned-flows]]
+=== Parameters in Versioned Flows
+When exporting a versioned flow to a Flow Registry, the name of the Parameter
Context is sent for each process group that is stored. The Parameters (names,
descriptions, values, whether or not sensitive) are also stored with the flow.
However, Sensitive Parameter values are not stored.
+
+When a versioned flow is imported, a Parameter Context will be created for
each one that doesn't already exist in the NiFi instance. When importing a
versioned flow from Flow Registry, if NiFi has a Parameter Context with the
same name, the values are merged, as described in the following example:
+
+A flow has a Parameter Context "PC1" with the following parameters:
+
+image::pc1_parameters.png[PC1 Parameters]
+
+The flow is exported and saved to the Flow Registry.
+
+A NiFi instance has a Parameter Context also named "PC1" with the following
parameters:
+
+image::nifi_pc1_parameters.png[NiFi PC1 Parameters]
+
+The versioned flow is imported into the NiFi instance. The Parameter Context
"PC1" now has the following parameters:
+
+image::nifi_pc1_parameters_new.png[New NiFi PC1 Parameters]
+
+The "Letters" parameter did not exist in the NiFi instance and was added. The
"Numbers" parameter existed in both the versioned flow and NiFi instance with
identical values, so no changes were made. "Password" is a sensitive Parameter
missing from the NiFi instance, so it was added but with no value. "Port"
existed in the NiFi instance with a different value than the versioned flow, so
its value remained unchanged.
+
+Parameter Contexts are handled similarly when a flow version is changed.
Consider the following two examples:
+
+If the versioned flow referenced earlier is changed to another version
(Version 2) and Version 2's Parameter Context "PC1" has a "Colors" Parameter,
"Colors" will be added to "PC1" in the NiFi instance.
+
+Version 1 of a flow does not have a Parameter Context associated with it. A
new version (Version 2) does. When the flow is changed from Version 1 to
Version 2, one of the following occurs:
+
+- A new Parameter Context is created if it does not already exist
+- An existing Parameter Context is assigned (by name) to the Process Group and
the values of the Parameter Contexts are merged
+
+
[[Variables_in_Versioned_Flows]]
=== Variables in Versioned Flows
Variables are included when a process group is placed under version control.
If a versioned flow is imported that references a variable not defined in the
versioned process group, the reference is maintained if the variable exists.
If the referenced variable does not exist, a copy of the variable will be
defined in the process group. To illustrate, assume the variable “RPG_Var" is
defined in the root process group:
