Create a device object change request

This REST calls supports opening object change requests, including those where objects from multiple devices are being changed.

FireFlow validates the API to ensure that mandatory elements are in place, such as permissions, template, date formats, that any specified device exists in AFA, and so on.

Note: The change request that is created from this request cannot be edited in the Web Interface.

Resource Name: /FireFlow/api/request/object

Request Method: POST

Header requirements:

Key Value
Cookie FireFlow_Session=[sessionID]. The sessionId is retrieved from the authentication request.

Request Query Parameters:

Element

Type

Description

Mandatory basic change request fields:

    template

Additional, optional basic change request fields, such as:

    description
    due
    expire
    externalId
    owner
    priority
    refersTo
    referredBy
    requestor
    subject

String

The change request's value for the field.

Note: Element syntax in this API may differ slightly from the traffic change request API, even if it refers to the same data.

For example, the externalID in this API is the same as the CMS ticket id in the traffic ticket API, and referredBy in this API is the same as ReferredBy in traffic ticket APIs.

customFields

Optional

A customFields object

See customFields type.

requestedActions:
devices

Mandatory

List of strings

The list of devices for which the object change request will be created.

This element is mandatory only if you do not use the objectContainers element.

Note: If you are defining the device, you must enter the device database name, not the name displayed in the AFA device tree.

Retrieve device database names using the following API:

https://<server_IP>/fa/server/rules/read?session=<FA_session_Id>&entity=<AFA_UI_display_name>

Any error messages that include the device name include the name displayed in AFA.

requestedActions:
action

String

One of the following:

  • create
  • delete
  • addObjectsToGroup
  • removeObjectsFromGroup
  • replaceContent
requestedActions:
name
String The Display name of the Object being modified.

requestedActions:
isGroup

String

Whether the object is able to hold multiple values within it. Non-group objects may not be transformed into group objects, and group objects may not become non-group objects(though they may contain only 1 value).

One of the following::

  • True
  • False

Example of a non-group object: host_1.1.1.1

Example of group object: ntp_servers

requestedActions:
type
String

The type of object.

One of the following:

  • network
  • service

requestedActions:
values

Array of String

List of values being added, removed, or placed.

Example for Service Object: ["tcp/23","udp/53"]

Example for Network Object: ["object2"]

objectContainerLevel

String

The device/management level on which to change the object.

One of the following:

  • highest. To change the object at the highest level/management.

    Note: For Check Point devices, choosing highest will change the object on the CMA, not the PV1.

  • lowest. To change the object on the lowest level/individual device.

  • automatic. (Default) The level on which to change the object is determined based on an algorithm.

Response:

Element

Type

Description

status

String

One of the following:

  • Success
  • Failure
messages

Object containing the code and the message.

Strings that indicate success or failure.

In case of failure, contains a list of strings that detail why the change request was not created.

data

A changeRequestId object or a list of strings

One of the following:

  • In case of success, the change request ID and a redirect URL
  • In case of failure, null.

Note: Change request creation may not have been completed even though the ID is supplied.

 

Response:

Code

Description

200

Operation completed successfully

400

Input validation failure

403

Authentication failure

500

Failed to complete operation.

Create object request example

{ 
   "template":"135: Object Change Multi Device Request",
   "subject":"Create object request",
   "due":"2019-10-10",
   "owner":"admin",
   "priority":"5",
   "customFields":[ 
      { 
         "key":"cf1",
         "values":[ 
            "cf value1",
            "cf value2"
         ]
      },
      { 
         "key":"cf2",
         "values":[ 
            "cf2 value1",
            "cf2 value2"
         ]
      }
   ],
   "devices":[ 
      "FW_101",
      "FW_102"
   ],
   "requestedActions":[ 
      { 
         "action":"create",
         "name":"networkObject1",
         "type":"network",
         "isGroup":"false",
         "values":[ 
            "1.1.1.1"
         ]
      },
      { 
         "action":"create",
         "name":"serviceObject1",
         "type":"service",
         "isGroup":"false",
         "values":[ 
            "tcp/12"
         ]
      }
   ],
   "objectContainerLevel":"Automatic"
}
			

Add objects to group request example

{
 "template": "135: Object Change Multi Device Request",
 "subject": "Modify object request",
 "description": "adding objects to GR_Network_Devices",
 "externalId": "123a",
 "devices": ["FW_101", "FW_102"],
 
 "requestedActions": [
  {
   "action": "addObjectsToGroup",
   "name": "GR_Network_Devices",
   "type": "network",
   "isGroup": true,
   "values": ["Net_10.163.40.232_31", "HK_Cyberark_10.133.21.217"]
  }] 
 "objectContainerLevel": "Automatic"           
}	

Multiple actions request example: replace content, remove objects from group, and delete

{

 "template": "135: Object Change Multi Device Request",
 "subject": "several actions",
 "devices": ["FW_101"],
 "requestedActions": [


  {
   "action": "replaceContent",
   "name": "object2",
   "type": "network",
   "isGroup": false,
   "values": ["object2"]
  },

  {
   "action": "removeObjectsFromGroup",
   "name": "GP_Captical",
   "type": "network",
   "isGroup": true,
   "values": ["Net_211.72.241.0", "Net_61.219.22.0"]
  },

  {
   "action": "delete",
   "name": "Net_203.69.50.0",
   "type": "network",
   "isGroup": false
  }
 ],
 "objectContainerLevel": "Automatic"
}

(success)

{
 "status": "Success",
 "messages": [   {
 "code": "success",
 "message": "Success"
}],
"data":    {
 "changeRequestId": 4341,
 "redirectUrl": "https://10.45.10.26/FireFlow/Ticket/Display.html?id=4341"
 }
}

(object not found failure)

{
 "status": "Failure",
 "messages": [{
   "code": "OBJECT_NOT_FOUND",
   "message": "On action: addObjectsToGroup the object: GR_Network_Devices doesnt exist on devices: [FW_101] ([FW_102])."
  },
  {
   "code": "OBJECT_NOT_FOUND",
   "message": "On action: removeObjectsFromGroup the object: GP_Captical doesnt exist on devices: [FW_101] ([FW_102])."
  },
  {
   "code": "OBJECT_NOT_FOUND",
   "message": "On action: delete the object: Net_203.69.50.0 doesnt exist on devices: [FW_101] ([FW_102])."
  }
 ],
 "data": null
}		Response example

(create failure)

{
 "status": "Failure",
  "messages": [   {
   "code": "CREATE_ZONE_BASED_DEVICE_NOT_SUPPORT_GLOBAL_OBJECTS",
   "message": "Device 10_20_152_1 does not support global objects (requested action line 1)."
  }],
  "data": null
}