Integrating with IBM Z JCL Expert

By integrating with IBM Z JCL Expert (also referred to as JCL Expert), from the Dynamic Workload Console V10.2.1 you can:

Invoke IBM JCL Expert when a job ends in error.
Verify the output of the JCL check in a new panel.
Speed up the debug process.
Automatically validate your JCL coding to ensure compliance with custom rules.

Before you begin

Before using the JCL Expert tool, ensure that you have:

Connected to a Dynamic Workload Console V10.2.1, or later.
Configured the systems on which you are working inside the same sysplex.
Set the JCLCHECKHOSTNAME, JCLCHECKPORT, and JCLCHECKTOKEN parameters in the HTTPOPTS statement.
Note: If in HTTPOPTS JCLCHECKHOSTNAME you have set the host name and not the IP address, you must edit the /etc/hosts file by adding the following line:
```
JclExpert_ip_instance     JclExpert_hostname_instance
```
where:

JclExpert_ip_instance

IP address of the system where JCL Expert is installed.

JclExpert_hostname_instance

Host name of the system where JCL Expert is installed.
Generated an API Mediation Layer Authentication token, as described in Generating an API Mediation Layer Authentication token.
Added the certificates to the key ring, as described in Add the Zowe API ML certificates to your key ring.

Generating an API Mediation Layer Authentication token

To authenticate to JCL Expert, you are required to generate an API Mediation Layer Authentication token that you will set in HTTPOPTS JCLCHECKTOKEN by performing the following steps:

Navigate to the API Catalog Gateway:
```
https://{gateway_URL}:{gateway_port}/apicatalog/ui/v1/#/tile/apimediationlayer/gateway
```
where:

gateway_URL

The URL to the API Catalog Gateway.

gateway_port

The port number to the API Catalog Gateway.
Log in to the API Catalog with your credentials.
Click the API Mediation Layer API service.
Select the API Gateway tab.
To authorize your credentials and return an authentication token, click the lock next to the POST /auth/login command
Provide your user name and password and click Authorize.
Click Close.
Click POST /auth/login, then click Try it out.
Edit the Request Body section by deleting all of its content, then click Execute.
You see that the Server Response is set to 204 Authenticated.
Right-click any place in the window and select Inspect.
Depending on the browser you are using, in the right upper frame of the window select the tab where the Cookies are available.
Expand the Cookies item and click the URL of the current API Catalog.
In the table of cookies that is displayed, click apimlAuthenticationToken and copy the Cookie Value that is shown at the bottom of the frame. This value must be set in the JCLCHECKTOKEN parameter of the HTTPOPTS statement.

Note: By default, the token expiration is set to 8 hours. To modify the token expiration value, see the Zowe documentation.

Add the Zowe API ML certificates to your key ring

To add the certificates that you have downloaded from your Zowe API ML to a key ring that is trusted by IBM Z Workload Scheduler, perform the following steps:

If you use a SAF ring

Create the sequential data sets where the downloaded certificates are to be stored. In this procedure, the certificates JCLEXPERT.CERT.ROOT and JCLEXPERT.CERT.SERVER are used as an example.
If your certificate is chained, you must create a data set for each intermediate or root certificate and save them.
Create a key ring (in this example, EQQRING) by using the certificates management command RACDCERT. Skip this step if you already use a key ring for HCL Workload Automation for Z services. (For more information about the RACDCERT command, see the section RACDCERT (Manage RACF digital certificates) in the IBM z/OS Server Security RACF Command Language Reference manual).
```
RACDCERT ADDRING(EQQRING) ID(Your_RACF_userID)
```

Add each certificate to the RACF database:

RACDCERT CERTAUTH ID(Your_RACF_userID) ADD('JCLEXPERT.CERT.ROOT') TRUST WITHLABEL('JCLEXPERT ROOT')

RACDCERT CERTAUTH ID(Your_RACF_userID) ADD('JCLEXPERT.CERT.SERVER') TRUST WITHLABEL('JCLEXPERT SERVER')

Connect each certificate to the EQQRING key ring :

RACDCERT ID(Your_RACF_userID) CONNECT(LABEL('JCLEXPERT ROOT') RING(EQQRING) USAGE(CERTAUTH)

RACDCERT ID(Your_RACF_userID) CONNECT(LABEL('JCLEXPERT SERVER') RING(EQQRING) USAGE(CERTAUTH)

Check that the certificates have been successfully added to the chain:
```
RACDCERT ID(Your_RACF_userID) LISTCHAIN(LABEL('JCLEXPERT SERVER')
```
Update the SSL parameters in the HTTPOPTS statement according to the values that you have set in this procedure.

If you use the keystore in the UNIX System Services

Save the downloaded certificates into a USS directory. In this procedure, /u/mycerts is used as an example.
If your certificate is chained, you must create a file for each intermediate or root certificate and save them.
From /u/mycerts, create a keystore database (in this procedure, the gskkyman utility is used). Skip this step if you already use a database for HCL Workload Automation for Z services.
```
gskkyman
```
From the Database Menu, select option 1 - Create new database. Skip this step if you already use a database for HCL Workload Automation for Z services.On completion, the following message is issued:
```
Key database /u/mycerts/my_db_name.kdb created
```
To store your database password in a file, from the Key Management Menu select option 10 - Store database password. Skip this step if you already use a database for HCL Workload Automation for Z services.
On completion, the following message is issued:
```
Database password stored in /u/mycerts/my_db_name.sth
```
From the Database Menu, select option 2 - Open database and enter the key database name and database password.
Import each certificate to your keystore database by selecting option 7 - Import a certificate from the Key Management Menu.
Based to the values that you set in this procedure, update the SSL parameters in the HTTPOPTS statement.

About this task

To use JCL Expert, from the Dynamic Workload Console:

Select Monitor & Reporting >Monitor Workload.
Select the engine to connect and set Job as the object type, then click Run.
The Monitor Workload panel displays, showing you all the jobs in the plan.
Select the job in error whose JCL you want to check, then from the More Actions menu select Edit JCL.
The Edit JCL panel displays, showing you the JCL for the job. You can edit it or leave as it is.
Click Save and reopen the job in error.
Click the JCL Check button to validate the JCL syntax through the JCL Expert tool. A pop-up window displays showing you a list of the errors found.
After making the required changes, click Save to save the corrected JCL.