Using Zowe to access the BMC Common REST API

You can access the Common REST API through the Zowe interface. Zowe is an open source software framework that provides solutions to allow development and operations teams to securely, manage, control, script, and develop on the Mainframe.

Some content is unavailable due to permissions.

You can now access CRA via Zowe versions 2.2.0 and 2.1.0, except version 2.0.0. If you are running version 2.0.0 of Zowe, you must upgrade to the version 2.2.0 of Zowe.

(BMC.AMIOPS.SPE2310)CRA now fulfills all of the requirements for version 2.9 of Zowe. 

This topic explains how to enable and then access CRA through Zowe.

The following procedures are available:

Related topics

Common-REST-API-administrative-procedures-and-general-endpoints

Using-Swagger-to-access-the-BMC-Common-REST-API

Enabling CRA in Zowe

For Zowe to be able to see Common REST API, you must set the Zowe-related parameters in the CRATCENV member in the &INSTALLHLQ.BMCSAMP data set.

(BMC.AMIOPS.SPE2310)

  1. Run the zwe script that is located in the bin folder of your Zowe installation. An example follows:

    zwe certificate pkcs12 create cert -d /shrd/zowe2.9/keystore -a cra -p password1234  -k myFolder --ca-alias local_ca --ca-password local_ca_password --domains abcd.eu.com

    The script generates the following files: 

    • cra.keystore.p12
    • cra.truststore.p12
      These files are located in the following location: /shrd/zowe2.9/keystore/myFolder
  2. Move these generated files to your Runtime folder in the USS directory.
  3. Run the job that starts your CRA on the mainframe.
  4. Search for the file that contains all the environment parameters and edit the file to set the following parameters:
    • IJO="$IJO -Dapiml.ssl.keypassword=<your password>"                   
    • IJO="$IJO -Dapiml.ssl.keystorepassword=<your password>"   
    • IJO="$IJO -Dapiml.ssl.keystoretype=PKCS12"     
    • IJO="$IJO -Dapiml.ssl.truststoretype=PKCS12"   
    • IJO="$IJO -Dapiml.ssl.truststorepassword=<your password>"  
    • IJO="$IJO -Dapiml.ssl.enabled=true"     
    • IJO="$IJO -Dapiml.ssl.verifycertificate=true"  
    • IJO="$IJO -Dapiml.ssl.protocol=TLSv1.2"    
    • IJO="$IJO -Dapiml.ssl.enabled-protocols=TLSv1.2"     
    • IJO="$IJO -Dapiml.ssl.keystore=${CRA_HOME}/<location of cra.keystore.p12>"  
    • IJO="$IJO -Dapiml.ssl.truststore=${CRA_HOME}/<location of cra.truststore.p12>"
  5. Save your changes and restart the CRA server started task.  
    After a few minutes, CRA is available in your Zowe interface. 

  1. Run the apiml_cm.sh script that is located in the bin folder of your Zowe installation as follows:

    ./apiml_cm.sh --action new-service --service-alias CRA --service-ext "SAN=dns:<FQDN>,dns:<hostname>,ip:<host_IP>" \
    --service-keystore  <keystore_location>/keystore  --service-truststore <truststore_location>/truststore  \
    --service-dname "<X.509_dname>"  \
    --service-password <password> --service-validity 3650
    --local-ca-filename "/<Zowe_CA_path>/localca"

    In the sample code, replace the variables as follows:

    Variable

    Description

    <FQDN>

    Fully Qualified Domain Name of your CRAserver

    <hostname>

    Host name of your CRA server

    <host_IP>

    IP address of your CRA server

    <keystore_location>

    Full path to the generated keystore

    This location must be accessible to the CRA server.

    <truststore_location>

    Full path to the generated truststore

    This location must be accessible to the CRA server.

    <X.509_dname>

    X.509 Distinguished Name used to identify entities which are named by the subject and issuer (signer) fields of X.509 certificates

    Example
    "CN=Zowe Service, OU=API Mediation Layer, O=Zowe Sample, L=Texas, S=Houston, C=USA"
    <password>

    Password to use for the creation of the keystore and truststore

    <Zowe_CA_path>

    Full path to your Zowe certificate authority

  2. Edit the CRATCENV member from the &INSTALLHLQ.BMCSAMP data set.
  3. Scroll to the Zowe settings section.

  4. Set the following parameters:

    Tip

    For the parameters specific to your Zowe installation, you can review the STDOUT log of the job that runs Zowe on your mainframe.

    Parameter

    Description

    -Dzowe.enable.deploy

    Set to true.

    -Dapiml.service.hostname

    Replace service_host with the host name of CRA.

    -Dapiml.service.port

    Enter the port number of your CRA installation.

    -Dapiml.service.ipaddress

    Enter the IP address of the LPAR where CRA is installed.

    -Dapiml.discovery.hostname

    Enter the host name of your Zowe Discovery server.

    -Dapiml.discovery.port

    Enter the port number of your Zowe Discovery server.

    -Dapiml.ssl.keypassword

    Replace empty with your SSL key password.

    -Dapiml.ssl.keystorepassword

    Replace empty with your SSL keystore password.

    -Dapiml.ssl.truststorepassword

    Replace empty with your SSL truststore password.

    -Dapiml.ssl.keystore

    Replace <Keystore_For_ML> with the location of the keystore created by the apiml_cm.sh script.

    -Dapiml.ssl.truststore

    Replace <Truststore_For_ML> with the location of the truststore created by the apiml_cm.sh script.

    -Dapiml.service.scheme

    Enter the Zowe service protocol type

    -Dapiml.enableurlencoded

    Set to true.

    -Dapiml.service.enableurlencoded

    Set to true.

    -Dapiml.discovery.scheme

    Enter the Zowe server protocol type.

    -Dapiml.ssl.keystoretype

    Enter the Zowe server keystore type.

    -Dapiml.ssl.truststoretype

    Enter the Zowe server truststore type.

    -Dapiml.ssl.enabled

    Set to false.

    -Dapiml.ssl.verifycertificate

    Set to true.

    -Dapiml.ssl.protocol

    To enable the protocol type such as TLSv1.2

    -Dapiml.ssl.enabled-protocols

    To enable the protocol type such as TLSv1.2

  5. After you finish updating the CRATCENV member restart the CRA server started task.  

After a few minutes, CRA is available in your Zowe interface. 


Setting the CRA log level

You can set the log level for CRA via Swagger or by updating the cralog4j2.xml file manually.  

To set the CRA log level via Swagger

  • Run the following API:
    http://<craHost>:<craPort>/cra/logger?logLevel=INFO&logName=ROOT

To set the CRA log level by updating the cralog4j2.xml

  • Edit the cralog4j2.xml file that is present in the USS directory of your server and set the required logger value in the Loggers section. 
    The valid values are OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, or ALL.

Accessing CRA in Zowe

  1. Login to Zowe.
  2. Click the tile labeled BMC Common REST API.
    Zowe_Interface.png
  3. Use CRA in Zowe in the same way as in Swagger.

    Zowe_CRA_Interface.png

A Swagger interface is also available directly. For more information, see Using-Swagger-to-access-the-BMC-Common-REST-API.

Disabling CRA in Zowe

  1. Edit the CRATCENV member from the &INSTALLHLQ.BMCSAMP data set.
  2. Scroll to the Zowe settings section.
  3. Set the -Dzowe.enable.deploy parameter to false.




 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*