Setting up the Common REST API

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:

   Note

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

   1. Go to http://dovetail.com/products/tomcat.html and click Download.
   2. Unzip the downloaded file. 

   3. Go to http://dovetail.com/docs/tomcat/install.html and follow the installation instructions.

      Tips

      • 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.
   

   Note

   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.

   Member	Description	Location in Tomcat
   CRACFG	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.	/conf/configurations.json
   CRAL4J	log4j.xml, required for CRA logging	/conf/log4j.xml
   CRAWAR	cra##1.0.war, the API executable	/bin/cra##1.0.war
   CRATO	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.	/conf/timeout.json
   UIMJNI	uimjni, the dynamic link library (DLL) that enables automatic discovery of services	/bin/uimjni

   
   

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:

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:
      

      Example

      RDEFINE EJBROLE TCAT.DEV.USER UACC(NONE)
      RDEFINE EJBROLE TCAT.DEV.MANAGER UACC(NONE)

   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:

      Example

      PERMIT TCAT.DEV.MANAGER CLASS(EJBROLE) ID(IBMUSER) ACCESS(READ)

   Note

   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.

   Example

   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.