Technical Tip: Find and replace an address object using the JSON API

Description

This article describes how to find and replace an address object used in a policy package using the JSON API.

Scope

FortiManager, Postman.

Solution

The find and replace address object (or any ADOM-level object) involves three steps:

1. Initialize the 'Find' process.

2. Get the list of all object references.

3. Replace the object in all references.

The following process details how to achieve this:

• Initialize the 'Find' process.

{
    "method": "exec",
    "params": [
        {
            "url": "cache/search/where/used/start",
            "data": {
                "obj": "adom/{{ADOM}}/obj/{{Object_Type}}",
                "mkey": "{{Object_Find}}",
                "flags": [
                    "direct used"
                ]
            }
        }
    ],
    "id": "2",
    "session": "{{session}}",
    "verbose": 1
}

Here, the {{Object_Type}} = firewall/address. This can be changed depending on the type of object required.

For example:

• For a local user: user/local.

• For a dynamic interface: dynamic/interface.

• For a Security Profile Group: firewall/profile-group.

• For a Metadata Variable: fmg/variable

The output of this request generates a 'token', which is then used in the next query.

• Get the list of all object references:
  
  

 {
    "method": "exec",
    "params": [
        {
            "url": "cache/search/where/used/get/detail",
            "token": "{{token}}"
        }
    ],
    "id": "1",
    "session": "{{session}}",
    "verbose": 1
}

Example output:

• Replace the object in all references (if 'X' number of references, then 'X' number of requests).

In this example, there is an address object 'Test1' that has been used in two firewall policies in a policy package (as seen in step 2 output). Consequently, two requests are required to replace it with another object, 'Test2'.

{
        "method": "update",
        "params": [
            {
                "url": `pm/config/adom/${adom}/pkg/${policy.package_name}/firewall/policy/${policy.policy_id}`,
                "used objs": {
                    "from": `obj/${objecttype}/${objectFind}`,
                    "to": [
                       `${objectReplaceWith}`
                    ]
                }
            }
        ],
        "id": 3,
        "session": sessionTokenValue
    };

             
Instead of running multiple queries manually, Postman Scripts can be used to run change requests in a loop until the object is replaced in all references.

• The API collection can be imported into Postman (tested with v11.73.0) using the attached file.

• Under the 'Variables' tab of the collection, the following variables are required:n

  • host: IP address of FortiManager.

  • ADMIN: FortiManager Admin user.

  • PASSWORD: Admin user password.

  • ADOM: FortiManager ADOM.

  • Object_Type: Already set to: firewall/address. Change if required - as explained in Step 1.

  • Object_Find: Object Name - object to be replaced

  • Object_ReplaceWith: Object Name - object to replace with

Related documents:

Postman Release Notes
Technical Tip: Using FortiManager API
Fortinet Development Network (FNDN) - FortiManager