How to use the Tools API with Maximo Manage

 The tools API was created to facilitate a simple way for clients to access CLI tools from outside of the Red Hat OpenShift cluster.

• icheckerreport – Run Integrity Checker in “report” mode
• icheckerrepair – Run Integrity Checker in “repair” mode
• toolslog - Get a specified tools log or get a list of all tools logs
• managestart - Start all Maximo Manage pods
• managestop – Stop all Maximo Manage pods
• submitUploadLogRequest - Upload logs from Maximo Manage UI, Cron, MEA, or Report pods to S3 Cloud Object Storage
• (Note: this tool runs against the Manage Liberty pods, where the Manage application runs, to collect and upload logs to Cloud Object Storage, unlike CLI tools that run against the MAXINST pod)

Setting up the Environment

There are three things to do before executing commands. 

Set up S3 Cloud Object Storage and configure Maximo properties (used to submit upload log requests for Manage Liberty pod logs).  See the link for more information:

https://www.ibm.com/docs/en/mas-cd/maximo-manage/continuous-delivery?topic=documents-sending-log-output-s3-cloud-object-storage

Configure access to the signature option:

1. In the Security Groups application, search for your security group
2. On the applications tab, search for the Logging application
3. Grant access to the "Load log files to object store" signature option
4. Save the changes and log out and in again to apply the changes

Generate an API key

In Manage 8.4 and newer versions:

1. Navigate to Integration -> API Keys. 
2. Click "Add API Key"
3. Search for the user, and click "Create"

For Manage 8.3 and earlier versions:

1. Navigate to the Administration -> Administration work center
2. Click the link "API Keys"
3. Click "Add API Key"
4. Search for the user, and click "Add"
   
5. Copy the API key
   

This key will be used in the next steps.

Setting up a rest client:

1. In the example shown, Postman was used as the REST client.  
2. Create new HTTP request
3. Add a header called "apikey".  Past the copied key into the value field

Executing CLI tools sending requests to the maxinst pod:

POST https://host:port/toolsapi/toolservice/icheckerreport - Generate an integrity checker log.

GET https://host:port/toolsapi/toolservice/toolslog?logfile=<name of report from icheckerreport request>

GET https://host:port/toolsapi/toolservice/toolslog - Get a list of all tools logs.

POST https://host:port/toolsapi/toolservice/icheckerrepair - Execute the integrity checker utility.

POST https://host:port/toolsapi/toolservice/managestop - Stop the Maximo Manage pods.

POST https://host:port/toolsapi/toolservice/managestart - Start the Maximo Manage pods.

Executing Logging service commands sending request to the Manage pod:

POST https://host:port/maximo/api/service/logging?action=wsmethod:submitUploadLogRequest - Upload logs from Maximo Manage pods to S3 Cloud Object Storage.
 

GET https://host:port/maximo/api/service/logging?action=wsmethod:streamLog - Stream the application log to the browser

Executing the integrity checker CLI

Executing Integrity Checker to write a report to logs

The URL for any of the toolsapi requests requires the url to your maxinst pod.  For this report, use the POST method. 

POST https://host:port/toolsapi/toolservice/icheckerreport

The body of the request is blank.

The response is shown in this screen capture:

Getting lists of tools logs

GET https://host:port/toolsapi/toolservice/toolslog Get a list of all tools logs.

A list of available logs is shown in the screen capture:

     

Streaming tools logs

To stream a particular log file output, add the logfile parameter along with the file name as shown:

GET https://host:port/toolsapi/toolservice/toolslog?logfile=ichecker_report1637953395961.log

Stopping and starting Manage

Executing managestop

You stop the manage pods by using the Tools API against the MAXINST pod URL:

POST https://host:port/toolsapi/toolservice/managestop

Executing managestart

POST https://host:port/toolsapi/toolservice/managestart

Submit Upload Log Request to Cloud Object Storage

Submitting upload log requests is executed on Manage pods.  Upon executing this command, all logs from all Manage Liberty pods (cron, UI, MIF, RPT) are collected, compressed, and automatically uploaded to Cloud Object Storage.  This allows administrators to access the logs without the need for access to the Red Hat OpenShift console.

POST https://host:port/maximo/api/service/logging?action=wsmethod:submitUploadLogRequest

Navigate to your Cloud Object Storage bucket to see the log returned in the output:

Reference Link : https://www.ibm.com/support/pages/how-use-tools-api-maximo-manage

How to configure JMS servers for Maximo Manage

 This configuration creates a single-pod Liberty JMS server.

Steps

1. Log in to Maximo Application Suite as a system administrator.
 

2. From Suite administration, select workspaces from the side navigation menu and then select the Manage title.

3. On the Manage workspace details page, click Actions, and select Update configuration.

4. In the Server bundles row, click the edit icon.

5. In the Server bundles section, if the System managed checkbox is selected, clear it. Click Add bundle.

6. In the Name column, enter a name for the bundle, such as jmsserver.

7. In the Type column, select standalonejms.

8. To configure the queues, complete the following steps:

       a. In the Additional properties column for your JMS server bundle, click View.

       b. Optional: Set a different route subdomain.

       c. In the Additional server config section, use XML to specify both the default queues and the custom queues that you want to add:

<?xml version="1.0" encoding="UTF-8"?>
<server description="new server">

    <!-- Enable features -->
      <featureManager>
        <feature>wasJmsSecurity-1.0</feature>
        <feature>wasJmsServer-1.0</feature>
    </featureManager>
    <applicationManager autoExpand="true"/>
    <wasJmsEndpoint host="*" wasJmsSSLPort="7286" wasJmsPort="7276" />
    <messagingEngine>
        <fileStore path="/jmsstore"/>
        <queue id="sqoutbd" maintainStrictOrder="true" maxMessageDepth="100000" failedDeliveryPolicy="KEEP_TRYING" maxRedeliveryCount="-1"/>
        <queue id="sqinbd" maintainStrictOrder="true" maxMessageDepth="200000" failedDeliveryPolicy="KEEP_TRYING" maxRedeliveryCount="-1"/>
        <queue id="cqinerrbd" maxMessageDepth="100000" failedDeliveryPolicy="KEEP_TRYING"/>
        <queue id="cqinbd" maxMessageDepth="100000" exceptionDestination="cqinerrbd"/>
        <queue id="cqouterrbd" maxMessageDepth="100000" failedDeliveryPolicy="KEEP_TRYING"/>
        <queue id="cqoutbd" maxMessageDepth="100000" exceptionDestination="cqouterrbd"/>
        <queue id="notferrbd" maxMessageDepth="100000" failedDeliveryPolicy="KEEP_TRYING"/>
        <queue id="notfbd" maxMessageDepth="100000" exceptionDestination="notferrbd"/>
    </messagingEngine>
</server>

Note: The fileStore path can be modified to use a different directory to store JMS messages. If you are using persistent volumes, make sure that the fileStore path is configured correctly under the persistent volume directory. For example, if your persistent volume is mounted on directory /nfs, then the fileStore path might be /nfs/jmsstore.

       d. Click Save to save the additional server bundle properties.

9. If you have a single server (all) bundle or for the mea bundle, to prepare the other Maximo Manage server bundles for the JMS queues, complete the following steps:

       a. In the Additional properties column for the server bundle, click View.

       b. In the Additional server config section, specify features for both the default queues and the custom queues that you want to add, as shown in the following example:

<?xml version='1.0' encoding='UTF-8'?>
<server description="new server">
<featureManager>
<feature>jndi-1.0</feature>
<feature>wasJmsClient-2.0</feature>
<feature>jmsMdb-3.2</feature>
<feature>mdb-3.2</feature>
</featureManager>

    <jmsQueueConnectionFactory jndiName="jms/maximo/int/cf/intcf" connectionManagerRef="mifjmsconfact"><properties.wasJms remoteServerAddress="<InstancesId>-<workspaceId>-<serverbundlename>.mas-<instanceId>-manage.svc:7276:BootstrapBasicMessaging"/></jmsQueueConnectionFactory>
    <connectionManager id="mifjmsconfact" maxPoolSize="20"/>

    <jmsQueue jndiName="jms/maximo/int/queues/sqout"><properties.wasJms queueName="sqoutbd"/></jmsQueue>
    <jmsQueue jndiName="jms/maximo/int/queues/sqin"><properties.wasJms queueName="sqinbd"/></jmsQueue>
    <jmsQueue jndiName="jms/maximo/int/queues/cqin"><properties.wasJms queueName="cqinbd"/></jmsQueue>
    <jmsQueue jndiName="jms/maximo/int/queues/cqinerr"><properties.wasJms queueName="cqinerrbd"/></jmsQueue>
    <jmsQueue jndiName="jms/maximo/int/queues/cqout"><properties.wasJms queueName="cqoutbd"/></jmsQueue>
    <jmsQueue jndiName="jms/maximo/int/queues/cqouterr"><properties.wasJms queueName="cqouterrbd"/></jmsQueue>
    <jmsQueue jndiName="jms/maximo/int/queues/notf"><properties.wasJms queueName="notfbd"/></jmsQueue>
    <jmsQueue jndiName="jms/maximo/int/queues/notferr"><properties.wasJms queueName="notferrbd"/></jmsQueue>


    <jmsActivationSpec id="maximo-all/mboejb/JMSContQueueProcessor-1" maxEndpoints="5"><properties.wasJms destinationLookup="jms/maximo/int/queues/cqin" maxConcurrency="5" maxBatchSize="20" connectionFactoryLookup="jms/maximo/int/cf/intcf"/></jmsActivationSpec>
    <jmsActivationSpec id="maximo-all/mboejb/JMSContQueueProcessor-2" maxEndpoints="1"><properties.wasJms destinationLookup="jms/maximo/int/queues/cqinerr" maxConcurrency="1" maxBatchSize="20" connectionFactoryLookup="jms/maximo/int/cf/intcf"/></jmsActivationSpec>
    <jmsActivationSpec id="maximo-all/mboejb/JMSContOutQueueProcessor-1" maxEndpoints="5"><properties.wasJms destinationLookup="jms/maximo/int/queues/cqout" maxConcurrency="5" maxBatchSize="20" connectionFactoryLookup="jms/maximo/int/cf/intcf"/></jmsActivationSpec>
    <jmsActivationSpec id="maximo-all/mboejb/JMSContOutQueueProcessor-2" maxEndpoints="1"><properties.wasJms destinationLookup="jms/maximo/int/queues/cqouterr" maxConcurrency="1" maxBatchSize="20" connectionFactoryLookup="jms/maximo/int/cf/intcf"/></jmsActivationSpec>
</server>

The queueName values must match the queue names that you specified in step 8.c. Also, the difference between all bundles or mea bundle XML versus the report, cron, UI bundles XML is that the second category does not have the jmsActivationSpec lines.

The ID used in jmsActivationSpec is "maximo-all/mboejb/JMSContQueueProcessor-1". Where maximo-all is the ear file name. 

For mea you need to use maximomea like: "maximomea/mboejb/JMSContQueueProcessor-1"

When you enter the connection properties, on remoteServerAddress supply the following variables:

Name of your JMS server bundle, for example, jmsserver.
 

<InstanceId>

Name of your Maximo Application Suite instance.

<workspaceId>

Name of your workspace.

<serverbundlename>

Note: Your remoteServerAddress must be in the following format:

remoteServerAddress="<InstanceId>-<workspaceId>-<serverbundlename>.mas-<InstanceId>-manage.svc:7276:BootstrapBasicMessaging".
 

For example:

remoteServerAddress="mngrel84-masdev-jmsserver.mas-mngrel84-manage.svc:7276:BootstrapBasicMessaging".
 

10. If you have report, cron, or UI bundles, complete the following steps for each of them:

       a. In the Additional properties column for the server bundle, click View.
       b. In the Additional server config section, specify features for both the default queues and the custom queues that you want to add, as shown in the following example:

<?xml version='1.0' encoding='UTF-8'?>
<server description="new server">
<featureManager>
<feature>jndi-1.0</feature>
<feature>wasJmsClient-2.0</feature>
<feature>jmsMdb-3.2</feature>
<feature>mdb-3.2</feature>
</featureManager>

    <jmsQueueConnectionFactory jndiName="jms/maximo/int/cf/intcf" connectionManagerRef="mifjmsconfact"><properties.wasJms remoteServerAddress="<InstanceId>-<workspaceId>-<serverbundlename>.mas-<InstanceId>-manage.svc:7276:BootstrapBasicMessaging"/></jmsQueueConnectionFactory>
    <connectionManager id="mifjmsconfact" maxPoolSize="20"/>

    <jmsQueue jndiName="jms/maximo/int/queues/sqout"><properties.wasJms queueName="sqoutbd"/></jmsQueue>
    <jmsQueue jndiName="jms/maximo/int/queues/sqin"><properties.wasJms queueName="sqinbd"/></jmsQueue>
    <jmsQueue jndiName="jms/maximo/int/queues/cqin"><properties.wasJms queueName="cqinbd"/></jmsQueue>
    <jmsQueue jndiName="jms/maximo/int/queues/cqinerr"><properties.wasJms queueName="cqinerrbd"/></jmsQueue>
    <jmsQueue jndiName="jms/maximo/int/queues/cqout"><properties.wasJms queueName="cqoutbd"/></jmsQueue>
    <jmsQueue jndiName="jms/maximo/int/queues/cqouterr"><properties.wasJms queueName="cqouterrbd"/></jmsQueue>
    <jmsQueue jndiName="jms/maximo/int/queues/notf"><properties.wasJms queueName="notfbd"/></jmsQueue>
    <jmsQueue jndiName="jms/maximo/int/queues/notferr"><properties.wasJms queueName="notferrbd"/></jmsQueue>

</server>

Remember to update remoteServerAddress as well for bundles report, cron, or UI.
 

11. Click Save again to save the additional server bundle properties.

12. After you complete the workspace updates, activate the changes.

 

Enabling MDBs

 

After the queue is configured, you need to enable MDBs so the continuous queue can work. 
 

1. Creating a customization file.
 

       a. Copy ejb-jar.xml file from maxinst pod in your local machine.

oc rsync MAXIST_POD_NAME:/opt/IBM/SMP/maximo/applications/maximo/mboejb/ejbmodule/META-INF/ejb-jar.xml ./

Do not copy ibm-ejb-jar-bnd.xmi. You need ejb-jar file only if you include ibm-ejb-jar-bnd.xmi in the customization file MDB will not work.

       b. Uncomment the sections in ejb-jar.xml file: "MEA MDB" and "MEA MDB for error queue".

If you want to use a continuous outbound queue and don't have a reference for JMSContOutQueueProcessor-1 and JMSContOutQueueProcessor-2 in your ejb-jar file include the TAGs:

 

<!-- MEA MDB FOR CQOUT -->

	<message-driven id="MessageDriven_JMSContOutQueueProcessor_1">
      <ejb-name>JMSContOutQueueProcessor-1</ejb-name>
      <ejb-class>psdi.iface.jms.JMSContQueueProcessor</ejb-class>
      <transaction-type>Container</transaction-type>
      <message-destination-type>javax.jms.Queue</message-destination-type>
      <env-entry>
        <env-entry-name>MESSAGEPROCESSOR</env-entry-name>
	<env-entry-type>java.lang.String </env-entry-type>
	<env-entry-value>psdi.iface.jms.QueueToMaximoProcessor</env-entry-value>
      </env-entry> 
    </message-driven>

<!-- MEA MDB for CQOUT error queue-->

    <message-driven id="MessageDriven_JMSContOutQueueProcessor_2">
      <ejb-name>JMSContOutQueueProcessor-2</ejb-name>
      <ejb-class>psdi.iface.jms.JMSContQueueProcessor</ejb-class>
      <transaction-type>Container</transaction-type>
      <message-destination-type>javax.jms.Queue</message-destination-type>
      <env-entry>
        <env-entry-name>MESSAGEPROCESSOR</env-entry-name>
	<env-entry-type>java.lang.String </env-entry-type>
	<env-entry-value>psdi.iface.jms.QueueToMaximoProcessor</env-entry-value>
      </env-entry> 
      <env-entry>
        <env-entry-name>MDBDELAY</env-entry-name>
	<env-entry-type>java.lang.Long </env-entry-type>
	<env-entry-value>30000</env-entry-value>
      </env-entry>      
      <env-entry>
        <env-entry-name>ERRORQUEUE</env-entry-name>
	<env-entry-type>java.lang.String </env-entry-type>
	<env-entry-value>1</env-entry-value>
      </env-entry>      
      
    </message-driven>

<!-- MEA MDB FOR CQOUT -->

	<container-transaction>
    	<method>
    	   <ejb-name>JMSContOutQueueProcessor-1</ejb-name>
    	   <method-name>*</method-name>
    	</method>
    
    	<trans-attribute>Required</trans-attribute>
    
    </container-transaction>

<!-- MEA MDB for CQOUT error queue-->

    <container-transaction>
    	<method>
    	   <ejb-name>JMSContOutQueueProcessor-2</ejb-name>
    	   <method-name>*</method-name>
    	</method>
    
    	<trans-attribute>Required</trans-attribute>
    
    </container-transaction>

       c. Create in your local machine the path: 

deployment\was-liberty-default\config-deployment-descriptors\maximo-all\mboejb\ejbmodule\META-INF\ejb-jar.xml

In this path, there is a reference to the bundle type, which in this example is maximo-all. Replace by maximo-mea if you are enabling for mea bundle. The customization file uses the same path that exists in the maxinst pod, like this example:

       d. Create a zip file with the entire path created in step 1.c.

2. Upload the customization zip file to an FTP or HTTP server.

3. Log in to Maximo Application Suite as a system administrator.
 

4. From Suite administration, select workspaces from the side navigation menu and then select the Manage tile.
 

5. On the Manage workspace details page, click Actions, and select Update configuration.

6. In the Customization row, clear the System Managed checkbox. Click Add customization archive.

7. In the Alias column, enter a name for the customization file, such as JMS. In the File address column, paste the URL for the customization file uploaded in step 2.

8. Click Activate button and wait for the environment to reconcile.

Reference Link:https://www.ibm.com/support/pages/node/6962441