Technical Tip: Managing the JSON API call with Postman and how to delete, create and update an ADOM using it

vraev · ‎01-04-2023

Description

This article describes how to use the JSON API calls to manage specific objects/information on the FortiManager.

Scope

Setting up and managing FortiManager with the JSON API call. Postman is used for testing.

Solution

Note: There is an attached text file that contains the full JSON API calls and the simplified version used in the article (see related article).

Download and install Postman if it is not already installed: Download Postman.
See the following article for information on how to import or export a collection:
Importing and exporting data.
Set up the environment:

Set up the appropriate environment variables:

Retrieve the login session ID:

The variable can be used as part of the syntax for a URL. For example: https://{{ip}}/jsonrpc.

The Request body should be like the one below:

{
  "method": "exec",
  "params": [
    {
      "data": {
        "passwd": "",
        "user": "{{user}}"
      },
      "url": "/sys/login/user"
    }
  ],
  "session": "1",
  "id": 1
}

The output should be like the one below:

{
    "id": 1,
    "result": [
        {
            "status": {
                "code": 0,
                "message": "OK"
            },
            "url": "/sys/login/user"
        }
    ],
    "session": "Vm1PhOjrqH0j24kJrh5kRTzghMtiJH3dFk6M3SxRgxB5MaNfyxlA0NHqf5B+r8B60BmGTVAGJCOGdusUNgf5Yw=="

From the received output, it is possible to copy the session ID to the environment variables and save the change.

Note:

The session ID remains active for a period of time based on the Idle Timeout (API) settings. See System Settings -> Admin -> Admin Settings:

After the session ID is updated, the current ADOM list will be retrieved.

The Request body should be like the one below:

{
  "method": "get",
  "params": [
    {
      "url": "/dvmdb/adom"
    }
  ],
  "session": "{{session}}",
  "id": 1
}

It is possible to review the provided data and, if everything is correct, the ADOM will be deleted.

Delete the ADOM.

If all steps have been performed correctly, the ADOM will be deleted.

The Request body should be like the one below:

{
  "method": "delete",
  "params": [
    {
      "url": "/dvmdb/adom/{{adomname}}"
    }
  ],
  "session": "{{session}}",
  "id": 1
}

The output should be like the one below:

{
    "id": 1,
    "result": [
        {
            "status": {
                "code": 0,
                "message": "OK"
            },
            "url": "/dvmdb/adom/Core-2200E"
        }
    ]
}

Optionally, confirm the information with the following CLI command:

diagnose dvm adom list

There are currently 26 ADOMs (count for license: 6/105):

OID STATE PRODUCT OSVER MR LIC NAME MODE VPN MANAGEMENT IPS ISDB

237 enabled FOS 6.0 4 Y CB-100E Normal Central VPN Console 22.458 7.2909

239 enabled FOS 6.0 4 Y CB-2500E Normal Central VPN Console 22.458 7.2909

243 enabled FOS 6.0 4 Y Core-100E Normal Central VPN Console 22.458 7.2909

---- Part of the output is omitted -----

501 enabled FOS 6.0 4 Y RD-100E Normal Central VPN Console 22.458 7.2909

241 enabled FOS 6.0 4 Y RD-2500E Normal Central VPN Console 22.458 7.2909

---End ADOM list---

Recreate the deleted ADOM.

The Request body should be like the one below:

{
  "method": "add",
  "params": [
    {
      "data": {
        "create_time": 0,
        "desc": "Test ADOM",
        "log_db_retention_hours": 1440,
        "log_disk_quota": 0,
        "log_disk_quota_alert_thres": 90,
        "log_disk_quota_split_ratio": 70,
        "log_file_retention_hours": 8760,
         "mig_mr": 2,
        "mode": "gms",
        "mr": 2,
        "state": 1,
        "workspace_mode": 0
      },
      "url": "/dvmdb/adom/{{adomname}}"
    }
  ],
  "session": "{{session}}",
  "id": 1
}

The output should be like the example below:

{
    "id": 1,
    "result": [
        {
            "data": {
                "name": "Core-2200E"
            },
            "status": {
                "code": 0,
                "message": "OK"
            },
            "url": "/dvmdb/adom/Core-2200E"
        }
    ]
}

Confirm the changes in the GUI:

Troubleshooting steps:

Start with a hardcoding of all the data, removing the variables.

In this case, the password is (blank) and an error is received. It will be removed and try again. Do not forget to save the changes.

Copy the whole request body and remove any unnecessary parts of it. Be careful with the syntax.

The full request body:

{
  "method": "update",
  "params": [
    {
      "data": {
        "create_time": 0,
        "desc": "string",
        "flags": [
          "{option}"
        ],
        "log_db_retention_hours": 1440,
        "log_disk_quota": 0,
        "log_disk_quota_alert_thres": 90,
        "log_disk_quota_split_ratio": 70,
        "log_file_retention_hours": 8760,
        "meta fields": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "mig_mr": 2,
        "mig_os_ver": "7.0",
        "mode": "gms",
        "mr": 2,
        "name": "string",
        "os_ver": "7.0",
        "restricted_prds": [
          "{option}"
        ],
        "state": 1,
        "uuid": "string",
        "workspace_mode": 0
      },
      "url": "/dvmdb/adom/{adom}"
    }
  ],
  "session": "string",
  "id": 1
}

The edited request body:

{
  "method": "update",
  "params": [
    {
      "data": {
        "desc": "Changed data"
      },
      "url": "/dvmdb/adom/Core-2200E"
    }
  ],
  "session": "RbSGfONitP134I7JI343UrNCTHNuXht0jIMB9lG0ulpCG8Tvl3B1lJkcc3y0m3PUXcf964DXIJ+ZBJ9GbX1CLA==",
  "id": 1
}

After removing all of the unnecessary data, the request body is much shorter and easier to understand. Check the status and observe the change from the GUI.

Do not forget to confirm whether the user has sufficient rights for the requests.

Related articles: