APIs for administrative utilities

You can invoke utilities and administrative functions by using the API framework. API requests can run the integrity checker utilities, start and stop the Maximo® Manage pods, download log files or a list of log files, and upload logs to Simple Storage Service (S3) Cloud Object Storage, and execute other utilities.

Overview

Beginning with Maximo Manage 8.1, an API framework is provided for the APIs that invoke certain utilities. The API framework is in the Maximo Manage administrative server that is in Maximo Application Suite. The Maximo Manage administrative server contains the smp folder that contains the maximo/tools folder for the scripts. The server also contains an instance of WebSphere® Application Server Liberty that hosts the APIs.

To work with the APIs, you use a browser or an API platform, such as Swagger or Postman.

Authorization to APIs

Authorized users must have an API key and must belong to the security group that enables the signature options for the APIs. The object structure that specifies the necessary signature options is available to the default administrator group, such as MAXADMIN. The default administrator group is specified by the value of the ADMINGROUP varname in the MAXVARS table.

Administrators give users authorization to access the APIs by taking the following steps:

In the API keys application of Maximo Manage, create API keys for the users. This action registers the keys to the users. Copy the keys and provide them to your users.
In the Security groups application, select the administrator group that can work with the APIs.
Select the Object Structures tab and grant access to the tools API object structure.
For the tools API object structure, grant access to the signature options that are associated with the APIs.

APIs to invoke utilities and administrative functions

The following table describes the APIs to invoke utitllies and their actions, HTTP methods, the associated signature options, and whether the API call waits for an API response before it continues. The toolslog and installexternalcert API calls are synchronous and wait for an API response before they continue.

API	Action	HTTP method	Signature option	API request type
icheckerreport	Generate the integrity checker log.	POST	ICREPORT	Asynchronous
toolslog	Get a specified tools log or get a list of all tools logs.	GET	GETLOG	Synchronous
submitUploadLogRequest	Upload logs from Maximo Manage UI, Cron, Maximo Enterprise Adapter, or Report pods to S3 Cloud Object Storage.	POST	GETLOG	Asynchronous
icheckerrepair	Start integrity checker repair.	POST	ICREPAIR	Asynchronous
managestart	Start all Maximo Manage pods.	POST	MANAGESTART	Asynchronous
managestop	Stop all Maximo Manage pods.	POST	MANAGESTOP	Asynchronous
installexternalcert	Import an external certificate to a server bundle truststore.	POST	INSTALLEXTERNALCERT	Synchronous
validatedbformas	Validate the database for the migration to Maximo Manage.	POST	VALIDATEDBFORMAS	Synchronous
runscript	Uses the runscript file CLI to run dbc scripts.	POST	RUNSCRIPT	Synchronous
generd	Generate an entity relationship document (ERD).	POST	GENERD	Synchronous
erd	View a generated ERD.	GET	ERD	Synchronous
downloaderd	Download a generated ERD to your local system as a compressed file.	GET	DOWNLOADERD	Synchronous
updatecustomizationarchive	Add, update, or delete a customization archive without a secret	GET	UPDATECUSTOMIZATIONARCHIVE	Synchronous
createarchivesecret	Create customization archive secrets for user ID and password	POST	CREATEARCHIVESECRET	Synchronous
getbuildstatus	Obtain Maximo Application Suite build status	POST	GETBUILDSTATUS	Synchronous

Note: Do not use the SetAdminMode command-line interface from Manage tools to set the admin mode. The SetAdminMode command-line interface is not available in Maximo Application Suite setup as of now. You must use the Maximo Application Suite user interface or use the REST APIs to manage the admin mode.

API request formats and actions

The following table lists the APIs for the commands and the format of the API request. In the header of any API request, supply the API key that is associated with the Manage user.

For the managestart, managestop, and generd APIs, an HTTP response code of 200 indicates a successful call.

Stop the Maximo Manage pods before you run the integrity checker utility.

Action	API request
Generate the integrity checker log.	`POST https://host:port/toolsapi/toolservice/icheckerreport`
Get an integrity checker log.	`GET https://host:port/toolsapi/toolservice/toolslog?logfile=name of report from icheckerreport request`
Get a list of all tools logs.	`GET https://host:port/toolsapi/toolservice/toolslog`
Run the integrity checker utility.	`POST https://host:port/toolsapi/toolservice/icheckerrepair`
Upload logs from Maximo Manage pods to S3 Cloud Object Storage.	`POST https://host:port/maximo/api/service/logging?action=wsmethod:submitUploadLogRequest`
Stop the Maximo Manage pods.	`POST https://host:port/toolsapi/toolservice/managestop`
Start the Maximo Manage pods.	`POST https://host:port/toolsapi/toolservice/managestart`
Import an external certificate to a server bundle truststore.	`POST https://host:port/toolsapi/toolservice/installexternalcert`
Validate the database for the migration to Maximo Manage.	`POST https://host:port/toolsapi/toolservice/validatedbformas`
Use the runscript file CLI to run dbc scripts.	`POST https://host:port/toolsapi/toolservice/runscript?args=-f<dbc script name>`. For example, `POST https://host:port/toolsapi/toolservice/runscript?args=-fV9000_05`
Generate an entity relationship document (ERD).	`POST https://host:port/toolsapi/toolservice/generd`
View a generated ERD.	`GET https://host:port/toolsapi/toolservice/erd`
Download a generated ERD to local system as a compressed file.	`GET https://host:port/toolsapi/toolservice/downloaderd`
Add, update, or delete a customization archive	`GET https://host:port/toolsapi/toolservice/updatecustomizationarchive`
Create customization archive secrets	`POST https://host:port/toolsapi/toolservice/createarchivesecret`
Check Maximo Manage build status	`POST https://host:port/toolsapi/toolservice/getbuildstatus`

Swagger interface for APIs

You can also make API requests by using the Swagger interface. Swagger is a browser-based editor that you can use to write API definitions.
To use the Swagger interface for APIs, you can enter a URL into a browser.

To use the Swagger interface, complete the following steps:

Enter the URL for the Swagger interface into a browser, as shown in the following example:
```
https://host:port/toolsapi/oas3/api.html
```
After the Swagger interface opens, in the Manage tools api window, click Authorize.
In the Available authorizations window, enter the API key for the interface and click Authorize. The available APIs are displayed.
To exit the window without submitting an authorization, you can click Done.

Examples: Generate and fetch integrity checker log files

Supply the API key in the header of any API request.

To run the integrity checker tool in report mode and generate a log report, make the following request:

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

No request body is required. The integrity checker report process starts asynchronously. The JSON response contains the file names of the report, as shown in the following sample:

{
 "lisfile": "ichecker_report1622050100427.lis"
 "logfile": "ichecker_report1622050100427.log"
 }

To fetch one of the logs, make the following request and supply one of the log file names as a parameter. The tools log process runs synchronously. The log file is returned as the response body of the request.

GET https://<domain path>/toolsapi/toolservice/toolslog?logfile=ichecker_report1622050100427.lis

The following related links about APIs provide detailed information about many of the APIs that work with this product and related products. The information might describe features that are not available to you.

Extended API framework to call shell scripts

From Maximo Manage 9.0, you can expand the API framework and create APIs that call additional existing shell scripts. You can create your own folder to store and run script files and access script files in both tools/maximo and tools/maximo/internal folder by using tools API.

To enable tools API to execute scripts in the tools/maximo/internal folder, set the INTERNAL flag to 1 in the APIROUTEPROP table for the corresponding API route in the Maximo Manage database.