Optional: Managing connection mappings during import

Data Virtualization Administrators can optionally control how connection IDs are mapped during import operations in Data Virtualization by running the MANAGE_CID_MAPPING stored procedure.

About this task

You can now optionally control how connection IDs (CIDs) are mapped from the source environment to your target environment during import operations. By using CID mappings, Data Virtualization maps the imported connection to a specific existing CID on the target instance. CID mapping is useful for connections that already exist in the target environment, or if the CID differs across environments.

Consider the following guidelines:
  • You can map your CIDs in both Git and non-Git (Data Virtualization APIs) migration workflows.
  • All CID mappings are stored persistently in the system table DVSYS.CID_IMPORT_MAPPINGS.
  • When a connection is imported and its CID is remapped, the mapping is automatically stored and reused for future imports, ensuring consistent behavior across subsequent import operations.
  • If there are no CID mappings defined, then Data Virtualization automatically generates new connection IDs during import.

Before you begin

  • You must be a Data Virtualization Administrator
  • You must have access to the Db2 CLI or the Data Virtualization RunSQL page

Syntax

This stored procedure has the following syntax:
CALL DVSYS.MANAGE_CID_MAPPING('<OPERATION TYPE>, ?);

Input parameters

OPERATION TYPE: This JSON string is a required parameter.

Replace <OPERATION TYPE> with the JSON string for set, list, get, delete, or clear.

Follow this workflow:
  1. Run this procedure with the set operation to establish connections mappings, which are saved to the DVSYS.CID_IMPORT_MAPPINGS table.
  2. Run this procedure with the list operation, to list all of the mappings, and to verify that they are correct.
  3. Proceed to import your Data Virtualization objects, which loads the mappings from the DVSYS.CID_IMPORT_MAPPINGS table.
  4. Use the get, delete or clear operations.

Operation types

The following list describes each operation, and features example calls and returns:
set a single mapping

Creates new CID mappings or updates existing ones, supporting one source‑to‑target CID mappings in the call.

Requirements: Requires the connection ID map (cid_map) array, with objects containing the source connection ID (source_cid) and the target source ID (target_cid).

Example JSON string:
{"operation":"set","cid_map":[{"source_cid":"DB210160","target_cid":"DB210143"}

Example call:

CALL DVSYS.MANAGE_CID_MAPPING('{"operation":"set","cid_map":[{"source_cid":"DB210000","target_cid":"DB210050"}]}', ?);
Return: 
{"status":"success","count":1}
set multiple mappings (batch)

Creates new CID mappings or updates existing ones, supporting multiple source‑to‑target CID mappings in the call.

Requirements: Requires the connection ID map (cid_map) array, with objects containing the source connection ID (source_cid) and the target source ID (target_cid).

Example JSON string: 
{"operation":"set","cid_map":[{"source_cid":"DB210000","target_cid":"DB210050"},{"source_cid":"DB210001","target_cid":"DB210051"},{"source_cid":"DB210002","target_cid":"DB210052"}

Example call:

CALL DVSYS.MANAGE_CID_MAPPING('{"operation":"set","cid_map":[{"source_cid":"DB210000","target_cid":"DB210050"},{"source_cid":"DB210001","target_cid":"DB210051"},{"source_cid":"DB210002","target_cid":"DB210052"}]}', ?)
Return: 
{"status":"success","count":3}
list all mappings

Lists all CID mappings currently persisted in the DVSYS.CID_IMPORT_MAPPINGS table.

Example JSON string:
{"operation":"list"}

Example call:

CALL DVSYS.MANAGE_CID_MAPPING('{"operation":"list"}', ?);
Return: 
Returns: {"status":"success","operation":"list","cid_map":[...],"count":5}
get mapping by source_cid or target_cid (might return multiple mapping)

Retrieves CID mapping details for a given source_cid or target_cid, and which might return multiple mappings.

Requirements: Requires the source connection ID (source_cid) or the target connection ID (target_cid).

Example JSON string with source_id:
{"operation":"get","source_cid":"DB210160"}
Example call:
CALL DVSYS.MANAGE_CID_MAPPING('{"operation":"get","source_cid":"DB210000"}', ?);
Return: 
{"status":"success","source_cid":"DB210000","target_cid":"DB210050"}
Example JSON string with target_cid:
{"operation":"get","target_cid":"DB210050"}
Example call:
CALL DVSYS.MANAGE_CID_MAPPING('{"operation":"get","target_cid":"DB210050"}', ?);
Return:
{"status":"success","cid_map":[{"source_cid":"DB210000","target_cid":"DB210050"}],"count":1}
delete mapping by source_cid

Deletes CID mappings based on a specific source_cid.

Example JSON string:
{"operation":"delete","source_cid":"DB210000"}

Example call:

CALL DVSYS.MANAGE_CID_MAPPING('{"operation":"delete","source_cid":"DB210000"}', ?);
Return: 
{"status":"success","deleted":1}
delete mapping by target_cid

Deletes CID mappings based on a specific target_cid.

Example JSON string:
{"operation":"delete","target_cid":"DB210050"}

Example call:

CALL DVSYS.MANAGE_CID_MAPPING('{"operation":"delete","target_cid":"DB210050"}', ?);
Return: 
{"status":"success","deleted":1}
delete mapping by exact pair

Deletes CID mappings based on an exact source_cid–target_cid pair.

Requirements: Requires the source connection ID (source_cid), target connection ID (target_cid) or the connection ID map array (cid_map).

Example JSON string:
{"operation":"delete","source_cid":"DB210000","target_cid":"DB210050"}

Example call:

CALL DVSYS.MANAGE_CID_MAPPING('{"operation":"delete","source_cid":"DB210000","target_cid":"DB210050"}', ?);
Return: 
{"status":"success","deleted":1}
delete multiple mapping pairs (batch)

Deletes CID mappings based on multiple exact source_cid–target_cid pairs.

Requirements: Requires the source connection ID (source_cid), target connection ID (target_cid) or the connection ID map array (cid_map).

Example JSON string:
{"operation":"delete","cid_map":[{"source_cid":"DB210000","target_cid":"DB210050"}{"source_cid":"DB210001","target_cid":"DB210051"}

Example call:

CALL DVSYS.MANAGE_CID_MAPPING('{"operation":"delete","cid_map":[{"source_cid":"DB210000","target_cid":"DB210050"}{"source_cid":"DB210001","target_cid":"DB210051"}]}', ?);
Return: 
{"status":"success","deleted":2}
clear all mappings

Removes all CID mappings from the DVSYS.CID_IMPORT_MAPPINGS table.

Example JSON string: 
{"operation":"clear"}

Example call:

CALL DVSYS.MANAGE_CID_MAPPING('{"operation":"clear"}', ?);
Return: 
{"status":"success","deleted":5}