Example – Catalog-to-catalog deployment

Edit online

This example procedure shows how to deploy the Db2 objects in a catalog-to-catalog release.

Requirements

Table 1. Requirements for catalog-to-catalog deployment
Requirement Description
User Db2 CD administrator or Db2 CD operator
Note: If you are a Db2 CD administrator, you can skip the APPROVE action in Step 2.
Purpose To deploy Db2 objects from one environment to another in a defined deployment path for a catalog-to-catalog release.
Prerequisites Before you create a deployment plan for a catalog-to-catalog release, you must ensure that the following are in place:
  • A catalog release, for example RD1, is created on a defined path with a catalog manifest. To know how to create a release, see Example for release type - Catalog-to-catalog.
  • The catalog manifest used in the release has at least one include filter to include object definitions from the catalog in the FAM for deployment.
  • The deployment path is defined to include the required source and target deployment environments.
  • Manifest is evaluated against the initiating source environment to verify that the desired objects are included.
  • Manifest is activated.
Deployment type Catalog-to-catalog

Description

In this example, you deploy Db2 objects from environment E2 (development node) to environments E3, E4, and E5 (QA nodes), as shown in the diagram for the Blue path. Then, you repeat the same process (CREATE -> APPROVE -> RUN) to deploy the objects from E3 (primary peer) to the next node (E6) in the deployment path.

Step 1 – CREATE the plan

Who can perform: Db2 CD administrator or Db2 CD operator

  1. Open the POST Deployment plan (/manageddeployments/release/{releaseUUIDOrName}/deploymentPlan) API, click Try it out and provide the required values to create the request.
    Table 2. Parameters for a catalog-to-catalog deployment
    Parameter User Input
    action

    (query)

    		 CREATE
    includePlanSummary

    (query)

    		 true
    recordJobResponse

    (query)

    		 true
    runUnapprovedPlan

    (query)

    		 true
    releaseUUIDOrName

    (path)

    		 RD1
    deploymentPlanRequest

    (body)

    		 
    {
  "comment": "This is a create call", 
}
    Click Execute.

    The CREATE action returns a uniqueId. A subsequent GET using this uniqueId shows status="CREATED" and provides the promotionPlanList containing the plan identifiers that you use in the next actions.

    Response
    {
"returnCode": "SUCCESS",
"messages": [],
"result": {"uniqueId": "86c5c99f-ce00-4c93-9bac-4c653ddbed0f",
"status": "IN_PROGRESS",
"promotionPlanList": [],
"sourceOutOfBandChangeList": null,
"targetOutOfBandChangeList": [],
"sourcePendingChangeList": null,
"targetPendingChangeList": null,
"sourceAndTargetEnvironmentDetails": null
}
}
  2. Copy the uniqueId from CREATE response.
  3. To retrieve created plan details, open the GET Get deployment plan details by unique Id API, click Try it out, an provide the uniqueId value from the CREATE response.
    Parameter User Input
    uniqueId

    (query)

    		 86c5c99f-ce00-4c93-9bac-4c653ddbed0f
    releaseUUIDOrName

    (path)

    		 RD1
    Click Execute.
    Response
    {
  "returnCode": "SUCCESS",
  "messages": [
    "IZPAN0022I - Deployment plan with plan id 'ff8482e3-a6d7-439b-8e8c-40b976f168f214' is created successfully for environment 'E5'.",
    "IZPAN0022I - Deployment plan with plan id 'ff8482e3-a6d7-439b-8e8c-40b976f168f212' is created successfully for environment 'E3'.",
    "IZPAN0022I - Deployment plan with plan id 'ff8482e3-a6d7-439b-8e8c-40b976f168f213' is created successfully for environment 'E4'."
  ],
  "data": {
    "uniqueId": "86c5c99f-ce00-4c93-9bac-4c653ddbed0f",
    "status": "CREATED",
    "promotionPlanList": [
      {
        "promotionPlanEnvUUID": "846ad378-50d0-44e5-9476-2df71c6385d3",
        "promotionPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f212",
        "recoveryPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f212_RCVR",
        "status": "CREATED",
        "jobDetails": {
             "jobID": "J0000001",
             "jobName": "<job_name>",
             "targetURL": "<URL_path_job_details>",
             "submissionTimestamp": "2025-02-05T11-22-03Z",
             "submissionUserId": "USR1234",
             "loggedInUserId": "USR1234",
             "returnCode": 4,
             "completionDetectionTimestamp": "2025-02-05T11-22-33Z",
             "errorMessage": null
        },
        "planSummary": [
              " ... <COMPARISON Summary will be here - omitted for brevity >..."
        ],  
        "planSummaryInJsonFormat": [
          {
            "Title": "COMPARISON SUMMARY REPORT",
            "Headings": [
              "Obtyp",
              "Source Object",
              "Target Object",
              "Result",
              "Object type"
            ],
            "Results": [
                "Obtyp": "D",
                "Source Object": "",
                "Target Object": "E3DB",
                "Result": "Dropped",
                "Object type": "Database",
                "parentIndex": -1
              }
            ]
          }
        ],
        "proxyUserName": null,
        "sqlId": null,
        "changeOwner": "DBUSR12"
      },
      {
        "promotionPlanEnvUUID": "c01dacd3-f220-4f0f-91dc-89ad8183166d",
        "promotionPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f214",
        "recoveryPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f214_RCVR",
        "status": "CREATED",
        "jobDetails": {
             "... <job details - omitted for brevity> ..." 
        },
        "planSummary": "COMPARISON Summary Report will be here" 
        "planSummaryInJsonFormat": [
          {
            "Title": "COMPARISON SUMMARY REPORT",
            "Headings": [
              "Obtyp",
              "Source Object",
              "Target Object",
              "Result",
              "Object type"
            ],
            "Results": 
                "Obtyp": "D",
                "Source Object": "",
                "Target Object": "E5DB",
                "Result": "Dropped",
                "Object type": "Database",
                "parentIndex": -1
              }
            ]
          }
        ],
        "proxyUserName": null,
        "sqlId": null
      },
      {
        "promotionPlanEnvUUID": "b5575e9a-a952-49ff-b6c8-416124b99309",
        "promotionPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f213",
        "recoveryPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f213_RCVR",
        "status": "CREATED",
        "jobDetails": {
             "... <job details - omitted for brevity> ..." 
        },
        "planSummary": "COMPARISON Summary Report will be here" 
        "planSummaryInJsonFormat": [
          {
            "Title": "COMPARISON SUMMARY REPORT",
            "Headings": [
              "Obtyp",
              "Source Object",
              "Target Object",
              "Result",
              "Object type"
            ],
            "Results": 
                "Obtyp": "S",
                "Source Object": "",
                "Target Object": "E4DB.NWTTS1",
                "Result": "Dropped",
                "Object type": "Tablespace",
                "parentIndex": -1
              }
            ]
          }
        ],
        "proxyUserName": null,
        "sqlId": null
      }
    ],
    "sourceOutOfBandChangeList": null,
    "targetOutOfBandChangeList": [],
    "sourcePendingChangeList": null,
    "targetPendingChangeList": null,
    "sourceAndTargetEnvironmentDetails": {
      "sourceEnvironmentsList": [
        {
          "envUUID": "c4e01061-08a0-41d5-bed8-39741f4dcb1e",
          "envName": "E2",
          "landscapeUUID": "cf58bbc0-d90b-4f21-9852-ff1f6c4e7986",
          "landscapeName": "Development",
          "sourceType": "INITIATING_SOURCE",
          "primary": true
        }
      ],
      "targetEnvironmentsList": [
        {
          "envUUID": "846ad378-50d0-44e5-9476-2df71c6385d3",
          "envName": "E3",
          "landscapeUUID": "40e67b3e-1585-48fb-93e4-221d24e7c255",
          "landscapeName": "QA",
          "targetType": "TARGET_IN_S_T_PAIR"
        },
        {
          "envUUID": "b5575e9a-a952-49ff-b6c8-416124b99309",
          "envName": "E4",
          "landscapeUUID": "40e67b3e-1585-48fb-93e4-221d24e7c255",
          "landscapeName": "QA",
          "targetType": "TARGET_IN_S_T_PAIR"
        },
        {
          "envUUID": "c01dacd3-f220-4f0f-91dc-89ad8183166d",
          "envName": "E5",
          "landscapeUUID": "40e67b3e-1585-48fb-93e4-221d24e7c255",
          "landscapeName": "QA",
          "targetType": "TARGET_IN_S_T_PAIR"
        }
      ]
    }
  }
}
    Tip: For failed deployment actions, review the jobDetails section in the response in addition to the returned error messages. The job details include JES job identifiers, return codes, timestamps, and job output links, which can help you further diagnose the failure.
  4. From the GET response, copy the plan identifiers that were generated for each target environment. Copy the following promotionPlanList details for each of the three plans:
    • promotionPlanEnvUUID
    • promotionPlanID
    • recoveryPlanID
    • changeOwner (if present)

Step 2 – APPROVE the plan (recommended)

Who can perform: Db2 CD administrator only

  1. Open the POST Deployment plan API, click Try it out, and paste the three sets of promotionPlanList entries in the request for approval.

    If the CREATE response shows changeOwner for a plan, carry the same value to the APPROVE and RUN requests for that same promotionPlanList entry.

    Parameter User Input
    action

    (query)

    		 APPROVE
    includePlanSummary

    (query)

    		 true
    recordJobResponse

    (query)

    		 true
    runUnapprovedPlan

    (query)

    		 true
    releaseUUIDOrName

    (path)

    		 RD1
    deploymentPlanRequest

    (body)

    		 
    {
  "comment": "This is an approve call",
  "promotionPlanList": [
      {
        "promotionPlanEnvUUID": "846ad378-50d0-44e5-9476-2df71c6385d3",
        "promotionPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f212",
        "recoveryPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f212_RCVR",

        "changeOwner": "DBUSR12"
      },
      {
        "promotionPlanEnvUUID": "c01dacd3-f220-4f0f-91dc-89ad8183166d",
        "promotionPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f214",
        "recoveryPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f214_RCVR"
      },
      {
        "promotionPlanEnvUUID": "b5575e9a-a952-49ff-b6c8-416124b99309",
        "promotionPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f213",
        "recoveryPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f213_RCVR"
      }
    ]
}
    Click Execute.
    Response
    {
   "returnCode": "OK",
   "messages": [],
   "message": "SUCCESS",
   "data": {
      "uniqueId": "cb92944f-c992-4eb2-b13c-da7ba9350c11",
      "status": "IN_PROGRESS",
      "promotionPlanList":[],
      "sourceOutOfBandChangeList": null,
      "targetOutOfBandChangeList": [],
      "sourcePendingChangeList": null,
      "targetPendingChangeList": null,
      "sourceAndTargetEnvironmentDetails": null
   }
}
  2. To check the approval status, open the GET Get Deployment plan details by unique Id API and provide the uniqueId value from the previous response.

    The plan moves to status="APPROVED". Operators can now RUN the plan.

    Exception to APPROVE: A Db2 CD administrator can set runUnapprovedPlan to true and directly RUN the deployment plan without a prior APPROVE.

Step 3 – RUN the plan

Who can perform: Db2 CD administrator (with or without approval) or Db2 CD operator (only after approval)

  1. Open the POST Deployment plan API, click Try it out, and use the same three sets of promotionPlanList entries for the RUN action.

    If the CREATE response shows changeOwner for a plan, carry the same value to the RUN request for that same promotionPlanList entry.

    Parameter User Input
    action

    (query)

    		 RUN
    includePlanSummary

    (query)

    		 true
    recordJobResponse

    (query)

    		 true
    runUnapprovedPlan

    (query)

    		 true
    releaseUUIDOrName

    (path)

    		 RD1
    deploymentPlanRequest

    (body)

    		 
    {
  "comment": "This is a run call",
  "promotionPlanList": [
      {
        "promotionPlanEnvUUID": "846ad378-50d0-44e5-9476-2df71c6385d3",
        "promotionPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f212",
        "recoveryPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f212_RCVR",
        "changeOwner": "DBUSR12"

      },
      {
        "promotionPlanEnvUUID": "c01dacd3-f220-4f0f-91dc-89ad8183166d",
        "promotionPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f214",
        "recoveryPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f214_RCVR"
      },
      {
        "promotionPlanEnvUUID": "b5575e9a-a952-49ff-b6c8-416124b99309",
        "promotionPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f213",
        "recoveryPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f213_RCVR"
      }
    ]
}
    Click Execute.
    Response
    {
   "returnCode": "OK",
   "messages": [],
   "message": "SUCCESS",
   "data": {
      "uniqueId": "3c0c7868-ebf5-4f23-94b4-335e0df3ddec",
      "status": "IN_PROGRESS",
      "promotionPlanList": [],
      "sourceOutOfBandChangeList": null,
      "targetOutOfBandChangeList": [],
      "sourcePendingChangeList": null,
      "targetPendingChangeList": null,
      "sourceAndTargetEnvironmentDetails": null
   }
}
  2. Copy the uniqueId from the RUN response.
  3. To check the deployment status, open the GET Get deployment plan details by unique Id API, click Try it out, and provide the uniqueId value from the RUN response.
    Parameter User Input
    uniqueId

    (query)

    		 3c0c7868-ebf5-4f23-94b4-335e0df3ddec
    releaseUUIDOrName

    (path)

    		 RD1
    Click Execute.
    Response
    {
  "returncode": "OK",
  "messages": [], 
  "message": "SUCCESS",
  "detailedMessages": [
    "IZPAN0024I - Deployment plan with plan id 'ff8482e3-a6d7-439b-8e8c-40b976f168f214' is executed successfully for environment 'E5'.",
    "IZPAN0024I - Deployment plan with plan id 'ff8482e3-a6d7-439b-8e8c-40b976f168f213' is executed successfully for environment 'E4'.",
    "IZPAN0024I - Deployment plan with plan id 'ff8482e3-a6d7-439b-8e8c-40b976f168f212' is executed successfully for environment 'E3'."
  ],
    "data": {
    "uniqueId": "3c0c7868-ebf5-4f23-94b4-335e0df3ddec",
    "status": "EXECUTED",
    "sourceObjects": [
      {
        "name": "NWTTB1",
        "type": "TB",
        "qualifier": "NWTMD",
        "objUUID": "dc459007-b0df-47c5-a70c-1a26d56928cf",
        "include": [
          {
            "manifestUUID": "421c045b-f5f1-48d9-971c-934291a455d6",
            "manifestObjectGUId": "2025-02-05 09:52:33.425677",
            "inclusionReason": "INCLUDED",
            "timestamp": "2025-02-05T11:38:18.883Z"
          }
        ]
      },
      {
        "name": "NWTIX1",
        "type": "IX",
        "qualifier": "NWTMD",
        "objUUID": "e9002fdd-394d-45d2-b90f-40c80fe246ac",
        "includedBy": [
          {
            "name": "NWTTB1",
            "type": "TB",
            "qualifier": "NWTMD",
            "inclusionReason": "REQUIRED",
            "timestamp": "2025-02-05T11:38:19.378Z"
          }
        ]
      },
      {
        "name": "NWTTS1",
        "type": "TS",
        "qualifier": "MDDB",
        "objUUID": "b7586420-b2b0-4e5e-b637-142a0a4b461c",
        "includedBy": [
          {
            "name": "NWTTB1",
            "type": "TB",
            "qualifier": "NWTMD",
            "inclusionReason": "REQUIRED",
            "timestamp": "2025-02-05T11:38:19.378Z"
          }
        ]
      }
    ],
    "promotionPlanList": [
      {
        "promotionPlanEnvUUID": "c01dacd3-f220-4f0f-91dc-89ad8183166d",
        "promotionPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f214",
        "recoveryPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f214_RCVR",
        "status": "EXECUTED",
        "jobDetails": {
             "jobID": "J0000002",
             "jobName": "<job_name>",
             "targetURL": "<URL_path_job_details>",
             "submissionTimestamp": "2025-02-05T11-37-03Z",
             "submissionUserId": "USR1234",
             "loggedInUserId": "USR1234",
             "returnCode": 4,
             "completionDetectionTimestamp": "2025-02-05T11-37-23Z",
             "errorMessage": null
        },
        "planSummary": null,
        "planSummaryInJsonFormat": null,
        "proxyUserName": null,
        "sqlId": null,
        "message": null,
        "detailedMessages": null,
        "releaseObjects": [
          {
            "name": "NWTTB1",
            "type": "TB",
            "qualifier": "NWTMD",
            "objUUID": "1f455342-1631-45fa-9be9-2063e0f56614"
          },
          {
            "name": "NWTTS1",
            "type": "TS",
            "qualifier": "MDDB",
            "objUUID": "0575038e-b6ec-4ec0-8e19-3cc1840af885"
          },
          {
            "name": "NWTTB1",
            "type": "TB",
            "qualifier": "NWTMD",
            "objUUID": "b7586420-b2b0-4e5e-b637-142a0a4b461c"
          }
        ]
      },
      {
        "promotionPlanEnvUUID": "b5575e9a-a952-49ff-b6c8-416124b99309",
        "promotionPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f213",
        "recoveryPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f213_RCVR",
        "status": "EXECUTED",
        "jobDetails": {
             "... <job details - omitted for brevity> ..."
        },
        "planSummary": null,
        "planSummaryInJsonFormat": null,
        "proxyUserName": null,
        "sqlId": null,
        "releaseObjects": [
          {
            "name": "NWTTB1",
            "type": "TB",
            "qualifier": "NWTMD",                        
            "objUUID": "1f455342-1631-45fa-9be9-2063e0f56614"
          },
          {
            "name": "NWTTS1",
            "type": "TS",
            "qualifier": "MDDB",
            "objUUID": "0575038e-b6ec-4ec0-8e19-3cc1840af885"
          },
          {
            "name": "NWTTB1",
            "type": "TB",
            "qualifier": "NWTMD",
            "objUUID": "e9002fdd-394d-45d2-b90f-40c80fe246ac"
          }
      },
      {
        "promotionPlanEnvUUID": "846ad378-50d0-44e5-9476-2df71c6385d3",
        "promotionPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f212",
        "recoveryPlanID": "ff8482e3-a6d7-439b-8e8c-40b976f168f212_RCVR",
        "status": "EXECUTED",
        "jobDetails": {
             "... <job details - omitted for brevity> ..."
        },
        "planSummary": null,
        "planSummaryInJsonFormat": null,
        "proxyUserName": null,
        "sqlId": null,
        "releaseObjects": [
          {
            "name": "NWTTB1",
            "type": "TB",
            "qualifier": "NWTMD",
            "objUUID": "1f455342-1631-45fa-9be9-2063e0f56614"
          },
          {
            "name": "NWTTS1",
            "type": "TS",
            "qualifier": "MDDB",
            "objUUID": "0575038e-b6ec-4ec0-8e19-3cc1840af885"
          },
          {
            "name": "NWTTB1",
            "type": "TB",
            "qualifier": "NWTMD",
            "objUUID": "e9002fdd-394d-45d2-b90f-40c80fe246ac"
          }
      }
    ],
    "sourceOutOfBandChangeList": null,
    "targetOutOfBandChangeList": [],
    "sourcePendingChangeList": null,
    "targetPendingChangeList": null,
    "sourceAndTargetEnvironmentDetails": {
      "sourceEnvironmentsList": [
        {
          "envUUID": "c4e01061-08a0-41d5-bed8-39741f4dcb1e",
          "envName": "E2",
          "landscapeUUID": "cf58bbc0-d90b-4f21-9852-ff1f6c4e7986",
          "landscapeName": "Development",
          "sourceType": "INITIATING_SOURCE",
          "primary": true
        }
      ],
      "targetEnvironmentsList": [
        {
          "envUUID": "846ad378-50d0-44e5-9476-2df71c6385d3",
          "envName": "E3",
          "landscapeUUID": "40e67b3e-1585-48fb-93e4-221d24e7c255",
          "landscapeName": "QA",
          "targetType": "TARGET_IN_S_T_PAIR"
        },
        {
          "envUUID": "b5575e9a-a952-49ff-b6c8-416124b99309",
          "envName": "E4",
          "landscapeUUID": "40e67b3e-1585-48fb-93e4-221d24e7c255",
          "landscapeName": "QA",
          "targetType": "TARGET_IN_S_T_PAIR"
        },
        {
          "envUUID": "c01dacd3-f220-4f0f-91dc-89ad8183166d",
          "envName": "E5",
          "landscapeUUID": "40e67b3e-1585-48fb-93e4-221d24e7c255",
          "landscapeName": "QA",
          "targetType": "TARGET_IN_S_T_PAIR"
        }
      ]
    }
  }
}

The Db2 objects are deployed from E2 to E3, E4, and E5 successfully.

To continue the release progression to the next node in the path, repeat the process to CREATE, APPROVE, and RUN a deployment plan for deploying objects from E3 (the primary peer in the QA landscape) to E6.

Step 4 – COMPLETE

  1. When you finish deploying objects to all target environments in the path and your deployment objectives are met, complete the release by calling the POST Deployment plan API with the COMPLETE action.
    Parameter User Input
    action

    (query)

    		 COMPLETE
    releaseUUIDOrName

    (path)

    		 EXT_R1
    deploymentPlanRequest

    (body)

    		 
    {
    "comment": "Release completed"
}
    Click Execute.

    A uniqueId is returned in the response.

  2. Open the GET Get deployment plan details by unique Id API and provide the uniqueId from the COMPLETE response.
    Parameter User Input
    uniqueId

    (query)

    		 7b74dbe2-d909-4d54-9bc5-1d3ea4c26b36
    releaseUUIDOrName

    (path)

    		 EXT_R1
    Click Execute.

    The response indicates that the Db2 objects were deployed successfully and the release has moved to the COMPLETE state. You cannot modify a release after it reaches the COMPLETE state.