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

Storing firewall suffix in host or service groups

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"

}

]

}

Status codes:

Code

Description

200

Traffic Change Request was created

400

Input validation failure

Error messages:

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

Error messages:

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

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"
				}
				]
				}
				}
				]
				}'

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": {
		// Data object
		},
		"messages": [
		{
		"code": "string",
	"message"message": "string"
}
],
"status": "Success"
}

Response Example Failure 400

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

Create a traffic change request

Sorry about that

Great!