Parameters

Parameter context management

For Managing NiFi Parameter Contexts

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

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.create_parameter_context(name, description=None, parameters=None, inherited_contexts=None)

Create a new Parameter Context with optional description and

initial Parameters

Parameters:

• name (str) – The Name for the new Context

• description (str) – An optional description

• parameters (list[ParameterEntity]) – A list of prepared Parameters

• inherited_contexts (list[ParameterContextEntity]) – A list of inherited Parameter Contexts

Returns:

The New Parameter Context

Return type:

ParameterContextEntity

nipyapi.parameters.delete_asset(context_id, asset_id)

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')

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')

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.get_parameter_context(identifier, identifier_type='name', greedy=True)

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)

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)

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, 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.list_all_parameter_contexts()

Lists all Parameter Contexts available on the Canvas

Returns:

list(ParameterContextEntity)

nipyapi.parameters.list_assets(context_id)

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()

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, description=None, sensitive=False)

Parses basic inputs into a Parameter object ready for submission

Parameters:

• name (str) – The Name for the Parameter

• value (str, int, float) – The Value for the Parameter

• 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

nipyapi.parameters.prepare_parameter_with_asset(name, asset_id, asset_name, description=None)

Prepare a parameter that references an asset.

Use this to update a parameter to point to an uploaded asset.

Parameters:

• name (str) – Parameter name

• asset_id (str) – ID of the asset to reference

• asset_name (str) – Name of the asset

• description (str) – Optional parameter description

Returns:

ParameterEntity ready for

use with update_parameter_context or upsert_parameter_to_context

Return type:

ParameterEntity

Example:

>>> # 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']
... )
>>> # Update the parameter context
>>> upsert_parameter_to_context(context, param)

nipyapi.parameters.remove_context_from_process_group(pg, greedy=True, identifier_type='auto')

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.update_parameter_context(context)

Update an already existing Parameter Context

Parameters:

• context (ParameterContextEntity) – Parameter Context updated to be applied

• refresh (bool) – Whether to refresh the object before Updating

Returns:

The updated Parameter Context

Return type:

ParameterContextEntity

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

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.upload_asset(context_id, file_path=None, file_bytes=None, filename=None)

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')

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.