Space banner


This space provides the same content as before, but the organization of the home page has changed. The content is now organized based on logical branches instead of legacy book titles. We hope that the new structure will help you quickly find the content that you need.

Setting up the Common REST API

This topic was edited by a BMC Contributor and has not been approved.  More information.

You use the Installation System to install the Common REST API (CRA). Before you install CRA, ensure that you have installed the latest ISU refresh. After you install, you must customize the Apache Tomcat server to work with the API and then deploy the API: 

Before you begin

Ensure that Tomcat, the required data set members, and PTF BQY2284 are installed: 

  1. If Tomcat is not installed on your mainframe, install it as follows:


    Because BMC has tested the Common REST API on the Dovetailed Technologies version of Tomcat, this step installs that version.

    1. Go to and click Download.
    2. Unzip the downloaded file. 
    3. Go to and follow the installation instructions.


      • Only one Tomcat server is needed for data collection.
      • Run the Tomcat server on the same LPAR as the primary source of performance data.
        For MainView, run Tomcat on the same system as the primary access CAS, which is usually where the MainView host server starts.
      • Install Tomcat in a directory on a locally mounted zFS file system. For optimum security, configure Tomcat to use TLS (SSL).
  2. Ensure that the CRAZFS1  data set and its members are installed as follows.


    If you previously installed a BMC product that supports the Common REST API, the Installation System created CRAZFS1 and its members. If not, you must run the Installation System to create the data set.

    MemberDescriptionLocation in Tomcat

    configurations.json, which you must modify if you want to use the API to access services that are not automatically discovered

    For more information, see Manually registering services with the Common REST API.


    log4j.xml, required for CRA logging


    cra##1.0.war, the API executable


    timeout.json, the file that sets the user token and session token timeout

    The default timeout is 15 minutes, but you can edit this file to change the setting.



    uimjni, the dynamic link library (DLL) that enables automatic discovery of services


  3. To use the Common REST API with MainView, ensure that PTF BQY2284 is applied.

Customizing Tomcat to work with the API

Use the following procedure to customize Tomcat:


If you are using the Dovetailed Technologies version of Tomcat, go to and read Using SAF Security in Tomcat to learn about security requirements.

  1. Set up user roles as follows:

    1. In the SAF security section of the TCENV member, add the following roles to the SAFROLES member:

      <role rolename="BMCCRA-rest" safclass="EJBROLE" safentity="TCAT.DEV.USER" saflevel="READ"/>
      <role rolename="manager-gui" safclass="EJBROLE" safentity="TCAT.DEV.MANAGER" saflevel="READ"/>
    2. Define the class and SAF entities to your External Security Manager (ESM).
      For example, in RACF, you would issue the the following RDEFINE commands:


    3. You also need to authorize your user base to the respective roles you want them to have.
      For example, to authorize user IBMUSER as a Tomcat manager in RACF, use the following command:




    The manager-gui role is required only for users who are deploying the CRA servlet on Tomcat.

    The BMCCRA-rest role is required for all users who access the Common REST API.

  2. In the TCENV member, ensure JAVA_HOME is pointing to a 32-bit Java installation.


    export JAVA_HOME=/usr/lpp/java/J8.0

  3. In the Tomcat proc, set VERSION to X0, where X is the Java release that your JAVA_HOME points to.
    For example, for Java version 8, your Tomcat proc would look like this:

    //* PROC for running Apache Tomcat using the JZOS batch Java launcher. 
    //* This can be used from a batch job, or from a started task so       
    //* long as the supplied parameters are either included or supplied.   
    //* For more information see: SAMPLIB($README) and IBM JZOS User's Gd. 
    //* NB: This JCL must be Mixed Case                                    
    //MVSXXXTC  PROC CNFGLIB='MVSXXX.TOMCAT.CONFIG',                       
    //   TCENV=TCENV,               < Member of CNFLIB with STDENV script  
    //*  JZOSLIB='SYS1.SIEALNKE',   < JZOS launcher PDSE LIB                 
    //   VERSION='80',              < JZOSVM version: 70,76,80,86          

Deploying the API on your mainframe

  1. After ensuring that Tomcat is running on your mainframe, access Tomcat from a web browser.
  2.  In the Administration menu, click Tomcat Manager
  3. In Username and Password enter your credentials for the Tomcat server.
  4. In the Deploy section of the Tomcat Web Application Manager, enter the following values:

    • In Context Path, enter /cra
      This is the path segment of the API's URL.
    • Leave XML configuration file URL blank.
    • In WAR or Directory URL, enter the full path of the cra.war file
  5. Click Deploy.

In the Message area of the Tomcat Web Application Manager, you will see the following message:

OK - Deployed application at context path /cra

 The Common REST API is now available and appears in the Applications list.

Was this page helpful? Yes No Submitting... Thank you