Create Rule Modification Change Request

Creates a rule modification change request. It accepts details about the modifications needed for rule configurations, including custom fields, actions to be applied, and the rule template to be used.

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

Request Method: POST

Request parameters:

Parameter Type Description
fields array An array of objects, each containing `name` and `values` for custom fields to be included in the rule modification request.
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 the mandatory field devices.

Note: devices field can contain one device only.

For more details, see:
values array An array of strings representing the values for the custom field.

requestActions

mandatory

array

An array of objects detailing actions to be applied to a rules (ruleId): application, destination, service, and source.

At least one of the fields (application, destination, service, and source) must be included.

Each request supports one requestAction only, and one single rule.

application object Details actions to be applied to the application.
destination object Details actions to be applied to the destination.

ruleId

mandatory

string The identifier of the rule to be modified.
service object Details actions to be applied to the service.
source object Details actions to be applied to the source.

actions

mandatory

array Array of objects determining the action to take.
action

mandatory

string

Determines the action to take. One of the following:

  • remove. Removes the item from the rule field.

  • add. Adds the item to the rule field.

item

mandatory

string The item to apply the action to.
template

mandatory

 string

The name of the change request template to use.

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.

Request example:

{
    "template": "145: Rule Modification Request",
    "fields": [{
            "key": "subject",
            "values": ["rule modification request"]
        }, {
            "key": "devices",
            "values": ["10_20_127_5_Modric_vsys1_default"]
        }, {
            "key": "due",
            "values": ["2025-01-09"]
        }, {
            "name": "requestor",
            "values": [
                "[email protected]"
            ]
        }, {
            "name": "CMS ticket id",
            "values": [
                "123"
            ]
        }, {
            "name": "expires",
            "values": [
                "2023-11-26"
            ]
        }
    ],
    "requestActions": [{
            "ruleId": "13-1",
            "source": {
                "actions": [{
                        "action": "add",
                        "item": "1.1.1.1"
                    }
                ]
            },
            "destination": {
                "actions": [{
                        "action": "remove",
                        "item": "ip-41.0.0.250"
                    }, {
                        "action": "add",
                        "item": "3.3.3.3"
                    }
                ]
            },
            "service": {
                "actions": [{
                        "action": "add",
                        "item": "ssh"
                    }, {
                        "action": "remove",
                        "item": "tcp-78"
                    }
                ]
            }
        }
    ]
}

cUrl Example:

curl -X POST "https://<localhost>/FireFlow/api/change-requests/rule-modification" -H "Content-Type: application/json" -d '{"template":"145: Rule Modification Request","fields":[{"key":"subject","values":["rule modification request"]},{"key":"devices","values":["10_20_127_5_Modric_vsys1_default"]},{"key":"due","values":["2025-01-09"]},{"name":"requestor","values":["[email protected]"]},{"name":"CMS ticket id","values":["123"]},{"name":"expires","values":["2023-11-26"]}],"requestActions":[{"ruleId":"13-1","source":{"actions":[{"action":"add","item":"1.1.1.1"}]},"destination":{"actions":[{"action":"remove","item":"ip-41.0.0.250"},{"action":"add","item":"3.3.3.3"}]},"service":{"actions":[{"action":"add","item":"ssh"},{"action":"remove","item":"tcp-78"}]}}]}'

Status codes:

Code Description  
200 Operation completed successfully  
400

Input validation failure

Message Code Message text Parameters
INVALID_DOMAIN New change requests cannot be created under the 'Management' domain. Please authenticate to a specific domain. N/A
FIELD_NOT_IN_TEMPLATE Change request template does not include the {0} field 0 – field name
INSUFFICIENT_FIELD_PERMISSIONS User has insufficient permissions on field {0} 0 - field name
FIREFLOW_FIELD_IS_DISABLED {0} field is disabled 0 – fireflow field full name
INVALID_VALUE_FOR_FIELD {0} field contains invalid value(s): {1} 0 - field name, 1 - value
INVALID_DATE_PATTERN Invalid date format in field: {0} 0 - field 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
DUPLICATED_VALUE Same {0} value(s) repeated multiple times ({1}) 0 – parameter name duplicated in the request (for example, devices, or rule id), 1 - the value
DUPLICATED_VALUE_IN_LINE Same {0} value(s) repeated multiple times ({1}, {2} line {3}) 0 – parameter name duplicated in the request (for example, devices), 1 - the value, 2 - “traffic”, 3 – line index
UNAUTHORIZED_DEVICE User has no permission for some of the devices in this request or some devices are not available N/A
INVALID_CF_CONTENT {0}: Field supposed to contain a single value 0 - custom field name
HIDDEN_FIELD {0} field cannot be used while it is configured as hidden (HideFieldsFromTicket) 0 – field name
PATTERN_NOT_MATCH {0}: Input must match {1} 0 - input value, 1 - pattern
INVALID_TEMPLATE_NAME Invalid Template Name: {0} 0 - template name
INVALID_FORM_TYPE Invalid template form type, form type should be: {0} 0 – request type (for example, “Rule Modification")
TEMPLATE_IS_DISABLED {0} template is disabled  0 – template display name 
NO_TEMPLATE_PERMISSION Access Denied. There are no permissions to use template: {0}. 0 - template name
INVALID_WORKFLOW_NAME Workflow {0} is invalid 0 – workflow name
USER_DISABLED User: {0} in field: {1} is disabled 0 – user, 1 – field name
INVALID_EMAIL_ADDRESS Invalid email format in field ({0}) 0 - any user fields (for example: requestor, owner, or cc)
USER_NOT_FOUND User: {0} in field: {1} was not found 0 – user, 1 - field name
INVALID_USER_REQUIRED_PERMISSIONS Selected user: {0} in fields {1} doesn't have the permissions to perform this action 0 - user name, 1 - field name
NOT_LOWEST_LEVEL_DEVICE {0} device is in an unsupported device level 0 – device name
EXTERNAL_VALIDATION_FAILED {0} 0 – external legacy error message 
FLOW_NOT_SUPPORTED_FOR_BRAND {0} flow is not supported for {1} 0 – “Rule modification change-request”, 1 - brand display name
MANDATORY_FIELD_MISSING Mandatory field is missing ({0}) 0 – request field name (for example, requestActions, or devices)
MANDATORY_FIELD_MISSING_IN_LINE Mandatory field is missing ({0}, {1} line {2}) 0 – request field name (for example, requestActions, or devices), 1 – “traffic”, 2 – line index
AT_LEAST_ONE_FIELD_REQUIRED_IN_LINE At least one traffic field is required (source/destination/service/application) ({0} line {1}) 0 – “traffic”, 1 – line index
CANNOT_MODIFY_BOTH_SERVICES_AND_APPLICATIONS_IN_LINE Cannot modify both services and applications ({0} line {1}) 0 – “traffic”, 1 – line index
CANNOT_REMOVE_ITEM_FROM_RULE_IN_LINE Unable to remove {0} from rule {1}. Rule fields cannot be empty. ({2} line {3}) 0 – field name, 1 – rule id, 2 - “traffic”, 3 – line index
INVALID_VALUE_FOR_FIELD_IN_LINE {0} field contains invalid value(s): {1} ({2} line {3}) 0 – field name, 1 – value, 2 - “traffic”, 3 – line index
INVALID_USE_OF_SPECIAL_OBJECTS_IN_FIELD {0} field does not support {1} object(s): {2} ({3} line {4}) 0 – field name 1 – unsupported type (for example, "security zone object") 2 - “traffic”, 3 – line index
INVALID_MIX_OF_SPECIAL_AND_OTHER_VALUE_TYPES_IN_FIELD {0} field does not support a mix of {1} object(s) {2} and other value types ({3} line {4}) 0 – field name, 1 – type (for example, “FQDN”), 2 – list of the unsupported values, 3 - “traffic”, 4 – line index
ITEM_TO_REMOVE_FROM_RULE_NOT_FOUND_IN_LINE Requested item(s) {0} to be removed from {1} does not exist on rule ({2} line {3}) 0 – missing items, 1 – field name, 2 - “traffic”, 3 – line index
ADDING_OR_REMOVING_USER_NOT_ALLOWED_IN_LINE Adding or removing users from {0} is not allowed ({1} line {2}) 0 – field name, 1 - “traffic”, 2 – line index
FIELD_CONTAIN_ANY_AND_ADDITIONAL_VALUES Cannot add "any" (or "*") {0} with additional {0} values ({0}, {1} line {2}) 0 – field name, 1 - “traffic”, 2 – line index
MIXED_TCP_UDP_AND_SPECIAL_SERVICES_IN_SERVICE_FIELD Please make sure the Service field does not contain a mix of tcp/udp and non tcp/udp entries ({0} line {1}) 0 - “traffic”, 1 – line index
PARSE_SPECIAL_PROTOCOL_RESULT_MIXED {0} service is not supported because it contains a mix of tcp/udp and non tcp/udp entries ({1} line {2}) 0 – service name, 1 - “traffic”, 2 – line index
FIELD_NOT_SUPPORTED_FOR_FLOW {0} field is not supported for {1} flow ({2} line {3}) 0 – field name, 1 – request type (for example, "Rule Modification"), 2 - “traffic”, 3 – line index
MANDATORY_FIELD_BY_CONFIGURATION {0} field is mandatory while {1} configuration is enabled ({2} line {3}) 0 – field name, 1 – configuration name, 2 - “traffic”, 3 – line index
FIELD_NOT_ALLOWED_BY_CONFIGURATION {0} field is not allowed while {1} configuration is disabled ({2} line {3}) 0 – field name, 1 – configuration name, 2 - “traffic”, 3 – line index
UNSUPPORTED_PROTOCOL Application {0} contains unsupported protocols ({1} line {2}) 0 – application name, 1 - “traffic”, 2 – line index
INVALID_RULEID Rule Id {0} was not found 0 – rule id
INVALID_RULE_PROPERTY_EXTENDED Rule {0} has {1}; these rules are not supported 0 – rule id, 1 – reason for the rule is not supported (for example, "services and applications", "invalid named objects", or "negated source") 
INVALID_RULE_SERVICE Rule {0} contains a special service; these rules are not supported 0 – rule id
INVALID_RULE_DISABLED Rule {0} is disabled; these rules are not supported 0 – rule id
INVALID_RULE_WITH_INVALID_NAMED_OBJECTS Rule {0} contains invalid named objects; these cannot be modified 0 – rule id
INVALID_RULE_ACTION Rule {0} contains a special action; these rules are not supported 0 – rule id
UNSUPPORTED_ACTION_ON_MULTIPLE_DEVICES Action on multiple devices is not supported, only single device N/A
INVALID_PATTERN Invalid Pattern N/A
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
INVALID_RULE_ID_NOT_FOUND_IN_ANALYSIS_REPORT Rule Id {0} was not found in analysis report 0 – rule id
 
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
 
500

Failed to complete operation.

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

Response parameters:

Element Type Description
status String

One of the following:

  • Success
  • Failure
messages Array
  code String A string that indicates the error message.
  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.

Response example success 200:

{
  "status": "Success",
  "messages": [],
  "data": {
    "changeRequestId": 3583,
    "redirectUrl": "https://10.20.10.26/FireFlow/Ticket/Display.html?id=3583"
  }
}

Response example failure 400: 

{
  "data": null,
  "messages": [
    {
      "code": "INVALID_RULEID",
      "message": "Invalid input parameters."
    }
  ],
  "status": "Failure"
}