Create a rule removal change request

The ruleRemovalChangeRequest creates a FireFlow change request to remove or disable a device rule, using the rule removal workflow.

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

Resource name: /FireFlow/api/change-requests/rule-removal

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
template String

The name of the change request template to use.
fields Array
  name String

The name of a field in the Change Request.

For example, enter Owner to set the value of the Owner field in the Change Request.

FireFlow validates the API for mandatory elements, such

Note: Each devices element can contain one device only, which must be a device from the lowest level in the AFA device tree.

For more details, see:
  values String

The value of the named field.

For example, if you are defining the Owner field, enter a username or email address.

requestActions Array
  action

Array

Determines the action to take. One of the following:

  • remove. Removes the rule completely.

  • disable. Disables the rule but does not remove it.

  • automatic. Determines the rule action based on whether the device supports disabling rules.

    If the device supports disabling rules, the action is translated consistently as disable. However, if the device does not support disabling rules, the action is translated as remove.

Each request supports one action only, even if it covers multiple rules. You cannot mix remove and disable actions for different rules.
  ruleId

String

 The ID of the rule to remove or disable.

The following date formats are supported:

  • DD-MM-YYYY, when DateDayBeforeMonth =1
  • MM-DD-YYYY, when DateDayBeforeMonth=0

If you are defining the device, you must enter the device database name, not the name displayed in the AFA device tree. Rule IDs must also be defined as the internal AFA IDs.

Retrieve both device database names and internal rule IDs 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.

Notes: For IPv6 templates, only Cisco ASA devices are supported.

The attachment field accepts single or multiple values, and expects the following syntax: 'filename=<filename>:content=<encoded file content to base64 string>'

Additionally:

  • Filenames must be valid Linux filenames, including valid characters only, no more than 255 characters, and not an empty string.

  • Files must also have valid extensions, and not be of any file types listed in the RestrictedFileExtensionsInAttachment configuration.

  • File content should be encoded to base 64.

  • Before encoding, the file content should not exceed the maximum size configured in the MaxAttachmentSize configuration parameter.

    For details, see FireFlow configuration parameter reference.

Response:

Element Type Description
status String

One of the following:

  • Success
  • Failure
messages Array
  code String A string that indicates the response code.
  message String Further details about the response, if needed.
data Array
  changeRequestID String The ID of the new Change Request created.
  redirectURL String A link to the new Change Request in FireFlow.

Code

Description
200

Operation completed successfully

400

Input validation failure

Message Code Message text Parameters
MULTIPLE_ACTIONS 'remove' and 'disable' actions cannot appear at the same request N/A
MANDATORY_FIELD_MISSING Mandatory field is missing ({0}) 0 - several options, like Device name, Action
INVALID_VALUE_FOR_FIELD {0} field contains invalid value(s): {1} 0 - field name, 1 - value
INVALID_VALUE_FOR_FIELD_IN_LINE {0} field contains invalid value(s): {1} ({2} line {3}) 0 - field name, 1 - line index, 2 - type, 3 - value
PATTERN_NOT_MATCH {0}: Input must match {1} 0 - input value 1 - pattern
INVALID_PATTERN Invalid Pattern N/A
INVALID_TEMPLATE_NAME Invalid Template Name: {0} 0 - template name
INVALID_DOMAIN New change requests cannot be created under the 'Management' domain. Please authenticate to a specific domain.
USER_NOT_FOUND User: {0} in field: {1} was not found 0 - user 1 - field name
INVALID_FORM_TYPE Invalid template form type, form type should be: {0} 0 - RequestType ("Traffic Change"/"Rule Removal"...)
NO_TEMPLATE_PERMISSION Access Denied. There are no permissions to use template: {0}. 0 - template name
INVALID_CF_CONTENT {0}: Field supposed to contain a single value 0 - custom field name
INSUFFICIENT_FIELD_PERMISSIONS User have insufficient permissions on field {0} 0 - custom field name
INVALID_USER_REQUIRED_PERMISSIONS elected user: {0} in fields {1} doesn't have the permissions to perform this action 0 - user name, 1 - field name
INVALID_USER_REQUIRED_PERMISSIONS elected user: {0} in fields {1} doesn't have the permissions to perform this action 0 - user name, 1 - field name
UNSUPPORTED_ACTION_ON_MULTIPLE_DEVICES Action on multiple devices is not supported, only single device N/A
RULE_REMOVAL_UNSUPPORTED_REQUEST_ACTION {0} action is not supported for brand {1} 0 - action (currently only 'disable') 1 - brand id
NUMBER_OF_TRAFFIC_LINES_OUT_OF_BOUNDS {0} traffic lines not within supported range: {1} .. {2} 0- number of traffic lines, 1- MIN_NUM_OF_TRAFFIC_LINES = 1, 2-MAX_NUM_OF_TRAFFIC_LINES = 500
FLOW_NOT_SUPPORTED_FOR_BRAND {0} flow is not supported for {1} 0- Flow (for example : Multi object change-request…...) 1- device/brand
INVALID_RULEID Rule Id {0} was not found 0- Rule id
INVALID_RULE_ACTION Rule {0} contains a special action; these rules are not supported 0- Rule id
INVALID_RULE_PROPERTY Rule {0} has a special property; these rules are not supported 0- Rule id
INVALID_RULE_SERVICE Rule {0} contains a special service; these rules are not supported 0- Rule id
DUPLICATED_VALUE Same {0} value(s) repeated multiple times ({1}) 0- param name that duplicated in the request (for now : ruleId/devices) 1- The value
NOT_LOWEST_LEVEL_DEVICE {0} device is in an unsupported device level  0 – device name 
INVALID_FILENAME Invalid filename for {0} field ({1})  0 – field name , 1 – file name 
UNSUPPORTED_FILENAME_EXTENSION Unsupported filename extension for {0} field ({1})  0 – field name , 1 – file name 
INVALID_BASE64_CONTENT Invalid content for {0} field ({1}); attachments must be base64 encoded string(s)  0 – field name , 1 – file name 
EXCEEDED_MAX_FILE_SIZE File {0} exceeded maximum size quota ({1} bytes)  0 – field name , 1 – file name 
TEMPLATE_IS_DISABLED {0} template is disabled  0 – Template display name 
TEMPLATE_CANNOT_BE_USED_WITH_SELECTED_DEVICE {0} template cannot be used with device {1}  0 – Template display name , 1 - device 
FIREFLOW_FIELD_IS_DISABLED {0} field is disabled  0 – fireflow field full name 
HIDDEN_FIELD {0} field cannot be used while it is configured as hidden (HideFieldsFromTicket)  0 – field name 
FIELD_NOT_IN_TEMPLATE Change request template does not include the {0} field  0 – field name 
INVALID_EMAIL_ADDRESS Invalid email format in field ({0}) 0 - any user fields like requestor, owner and cc
UNSUPPORTED_SPECIAL_SERVICES The following special service objects are with numeric values and not supported: {0} 0 - numeric services names
BAD_JSON_FORMAT Bad JSON format: {0} 0 - "failed to parse request body"
BAD_MEDIA_TYPE Content-Type header is missing or has unsuitable value N/A
UNAUTHORIZED_DEVICE User has no permission for some of the devices in this request or some devices are not available N/A
403

Authentication failure

Message Code Message text Parameters
NO_PERMISSIONS There are no permissions to process the requested operation N/A
INVALID_SESSION_KEY The session key provided is invalid N/A
EXPIRED_SESSION_KEY The session key provided has expired N/A
BAD_COOKIE_HEADER Cookie header is missing or has non-expected value N/A
UNAUTHORIZED_DEVICE User has no permission for some of the devices in this request or some devices are not available N/A
500

Failed to complete operation.

Message Code Message text Parameters
UNEXPECTED_ERROR_OCCURRED Unexpected error occurred N/A

 

Rule removal request example:

{
"template": "140: Rule Removal Request",
  "fields":
   [    {
    "name":"subject",
    "values":[
    "subject1111"              
   ]
   },
   {
   "name":"Owner",
   "values":[
    "[email protected]"                
   ]
   },         
   {
    "name": "devices",
    "values": ["<device ID>"]
   }
   ],
   "requestActions": 
   [
   {
    "action": "remove",
    "ruleId": "<ruleID>"
   }
 ]}
}

Rule removal request example (multiple rules)

{

"template": "140: Rule Removal Request",

"fields":

[

{

"key": "subject",

"values": ["test55"]

},

{

"key": "devices",

"values": ["Orit_GW2"]

}

],

"requestActions":

[

{

"action": "remove",

"ruleId": "BC100ABA-446E-493B-9707-604C2A493676"

},

{

"action": "remove",

"ruleId": "88784DAF-C0A9-4B06-AE94-E8199A802EAC"

}

]

}

Rule removal response example (success)

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

Rule removal response example (failure)

{
 "status": "Failure",
 "messages": [   {
  "code": "DEVICES_NOT_FOUND",
  "message": "Cannot find devices: <device ID>."
 }],
 "data": null
}