Create a traffic change request

The FireFlow REST API creates a Traffic Change Request.

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: For IPv6 addresses, you must use IPv6 format for both source and destination. For example: 2001:cdba::3257:9652 - 2001:cdba::3257:9657. See IPv6 traffic change workflow.

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

Resource Name: /FireFlow/api/change-requests/traffic

Request Method: POST

Header requirements:

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

Request Body:

Parameter

Type

Description
trafficChangeRequestDetails

TrafficChangeRequest type

Object body containing details for creation of traffic change request.

TrafficChangeRequest

Parameter Type Description
fields array Array of Fields
template string Template string
traffic array Array of Traffic

Fields

Parameter Type Description
name string Custom field name
values array Custom field values

TrafficLineDetails (part of Traffic array)

Parameter Type Description
action string Action: Allow or Drop
application object Application details
destination object Destination details
fields array Array of Fields
natDetails object NAT details
service object Service details
source object Source details
user object User details

NameTrafficFieldDetails (part of Application, Destination, Source, and User)

Parameter Type Description
items array Array of NameTrafficItemDetails

NameTrafficItemDetails

Parameter Type Description
fields array Array of Fields
name string Name to match

AddressTrafficFieldDetails (part of Destination and Source)

Parameter Type Description
items array Array of AddressTrafficItemDetails

AddressTrafficItemDetails

Parameter Type Description
address string IP address
fields array Array of Fields

ServiceTrafficFieldDetails (part of Service)

Parameter Type Description
items array Array of ServiceTrafficItemDetails

ServiceTrafficItemDetails

Parameter Type Description
fields array Array of Fields
service string Service name

NatDetails (part of TrafficLineDetails)

Parameter Type Description
destination array Destination array
port array Port array
source array Source array
type string NAT type

If you are using the StoreFirewallSuffixInHostGroup and StoreFirewallSuffixInServiceGroup configuration, the address format in source and destination fields must be as follows:

Firewall suffixes

This definition is translated from the firewall as follows:

<object_name>:fw:<firewall treeName>

For example: host-1:fw:My_GW1
Group suffixes

This definition is translated from the one of the group members, as follows:

<object_name>:grp:<firewall treeName>

For example: grp-1:grp:My_GW1

Source with firewall suffix example:

{

"source": {

"items": [{

"address": "host-1:fw:My_GW1"

}

]

}

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.

Request example

{ "template": "Basic Change Traffic Request", "fields": [ { "key": "subject", "values": [ "Traffic_Ticket_Via_REST_API" ] }, { "key": "Change Request Description", "values": [ "add here the change request description" ] }, { "name": "devices", "values": [ "CKP1", "Cisco2" ] } ], "traffic": [ { "source": { "items": [ { "name": "1.1.1.0/24" }, { "name": "host_object" } ] }, "destination": { "items": [ { "name": "2.2.2.2-2.2.2.150", "fields": [ { "key": "CFPTI", "values": [ "destination1" ] } ] } ] }, "service": { "items": [ { "name": "https" }, { "name": "service_object" } ] }, "user": { "items": [ { "name": "user1" } ] }, "application": { "items": [ { "name": "any" } ] }, "action": "Allow", "natDetails": { "source": [ "9.9.9.9" ], "destination": [ "8.8.8.8" ], "port": [ "tcp/8080" ], "type": "Static" }, "fields": [ { "key": "Requested Source Group Name", "values": [ "sourceGroup100" ] } ] } ] }

IPv6 request example

{
  "template": "170: Traffic Change Request (IPv6)",
  "fields": [
    {
      "name": "subject",
      "values": [
        "IPv6_demo_3"
      ]
    },
    {
      "name": "devices",
      "values": [
        "10_132_16_2"
      ]
    }
  ],
  "traffic": [
    {
      "source": {
        "items": [
          {
            "address": "fe80:2222::3333"
          }
        ]
      },
      "destination": {
        "items": [
          {
            "address": "2001:cdba::3257:9652 - 2001:cdba::3257:9657"
          }
        ]
      },
      "service": {
        "items": [
          {
            "name": "tcp/80-90"
          }
        ]
      },
      "action": "Allow"
    }
  ]
}

cURL example

curl --request POST \ --url https://<localhost>/FireFlow/api/change-requests/traffic \ --header 'Content-Type: application/json' \ --data '{ "fields": [ { "name": "custom field name", "values": [ "custom field value 1", "custom field value 2" ] } ], "template": "string", "traffic": [ { "action": "Allow/Drop", "application": { "items": [ { "fields": [ { "name": "custom field name", "values": [ "custom field value 1", "custom field value 2" ] } ], "name": "name to match" } ] }, "destination": { "items": [ { "address": "1.1.1.1", "fields": [ { "name": "custom field name", "values": [ "custom field value 1", "custom field value 2" ] } ] } ] }, "fields": [ { "name": "custom field name", "values": [ "custom field value 1", "custom field value 2" ] } ], "natDetails": { "destination": [ "string" ], "port": [ "string" ], "source": [ "string" ], "type": "Static/Dynamic" }, "service": { "items": [ { "fields": [ { "name": "custom field name", "values": [ "custom field value 1", "custom field value 2" ] } ], "service": "tcp/80" } ] }, "source": { "items": [ { "address": "1.1.1.1", "fields": [ { "name": "custom field name", "values": [ "custom field value 1", "custom field value 2" ] } ] } ] }, "user": { "items": [ { "fields": [ { "name": "custom field name", "values": [ "custom field value 1", "custom field value 2" ] } ], "name": "name to match" } ] } } ] }

Status codes:

Code

Description
200

Traffic Change Request was created

400

Input validation failure

Message Code Message text Parameters
MANDATORY_FIELD_MISSING_IN_LINE Mandatory field is missing ({0}, {1} line {2}) 0 - field name, 1 - type, 2 - line
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
INVALID_VALUE_FOR_FIELD_POSSIBLE_VALUES_IN_LINE{0} {0} field contains invalid value(s): {1}. Valid values are {2} ({3} line {4}) 0 - field name, 1 - line index, 2 - type, 3 - value, 4 - line index
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
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 - entry 2 - line index
PARSE_SPECIAL_PROTOCOL_RESULT_MISSING Could not find matching applications for all requested services ({0} line {1}) 0 - services 1 - 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 type 1 - line index
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
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
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- request line index
UNSUPPORTED_PROTOCOL Application {0} contains unsupported protocols ({1} line {2}) 0- Application name, 1- protocol, 2- line index
NAT_AT_LEAST_ONE_FIELD_REQUIRED At least one NAT field is required (Source/Destination/Port) ({0} line {1}) 0- RequestLineType ( traffic/requested action), 1- request line Index
NAT_UNSUPPORTED_TRAFFIC_ACTION NAT can only be defined for traffic with action 'Allow' ({0} line {1}) 0- RequestLineType ( traffic/requested action) 1- request line index
FIELD_NOT_FOUND {0} field was not found 0- custom field
DUPLICATED_VALUE_IN_LINE Same {0} value(s) repeated multiple times ({1}, {2} line {3})  0 – field name 1 –  value 2 – request line type  3 - traffic line index  
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 
EXTERNAL_VALIDATION_FAILED {0}  0 – External legacy error message 
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_ALLOWED_BY_CONFIGURATION {0} field is not allowed while {1} configuration is disabled ({2} line {3})  0 – field name , 1 – configuration ,2 – request line type, 3 – traffic line index  
MANDATORY_FIELD_BY_CONFIGURATION {0} field is mandatory while {1} configuration is enabled ({2} line {3})  0 – field name , 1 – configuration ,2 – request line type, 3 – traffic line index  
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
FIELD_NOT_SUPPORTED_FOR_FLOW {0} field is not supported for {1} flow ({2} line {3}) 0 - field,1 - flow, 2 - Traffic , 3 - line index  
APPLICATION_DEFAULT_ANY_SERVICE_UNSUPPORTED Cannot add 'application-default' service without selecting applications ({0} line {1})
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
50x

Internal Server Error

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

Response parameters

Parameter Data Type Description
data object Data object
messages array Array of messages
status string Status of request

MessageDetails (part of Messages array)

Parameter Type Description
code string Code
message string Message

Response Example Success 200

{
  "data": {},
  "messages": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "status": "Failure"
}

Response Example Failure 400

{
  "data": {},
  "messages": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "status": "Failure"
}