Parameters

Parameter context management

For Managing NiFi Parameter Contexts

nipyapi.parameters.apply_parameter_provider(provider, group_names=None, sensitivity='SENSITIVE', sensitivities=None, synchronized=None, fetch_result=None, greedy=True, identifier_type='auto', refresh=True)[source]

Apply selected staged groups and wait for the completed request.

Parameters:

  • provider (ParameterProviderEntity or str) – Provider entity, ID, or name.

  • group_names (list[str] or str) – Groups to apply; None selects all staged groups.

  • sensitivity (str) – Default “SENSITIVE” or “NON_SENSITIVE” for unset choices.

  • sensitivities (dict) – Parameter name to “SENSITIVE” or “NON_SENSITIVE”. Each name applies in every selected group and must match a staged parameter; other parameters retain their staged choices.

  • synchronized (bool) – Override whether contexts stay synchronized with their provider group. None (default) keeps the staged value, or True where unset; NiFi skips unsynchronized groups on apply, and a warning is logged when none remain.

  • fetch_result (ParameterProviderEntity) – Optional staged response from fetch.

  • greedy (bool) – Allow partial name matching.

  • identifier_type (str) – “auto”, “id”, or “name”.

  • refresh (bool) – Refresh the provider before the operation. Defaults to True.

Returns:

Completed request including affected

components. Sensitive parameter values remain masked by NiFi.

Return type:

ParameterProviderApplyParametersRequestDTO

Raises:

ValueError – Invalid group, sensitivity, or parameter name, mismatched fetch, or failed request.

nipyapi.parameters.assign_context_to_process_group(pg, context_id, cascade=False, greedy=True, identifier_type='auto')[source]

Assigns a given Parameter Context to a specific Process Group Optionally cascades down to direct children Process Groups

Parameters:

  • pg (ProcessGroupEntity or str) – The Process Group to target, as a ProcessGroupEntity object, process group ID, or name.

  • context_id (str) – The ID of the Parameter Context

  • cascade (bool) – Cascade Parameter Context down to child Process Groups?

  • greedy (bool) – For name lookup, True for partial match, False for exact.

  • identifier_type (str) – How to interpret string identifier: “auto” (default) detects UUID vs name, “id” or “name” to force.

Returns:

The updated Process Group

Return type:

ProcessGroupEntity

Raises:

  • TypeError – If pg is not a string or ProcessGroupEntity.

  • ValueError – If process group not found or multiple matches found.

nipyapi.parameters.connect_parameter_provider_group(target, group_name, mappings, identifier_type='auto', greedy=True)[source]

Inherit a provider-created context and set local sensitive parameter aliases.

The target, and any process-group binding, is always re-read before the update. A context not yet inherited is placed first, because the first inherited context defining a name wins and aliases resolve against it. An already inherited context keeps its position unless a higher one defines a mapped source name; then this raises, so the order can be set with set_inherited_parameter_contexts.

Parameters:

  • target (ParameterContextEntity or ProcessGroupEntity or str) – Target context or process group. A group must have a bound context. Ambiguous names fail.

  • group_name (str) – Exact name of the provider-created parameter context.

  • mappings (dict) – Local parameter name to source parameter name.

  • identifier_type (str) – “auto”, “id”, or “name” for target lookup.

  • greedy (bool) – Allow partial target name matching.

Returns:

Completed update and affected components.

Return type:

ParameterContextUpdateRequestDTO

Raises:

ValueError – Missing source parameters, ambiguous/unbound target, invalid aliases, a mapped source name shadowed by a higher-precedence inherited context, a non-sensitive source parameter (NiFi would leave the sensitive alias unresolved), or a local non-sensitive parameter that cannot be changed to sensitive.

nipyapi.parameters.create_parameter_context(name, description=None, parameters=None, inherited_contexts=None)[source]
Create a new Parameter Context with optional description and

initial Parameters

Parameters:
Returns:

The New Parameter Context

Return type:

ParameterContextEntity

nipyapi.parameters.delete_asset(context_id, asset_id)[source]

Delete an asset from a parameter context.

Parameters:

  • context_id (str) – The parameter context ID

  • asset_id (str) – The asset ID to delete

Returns:

Deleted asset info with keys: id, name

Return type:

dict

Raises:

ApiException – If asset not found or delete fails

Example:

>>> result = delete_asset(context_id, asset_id)
>>> print(f"Deleted: {result['name']}")
nipyapi.parameters.delete_parameter_context(context, refresh=True, greedy=True, identifier_type='auto')[source]

Removes a Parameter Context

Parameters:

  • context (ParameterContextEntity or str) – Parameter Context to be deleted, as a ParameterContextEntity object, context ID, or context name.

  • refresh (bool) – Whether to refresh the Context before Deletion

  • greedy (bool) – For name lookup, True for partial match, False for exact.

  • identifier_type (str) – How to interpret string identifier: “auto” (default) detects UUID vs name, “id” or “name” to force.

Returns:

The removed Parameter Context

Return type:

ParameterContextEntity

Raises:

  • TypeError – If context is not a string or ParameterContextEntity.

  • ValueError – If parameter context not found or multiple matches found.

nipyapi.parameters.delete_parameter_from_context(context, parameter_name, greedy=True, identifier_type='auto')[source]

Delete a specific Parameter from a Parameter Context

Parameters:

  • context (ParameterContextEntity or str) – The Parameter Context to Update, as a ParameterContextEntity object, context ID, or context name.

  • parameter_name (str) – The Parameter to delete

  • greedy (bool) – For name lookup, True for partial match, False for exact.

  • identifier_type (str) – How to interpret string identifier: “auto” (default) detects UUID vs name, “id” or “name” to force.

Returns:

The updated Parameter Context

Return type:

ParameterContextEntity

Raises:

  • TypeError – If context is not a string or ParameterContextEntity.

  • ValueError – If parameter context not found or multiple matches found.

nipyapi.parameters.fetch_and_apply_parameter_provider(provider, group_names=None, sensitivity='SENSITIVE', sensitivities=None, synchronized=None, require_parameters=True, greedy=True, identifier_type='auto', refresh=True)[source]

Fetch provider parameters and apply the selected groups.

Parameters:

  • provider (ParameterProviderEntity or str) – Provider entity, ID, or name.

  • group_names (list[str] or str) – Groups to apply; None selects all groups.

  • sensitivity (str) – Default sensitivity for previously unset choices.

  • sensitivities (dict) – Parameter name overrides; see apply_parameter_provider.

  • synchronized (bool) – Synchronized override; see apply_parameter_provider.

  • require_parameters (bool) – Reject missing or empty selected groups.

  • greedy (bool) – Allow partial name matching.

  • identifier_type (str) – “auto”, “id”, or “name”.

  • refresh (bool) – Refresh the provider before the operation. Defaults to True.

Returns:

Completed apply request.

Return type:

ParameterProviderApplyParametersRequestDTO

Raises:

ValueError – Missing/empty selected groups, or the errors raised by apply_parameter_provider.

nipyapi.parameters.fetch_parameter_provider(provider, greedy=True, identifier_type='auto', refresh=True)[source]

Fetch and stage provider parameters without applying them to contexts.

This is a write operation. The synchronous POST response contains staged groups.

Parameters:

  • provider (ParameterProviderEntity or str) – Provider entity, ID, or name.

  • greedy (bool) – Allow partial name matching.

  • identifier_type (str) – “auto”, “id”, or “name”.

  • refresh (bool) – Refresh the provider before the operation. Defaults to True.

Returns:

Provider with staged parameter groups.

Return type:

ParameterProviderEntity

Raises:

  • ValueError – If lookup fails.

  • ApiException – If fetch fails; the original NiFi response is preserved.

nipyapi.parameters.get_parameter_context(identifier, identifier_type='name', greedy=True)[source]

Gets one or more Parameter Contexts matching a given identifier

Parameters:

  • identifier (str) – The Name or ID matching Parameter Context(s)

  • identifier_type (str) – ‘name’ or ‘id’

  • greedy (bool) – False for exact match, True for string match

Returns:

None for no matches, Single Object for unique match, list(Objects) for multiple matches

nipyapi.parameters.get_parameter_context_hierarchy(context_id, include_bindings=False, include_parameters=True)[source]

Get the full parameter context inheritance hierarchy.

Traverses from the given context through all inherited contexts, returning a nested structure showing the full hierarchy.

Parameters:

  • context_id (str) – The ID of the root parameter context

  • include_bindings (bool) – If True, include bound_process_groups for each context showing which process groups are using it. Useful for determining cleanup safety. Default: False

  • include_parameters (bool) – If True, include parameter details for each context. Set to False for a lightweight structure-only view. Default: True (backwards compatible)

Returns:

Hierarchy with keys:

  • id: Context ID

  • name: Context name

  • parameters: List of parameter info dicts (if include_parameters=True)

    Each parameter dict contains: name, description, sensitive, value, has_asset, asset_name

  • inherited: List of child hierarchy dicts (recursive)

  • bound_process_groups: List of {id, name} dicts (if include_bindings=True)

Return type:

dict

Example:

>>> # Get full hierarchy with parameters
>>> hierarchy = get_parameter_context_hierarchy(context_id)
>>> print(hierarchy['name'])  # "PostgreSQL Ingestion Parameters"
>>> print(hierarchy['inherited'][0]['name'])  # "PostgreSQL Destination Parameters"

>>> # Get structure with bindings for cleanup analysis
>>> hierarchy = get_parameter_context_hierarchy(
...     context_id, include_bindings=True, include_parameters=False
... )
>>> for ctx in [hierarchy] + hierarchy['inherited']:
...     bindings = len(ctx.get('bound_process_groups', []))
...     print(f"{ctx['name']}: {bindings} bindings")
nipyapi.parameters.get_parameter_ownership_map(context_id)[source]

Build a map of parameter names to their owning context.

Traverses the inheritance hierarchy and returns information about where each parameter is defined (its “owner”), including metadata needed for safe updates.

Parameters:

context_id (str) – The ID of the root parameter context

Returns:

dict mapping parameter names to ownership info dicts. Each ownership dict has: context_id, context_name, description, sensitive, has_asset, asset_name, and current_value (None if sensitive).

Example:

>>> ownership = get_parameter_ownership_map(context_id)
>>> print(ownership["PostgreSQL Username"])
{'context_id': '...', 'context_name': 'PostgreSQL Source Parameters', ...}
nipyapi.parameters.get_parameter_provider(identifier, identifier_type='name', greedy=True)[source]

Find parameter providers by name, ID, or provider type.

Parameters:

  • identifier (str) – Name, ID, or provider class name to match.

  • identifier_type (str) – One of “name”, “id”, or “type”.

  • greedy (bool) – Use substring matching instead of exact matching.

Returns:

Single match, multiple matches,

or None when no provider matches.

Return type:

ParameterProviderEntity or list or None

nipyapi.parameters.get_parameter_provider_type(identifier, identifier_type='name', greedy=True)[source]

Find installed parameter provider types.

Parameters:

  • identifier (str) – Class name, bundle, or tag to match.

  • identifier_type (str) – Registered DocumentedTypeDTO filter field.

  • greedy (bool) – Use substring matching instead of exact matching.

Returns:

Matching provider type(s).

Return type:

DocumentedTypeDTO or list or None

nipyapi.parameters.get_process_group_parameter_context(process_group, greedy=True, identifier_type='auto')[source]

Get the context currently bound to a process group.

The process group is always re-read, so a supplied entity’s binding is not trusted.

Parameters:

  • process_group (ProcessGroupEntity or str) – Process group entity, ID, or name.

  • greedy (bool) – Allow partial name matching.

  • identifier_type (str) – “auto”, “id”, or “name”.

Returns:

Bound context, or None for an unbound group.

Return type:

ParameterContextEntity or None

Raises:

ValueError – The process group cannot be uniquely resolved.

nipyapi.parameters.list_all_parameter_contexts()[source]

Lists all Parameter Contexts available on the Canvas

Returns:

list(ParameterContextEntity)

nipyapi.parameters.list_all_parameter_provider_types()[source]

List available parameter provider types.

Returns:

Installed provider types.

Return type:

list[DocumentedTypeDTO]

nipyapi.parameters.list_all_parameter_providers()[source]

List all parameter providers.

Returns:

Configured providers.

Return type:

list[ParameterProviderEntity]

nipyapi.parameters.list_assets(context_id)[source]

List all assets in a parameter context.

Parameters:

context_id (str) – The parameter context ID

Returns:

List of asset info dicts with keys: id, name, digest, missing_content

Return type:

list[dict]

Example:

>>> assets = list_assets(context_id)
>>> for asset in assets:
...     print(f"{asset['name']} ({asset['id']})")
nipyapi.parameters.list_orphaned_contexts()[source]

Lists Parameter Contexts that are not bound to any Process Groups.

An orphaned context is one that exists but has no process groups referencing it. These may be safe to delete after cleanup operations.

Returns:

Contexts with no bound process groups

Return type:

list(ParameterContextEntity)

nipyapi.parameters.prepare_parameter(name, value=<object object>, description=None, sensitive=False)[source]

Parses basic inputs into a Parameter object ready for submission

Parameters:

  • name (str) – The Name for the Parameter

  • value (str, int, float, None) – The Value for the Parameter. - Omit: Don’t change existing value (useful for updating description only) - None: Explicitly unset/remove the value - “”: Set to empty string - Other: Set to that value

  • description (str) – Optional Description for the Parameter

  • sensitive (bool) – Whether to mark the Parameter Value as sensitive

Returns:

The ParameterEntity ready for use

Return type:

ParameterEntity

Example:

>>> # Create parameter with value
>>> param = prepare_parameter("Username", "admin")

>>> # Update description without changing value (e.g., for sensitive params)
>>> param = prepare_parameter("Password", description="Database password")

>>> # Explicitly unset/remove a parameter's value
>>> param = prepare_parameter("OptionalSetting", value=None)
nipyapi.parameters.prepare_parameter_with_asset(name, asset_id=None, asset_name=None, description=None, assets=None)[source]

Prepare a parameter that references one or more assets.

Use this to update a parameter to point to uploaded asset(s). Provide either (asset_id + asset_name) for a single asset, or assets for multiple assets. These are mutually exclusive.

Parameters:

  • name (str) – Parameter name (required)

  • asset_id (str, optional) – ID of a single asset. Must be provided together with asset_name. Cannot be used with assets.

  • asset_name (str, optional) – Name of a single asset. Must be provided together with asset_id. Cannot be used with assets.

  • description (str, optional) – Parameter description

  • assets (list, optional) – List of asset dicts, each with ‘id’ and ‘name’ keys. Cannot be used with asset_id/asset_name.

Returns:

ParameterEntity ready for

use with update_parameter_context or upsert_parameter_to_context

Return type:

ParameterEntity

Example (single asset):

>>> # Upload asset first
>>> asset = upload_asset(context_id, file_path="/path/to/driver.jar")
>>> # Then prepare parameter to reference it
>>> param = prepare_parameter_with_asset(
...     name="JDBC Driver",
...     asset_id=asset['id'],
...     asset_name=asset['name']
... )
>>> upsert_parameter_to_context(context, param)

Example (multiple assets):

>>> # Upload multiple JARs
>>> jar1 = upload_asset(context_id, file_path="/path/to/activemq-client.jar")
>>> jar2 = upload_asset(context_id, file_path="/path/to/activemq-broker.jar")
>>> # Reference all in one parameter
>>> param = prepare_parameter_with_asset(
...     name="JMS Client Libraries",
...     assets=[jar1, jar2]  # Each dict has 'id' and 'name'
... )
>>> upsert_parameter_to_context(context, param)
nipyapi.parameters.remove_context_from_process_group(pg, greedy=True, identifier_type='auto')[source]

Clears any Parameter Context from the given Process Group

Parameters:

  • pg (ProcessGroupEntity or str) – The Process Group to target, as a ProcessGroupEntity object, process group ID, or name.

  • greedy (bool) – For name lookup, True for partial match, False for exact.

  • identifier_type (str) – How to interpret string identifier: “auto” (default) detects UUID vs name, “id” or “name” to force.

Returns:

The updated Process Group

Return type:

ProcessGroupEntity

Raises:

  • TypeError – If pg is not a string or ProcessGroupEntity.

  • ValueError – If process group not found or multiple matches found.

nipyapi.parameters.rename_parameter_context(context, name, refresh=True, greedy=True, identifier_type='auto')[source]

Rename a Parameter Context without resubmitting parameter values.

This is a lightweight wrapper around update_parameter_context that only updates the name field, avoiding the overhead of revalidating all parameters.

Parameters:

  • context (ParameterContextEntity or str) – Parameter Context to rename, as a ParameterContextEntity object, context ID, or context name.

  • name (str) – The new name for the parameter context.

  • refresh (bool) – Whether to refresh the Context before renaming.

  • greedy (bool) – For name lookup, True for partial match, False for exact.

  • identifier_type (str) – How to interpret string identifier: “auto” (default) detects UUID vs name, “id” or “name” to force.

Returns:

The renamed Parameter Context

Return type:

ParameterContextEntity

Raises:

  • TypeError – If context is not a string or ParameterContextEntity.

  • ValueError – If parameter context not found or multiple matches found.

Example:

# Rename by ID
nipyapi.parameters.rename_parameter_context('ctx-id', 'new-name')

# Rename by name
nipyapi.parameters.rename_parameter_context('old-name', 'new-name')
nipyapi.parameters.set_inherited_parameter_contexts(context, inherited, mode='prepend', greedy=True, identifier_type='auto')[source]

Prepend or replace inherited contexts without changing local parameters.

The target is always re-read, so the update is built from its current inheritance rather than from a supplied entity.

Parameters:

  • context (ParameterContextEntity or str) – Target context, ID, or name.

  • inherited (list) – Context entities, IDs, or names in precedence order.

  • mode (str) – “prepend” puts the listed contexts first, in the given order, including any already inherited, and keeps the others after them; “replace” removes the others.

  • greedy (bool) – Allow partial name matching.

  • identifier_type (str) – “auto”, “id”, or “name” for string identifiers.

Returns:

Completed update and affected components.

Return type:

ParameterContextUpdateRequestDTO

Raises:

  • ValueError – Invalid mode, missing/ambiguous context, or failed update.

  • ApiException – NiFi rejects the update, including inheritance conflicts (409).

nipyapi.parameters.update_parameter_context(context)[source]

Update an already existing Parameter Context.

Wait for completion and delete the completed request. Request-level failures raise ValueError. Timeout or polling interruption does not cancel the update; see utils.wait_for_request for cleanup and error precedence.

Parameters:

context (ParameterContextEntity) – Parameter Context updated to be applied

Returns:

The updated Parameter Context

Return type:

ParameterContextEntity

nipyapi.parameters.update_parameter_in_context(context_id, param_name, value, create_if_missing=False)[source]

Update a parameter in a specific context, with safety checks.

By default, this function will only update a parameter that already exists in the specified context. This prevents accidental creation of shadowing parameters in inherited hierarchies.

Parameters:

  • context_id (str) – The ID of the parameter context to update

  • param_name (str) – Name of the parameter to update

  • value (str) – New value for the parameter

  • create_if_missing (bool) – If True, create the parameter if it doesn’t exist in this context. Default False (safe mode).

Returns:

Updated context

Return type:

ParameterContextEntity

Raises:

  • ValueError – If parameter not found and create_if_missing=False

  • ValueError – If context not found

Example:

>>> # Safe update - only if param exists in this context
>>> update_parameter_in_context(ctx_id, "Username", "newuser")

>>> # Create if missing (use with caution - may shadow inherited params)
>>> update_parameter_in_context(ctx_id, "NewParam", "value", create_if_missing=True)
nipyapi.parameters.update_parameter_provider(provider, properties, greedy=True, identifier_type='auto', allow_dynamic=False, refresh=True)[source]

Update provider properties, optionally refreshing the provider first.

Parameters:

  • provider (ParameterProviderEntity or str) – Provider entity, ID, or name.

  • properties (dict) – Property names and values; None clears a property.

  • greedy (bool) – Allow partial name matching.

  • identifier_type (str) – “auto”, “id”, or “name”.

  • allow_dynamic (bool) – Allow keys absent from static property descriptors.

  • refresh (bool) – Refresh the provider before updating. Defaults to True.

Returns:

Updated provider, with sensitive properties masked by NiFi.

Return type:

ParameterProviderEntity

Raises:

  • ValueError – If lookup is ambiguous or a property name is unknown.

  • TypeError – If properties is not a dictionary.

nipyapi.parameters.upload_asset(context_id, file_path=None, file_bytes=None, filename=None)[source]

Upload an asset to a parameter context.

Parameters:

  • context_id (str) – The parameter context ID

  • file_path (str) – Path to local file to upload (alternative to file_bytes)

  • file_bytes (bytes) – Raw bytes to upload (alternative to file_path)

  • filename (str) – Name for the asset (defaults to basename of file_path)

Returns:

Asset info with keys: id, name, digest

Return type:

dict

Raises:

  • ValueError – If neither file_path nor file_bytes provided

  • ValueError – If filename not provided when using file_bytes

Example:

>>> # Upload from file path
>>> asset = upload_asset(context_id, file_path="/path/to/driver.jar")

>>> # Upload from bytes with explicit filename
>>> asset = upload_asset(context_id, file_bytes=data, filename="driver.jar")
nipyapi.parameters.upsert_parameter_to_context(context, parameter, greedy=True, identifier_type='auto')[source]

Insert or Update Parameter within a Parameter Context

Parameters:

  • context (ParameterContextEntity or str) – The Parameter Context to Modify, as a ParameterContextEntity object, context ID, or context name.

  • parameter (ParameterEntity) – The ParameterEntity to insert or update

  • greedy (bool) – For name lookup, True for partial match, False for exact.

  • identifier_type (str) – How to interpret string identifier: “auto” (default) detects UUID vs name, “id” or “name” to force.

Returns:

The updated Parameter Context

Return type:

ParameterContextEntity

Raises:

  • TypeError – If context is not a string or ParameterContextEntity.

  • ValueError – If parameter context not found or multiple matches found.