Insert an extra PROD Site for 1500 Existing DFZ Packages
Challenge
Find all existing DFZ packages (a) for which the install date has not yet passed and (b) which already have site S2SFO as one of their production target sites. For all such packages, insert an additional production site S2BRU with a planned production install date identical to the date from S2SFO.
Solution
Here is the basket we created to address this challenge:
All that’s left to do is to have ASC process the above basket (via a single batch job). This job is expected to complete in approximately 13 minutes without overloading the CMN started task while skipping/ignoring packages that already include S2BRU. After the job completes, we can be sure that all 1567 packages will also be installed in the S2BRU site (around the same time these packages will be installed in S2SFO).
Key Features Used in ASR and ASC
To complete this challenge, we used a combination of ASR and ASC, along with some special features beyond the typical ASR/ASC functionalities, including:
• Searching for packages for which no XML search facilities are available (refer to Step 1 below for more details)
• XML variations (refer to Step 6 below for more details)
• XML chunking (refer to Step 8 below for more details)
We are ensuring that S2SFO is included in all 1567 packages. Based on our estimates, only 5-10% of these packages likely already contain this site. While we could verify the exact number beforehand, ASC efficiently handles and skips these cases, so we chose to skip this additional check to save time. All that’s left is for ASC to process this basket using the XML service SITE/PKG/CREATE.
Steps to build the basket (= ASR & ASC in action)
In short: Use ASR (steps 1 & 2) to generate a report in basket format, followed by ASC (steps 3 to 8) to process the basket. The basket specifications (= ASR report design) are based on a variation of PRDSITES (= one of the 150+ reports included with ASR).
Step 1:
Use ASR to build a report (in basket format) using the following report specifications. This report is actually a variation of PRDSITES (one of the 150+ out-of-the-box reports shipped with ASR).
Additional details on how we tuned the delivered report to fit our current use case:
Filtering by planned installation date: We only want to apply this operation to packages where the planned installation date has not yet expired. This is achieved using the line “GE &TODAY”, which means “greater than or equal to today’s date.”
“&TODAY” is a report variable that is automatically replaced by the current date at runtime.Filtering by site S2SFO: Our update should only apply to packages that already include site S2SFO in their U7 panel (i.e., the package is requested to be installed in site S2SFO). This is controlled by the line “EQ #RPTV_SITE_NAME”, ensuring that the output (basket) only contains records for such packages. “#RPTV_SITE_NAME” is a report runtime variable, meaning its value is entered by the user before running the report. In this case, we set the value to “S2SFO” to match our criteria.
Step 2:
After the job submitted in the previous step is completed (it took only about 1 minute of elapsed time to search approximately 20,000 packages), the generated report (basket) looked like this:
Note that we intentionally included the column ‘department number’ (XML tag = requestorDept) because it allowed us to quickly verify that no packages were selected with a special department number (e.g., TRSH, which we do not want to process).
Step 3:
Using ASC’s basket processing, and in preparation for using the XML service SITE/PKG/CREATE, we filtered out some tags (columns) from the last basket (CHGMAN.B.ASR.CMB.RPTL(PRDSITES)), as shown here using ASC’s “ignore tags” feature:
After ignoring these tags, here is the shortlist of available XML services that can be applied to this basket. There are actually 12 candidate XML services, but we know we only want to work with the SITE services, which is why we added that as an extra filter.
With this shortlist of only four XML services, we can complete the rest of our task:
Execute SITE/PKG/LIST to retrieve all site information (such as planned install dates, primary contacts, etc.) for site S2SFO, and save it as a new basket.
Edit the new basket using ISPF edit to perform a mass update, changing S2SFO to S2BRU.
Apply (execute) SITE/PKG/CREATE to the edited basket.
More details on completing these remaining tasks are provided below.
Step 4:
On the last ASC screen shown above, simply use the command “ex” to execute the XML service SITE/PKG/LIST for each record in CHGMAN.B.ASR.CMB.RPTL(PRDSITES). Ensure that the XML results are saved as a new basket, which will look like this (only the first 72 columns shown below; shifting right would reveal additional columns such as toInstallTime<contactName<contactPhone<, etc.):
Step 5:
Use ISPF edit to perform a mass update of the basket CHGMAN.B.ASC.BSK.PRDSITES.S2SFO by changing S2SFO to S2BRU (using the ISPF edit command ‘c <S2SFO< <S2BRU<’). Then, save the edited basket with a DSN like CHGMAN.B.ASC.BSK.PRDSITES.S2SFO.EDT. Its content should now look like this:
Step 6:
Attention
At this point, it might be tempting to simply launch (= use) the edited basket CHGMAN.B.ASC.BSK.PRDSITES.S2SFO.EDT to have the XML service SITE/PKG/CREATE run for each record in the basket.
However, attempting this will result in ASC not allowing execution, because SITE/PKG/CREATE is not 100% compatible with SITE/PKG/LIST. To proceed, we first need to make them compatible.
To identify the exact compatibility issue, we use ASC’s “XML variations” feature, as shown in the next screen. Here, we compare the RESULT tags from SITE/PKG/LIST with the REQUEST tags from SITE/PKG/CREATE to determine the differences.
This will generate an (online) report that tells us what the (minor) differences between these two XML services are, and it looks like this:
The report above reveals that to execute the XML service SITE/PKG/CREATE, the input tags applName and packageId are not accepted. This is the actual compatibility issue that needs to be resolved, as detailed in the next step. However, the tag package is considered compatible since it is used in both XML services.
Step 7:
Based on what we learned in the previous step, we can now proceed with launching the edited basket CHGMAN.B.ASC.BSK.PRDSITES.S2SFO.EDT: All we need to do is use the “ignore tags” feature again, as shown below:
After ignoring these two tags, the XML service SITE/PKG/CREATE is now compatible. All remaining tags are accepted as request tags for XML service SITE/PKG/CREATE, and the complete list of these tags perfectly matches the result tags produced by running SITE/PKG/LIST.
Step 8:
Attention
To process all 1,567 XML requests, we must minimize the impact on the ChangeMan ZMF started task to prevent performance issues for other users. To achieve this, we will use ASC’s “XML chunking” feature, which splits the 1,567 XML requests into smaller chunks (e.g., 20 requests per chunk), with a 10-second wait time between each chunk. This means we will have 79 chunks and a total wait time of 79 × 10 seconds = approximately 13 minutes. As a result, the total elapsed time for the job to process all XML requests will be around 13 minutes.
While processing this final basket, we may encounter a few XML errors indicating that some packages already contain the S2BRU site. If this happens, no problem—this simply means that some ChangeMan ZMF users couldn’t wait for our mass update to complete and manually inserted S2BRU into their package. These cases can be safely ignored and will not affect the overall process.
Variation 1: Last Year Instead of Next Year
The above process applies to packages with a planned install date in the future (as defined by “GE &TODAY”in Step 1). However, we wouldn’t be surprised if a related request comes up soon, such as: “Can you do the same for packages with a planned install date less than one year ago?” In that case, all that’s needed is to change “GE &TODAY” to “GE &TODAY - 365”.
However, we’d likely need a few extra steps between Step 1 and Step 2 to prevent attempting to insert an extra site using SITE/PKG/INSERT for packages with a planned install date in the past:
Create a basket of all packages with a planned install date “LT &TODAY”, across all sites where they are planned to be installed (not just for S2SFO). This can be done by omitting the condition “EQ #RPTV_SITE_NAME” from the query.
Apply the XML service SITE/PKG/UPDATE to update the planned install dates to the current date or some future date.
Variation 2: Remove A PROD Site
The above approach focuses on adding a new PROD site (S2BRU). However, if the request were instead to remove an obsolete PROD site (e.g., S2OLD), then the process would be slightly different. All that’s needed is:
Use S2BRU instead of S2SFO in Step 1.
Skip Step 2 (no need for any edits).
Process the output from Step 1 in Step 3 instead of Step 2.
Use XML service SITE/PKG/DELETE instead of SITE/PKG/INSERT.
Discover More Ways to Leverage SCM Commander or Reporter
