John Q. Todd

Sr. Business Consultant/Product Researcher

Total Resource Management (TRM), Inc. 

One of the concerns clients have when they go to the cloud is the degree of access they have to the underlying infrastructure to control and generally administrate their MAS instances. The Tools API provides a few of the commonly needed actions an Administrator would need to perform, without them having to ask for permission. The ability for you to make the connection and requests is contingent upon the nature of your cloud hosting agreement and provider. Start by asking this question before trying to set up and make the connection on your own.

For full disclosure, much of the detail for this article can be found via this URL provided by IBM:

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

However, indulge us a bit as we walk through what the Tools API brings to you as a MAS client, whether your instances are on-prem or being hosted in the cloud by someone.

What is the Tools API?

Starting way back with Manage 8.1, the Tools API provides many of the Cloud Command Line Interface (CLI) tools that a client could execute on their instances which are hosted in the cloud. As a side note, Manage is now at release 8.6 under the MAS 8.10 umbrella.

Commands such as running the Integrity Checker, starting/stopping Manage pods, uploading logs, etc. are all common operations that an Administrative User might wish to perform. Depending upon your hosting situation, your host may require you to submit a request to execute these commands, or they may give you access to do on your own. Best to check your hosting agreement before you try to set up what the IBM URL suggests.

Setup

The first thing you are going to need to do is download a REST command/request application such as Postman or the like. These applications enable you to connect to servers (via URLs) and execute REST requests such as POST, GET, etc. You can form, execute, and then save your requests, so once you have your key functions in place, you simply execute the requests as needed. Tools such as Postman have many useful functions when it comes to interacting with APIs.

The URL provided by IBM points to the need to configure the Logging app within Manage to provide the necessary application access to the User(s) you expect to execute the Tools commands. We strongly recommend that the list of Users granted this degree of access is very small and are Administration level Users.

You will also need to generate an API Key for the Postman app to use to authenticate with the server when it attempts to make a connection. This is done via the API Key application under the Integrations module of Manage. It is a simple matter to generate the key for a particular User (most likely MAXADMIN) and copy it for use later.

Making the connection

Armed with Postman and your API Key, you can configure your first REST request. As a side note, you are making these requests to the maxinst pod that is running under the Red Hat OpenShift environment that is supporting your MAS instance. This detail may be important if you must work with your hosting provider to gain access.

You will need to know the hosting details to form proper URLs to execute your REST requests. This can be frustrating because the URL must be exact. A sample REST request URL would look like:

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

Note that the “host:port” section of the URL is very specific to the instance you are attempting to connect to.

Executing requests

Now comes the fun part… executing REST requests. If you are new to applications like Postman, there will be a small learning curve to understand how it works, and then some learning to understand the results that the CLI tools return to you.

Leverage the IBM link to walk through each of the Tools to get a feel for what they do for you.

Warning! Making requests such as:

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

… do just that. They stop the Manage pod! If you just did this in your Production instance, your phone would certainly start ringing. Best to learn on your non-production instances before moving over to the ones your business depends upon. Use the managestart request to restart the pod if you make this error.

One function that is nice to have is the ability to capture logs and then access them for analysis without having to ask for them or enter tickets to the host. When the submit upload log request is made, all the Manage Liberty (the underlying MAS application server that replaced WebSphere) pod logs are zipped up and uploaded to the underlying cloud object storage. The logs of the cron, UI, MIF, and RPT pods are included all at once.

Of course, you will need to have access to this storage location to retrieve the zipped files. More discussions with your Cloud host for sure.

Wrap up

TRM, being a cloud host, fields requests for this degree of system access on a very regular basis. We certainly help our clients achieve the access they need to manage their instances. Some need access, while others are perfectly happy having us do all the work!