IR-Flow Client¶

Python SDK and Wrapper for the IR-Flow REST API

class irflow_client.irflow_client.IRFlowClient(config_args=None, config_file=None)[source]¶

Bases: object

Python SDK for the IR-Flow REST API.

__init__(config_args=None, config_file=None)[source]¶

Create an API Client instance

Creates API Client to IR-Flow API. Default timeout is 5 seconds on connect and 30 seconds on response.

Parameters:	config_args (dict) – Key, Value pairs of IR-Flow API configuration options config_file (str) – Path to a valid Ir-Flow configuration file

static _build_user_agent()[source]¶

Builds the current version User-Agent String

Returns:	user-agent
Return type:	str

_get_config_args_params(config_args)[source]¶

Helper function to check/parse configuration arguments provided as a dict

Parameters:	config_args (dict) – A dict of the following keys:
Keys:	address (str) – IR-Flow Server FQDN or IP Address api_user (str) – IR-Flow API User api_key (str) – above user’s api key protocol (str) – https unless otherwise specified, default = HTTPS debug (bool) – enable debug output, default = None verbose (int) – turn up the verbosity default = 0 (optional)

_get_config_file_params(config_file)[source]¶

Helper function to parse configuration arguments from a valid IR-Flow configuration file

Parameters:	config_file (str) – Path to a valid IR-Flow configuration file

add_item_to_picklist(picklist_id, value, label, description=None)[source]¶

Add an item with the provided value, label, and description to the picklist: matching the provided ID

Parameters:	picklist_id (int) – The IR-Flow assigned ID of the picklist to which the new item should be added value (str) – The string value submitted to actions and integrations for this picklist item label (str) – The label to be displayed for this picklist item description (str) – An optional description for this picklist item
Returns:	The full json response object from the IR-Flow API
Return type:	dict

assign_user_to_alert(alert_num, username)[source]¶

Assign a user to an Alert

Parameters:	alert_num (int) – The IR-Flow Assigned Alert Number of the Alert to attach to the specified incident username (string) – The IR-Flow User to assign to an alert
Returns:	The full json response object returned by the IR-Flow API.
Return type:	dict

attach_alert_to_incident(alert_num, incident_num)[source]¶

Attach the specified alert to the specified incident

Parameters:	incident_num (int) – The Incident Number of the Incident to which the specified alert should be attached alert_num (int) – The IR-Flow Assigned Alert Number of the Alert to attach to the specified incident
Returns:	The full json response object returned by the IR-Flow API
Return type:	dict

attach_field_to_object_type(object_type_name, field_name, object_type_id=None, field_id=None)[source]¶

Attach an existing field to an object of the specified name or id

Parameters:	object_type_name (str) – The string name of the object to which the specified field should be added - required only if no object_type_id is provided field_name (str) – The string name of the field to be added to the specified object - required only if no field_id is provided object_type_id (int) – The IR-Flow assigned ID of the object to which the specified field should be added - required only if no object_type_name is provided field_id (int) – The IR-Flow assigned IF of the field to be added to the specified object - required only if no field_name is provided
Returns:	The full json response object from the IR-Flow API
Return type:	dict

attach_incident_to_alert(incident_num, alert_num)[source]¶

Attach the specified alert to the specified incident

Note

This API endpoint will be deprecated in a future release. You should use attach_alert_to_incident(), which accomplishes the same outcome, and is how this would be done naturally in the interface. No new code should use this function.

Parameters:	incident_num (int) – The Incident Number of the Incident to which the specified alert should be attached alert_num (int) – The IR-Flow Assigned Alert Number of the Alert to attach to the specified incident
Returns:	The full json response object returned by the IR-Flow API
Return type:	dict

close_alert(alert_num, close_reason)[source]¶

Close the alert with the provided number, for the provided reason

Parameters:	alert_num (int) – The IR-Flow assigned alert number of the alert to close close_reason (str) – The reason for which to close the desired alert
Returns:	The full json response object returned by the IR-Flow API
Return type:	dict

create_alert(alert_fields, description=None, incoming_field_group_name=None, suppress_missing_field_warning=False)[source]¶

Create an alert of the desired field group name with the specified fields and description

Parameters:	alert_fields (dict) – Key, Value pairs of fields configured in IR-Flow and their values description (str) – An optional string description for the alert incoming_field_group_name (str) – The string name of the incoming field group name for this alert as specified in IR-Flow suppress_missing_field_warning (bool) – Suppress the API warnings indicating missing fields if True - defaults to False
Returns:	The full json response object from the IR-Flow API
Return type:	dict

create_incident(incident_type_name, incident_fields=None, incident_subtype_name=None, description=None, priority_id=None, owner_id=None)[source]¶

Create an incident of the desired type and subtype with the specified fields: and description

Parameters:

incident_type_name (str) – The string name of the incident type with which this incident should be created
incident_subtype_name (str) – The string name of the incident subtype with which this incident should be created (optional)
incident_fields (dict) – Key, Value pairs of fields configured in IR-Flow and their values (optional)
description (str) – An optional string description for the incident
priority_id (str) – ID of the priority to set
owner_id (str) – ID of the user to set incident owner to

create_object_type(type_name, type_label, parent_type_name=None, parent_type_id=None)[source]¶

Create an object type of the provided parent type or id with the provided name and label

Parameters:	type_name (str) – The string name for this object type type_label (str) – The label for this object type parent_type_name (str) – The string name of the parent object type - required if no parent_type_id is specified parent_type_id (int) – The id of the parent object type - required if no parent_type_name is specified
Returns:	The full json response object from the IR-Flow API
Return type:	dict

create_picklist_item(picklist_id, value, label, description=None)[source]¶

Create a new item in a specified picklist

Parameters:	picklist_id (int) – The IR-Flow assigned ID of the picklist to which the new item should be added value (str) – The string value submitted to actions and integrations for this picklist item label (str) – The label to be displayed for this picklist item description (str) – An optional description for this picklist item
Returns:	The full json response object from the IR-Flow API
Return type:	dict

delete_picklist_item(picklist_item_id)[source]¶

Mark a picklist item as deleted

Parameters:	picklist_item_id (int) – The IR-Flow assigned ID of the picklist item to be deleted
Returns:	The full json response object from the IR-Flow API
Return type:	dict

download_attachment(attachment_id, attachment_output_file)[source]¶

Download the attachment with the specified ID

Parameters:	attachment_id (int) – The ID of the attachment to be downloaded attachment_output_file (str) – The full path to the file on disk to which the desired attachment should be saved

download_attachment_string(attachment_id)[source]¶

Download an attachment and return it as text

Parameters:	attachment_id (int) – The ID of the attachment to be downloaded
Returns:	The textual contents of the downloaded file
Return type:	str

dump_request_debug_info(heading, url, headers=None, data=None, params=None)[source]¶

Helper function to dump request info to the debug stream on the logging bus

Parameters:

heading (str) – A string heading for the debug message - typically the name of the endpoint being queried
url (str) – The full url of the API endpoint
headers (dict) – The headers of this request, if desired
data (dict) – Key, Value pairs of data in the body of a request, if desired
params (dict) – Key, Value pairs of parameters passed in a request, if desired

dump_response_debug_info(heading, status, json)[source]¶

Helper function to dump response info from a request to the debug stream: on the logging bus

Parameters:	heading (str) – A string heading for the debug message, the word ‘Response’ will be appended status (int) – The HTTP response code of the previously made request json (dict) – The full json response body as returned by the IR-Flow API

dump_settings()[source]¶: Helper function to print configuration information

get_alert(alert_num)[source]¶

Retrieve the alert with the specified alert number

Parameters:	alert_num (int) – The IR-Flow assigned alert number of the alert to retrieve
Returns:	The full json response object from the IR-Flow API
Return type:	dict

get_fact_group(fact_group_id)[source]¶

Retrieve the current data in the specified fact group

Parameters:	fact_group_id (int) – The IR-Flow assigned IF of the fact_group to retrieve
Returns:	The full json response object from the IR-Flow API
Return type:	dict

static get_field_by_name(field_name, field_list)[source]¶

Helper function to return a field via a string name match given a field and field list

Parameters:	field_name (str) – The string name of the desired field field_list (list) – A list of field objects
Returns:	The field object if found, None otherwise
Return type:	dict

get_incident(incident_num)[source]¶

Retrieve the incident with the specified ID

Parameters:	incident_num (int) – The IR-Flow assigned ID of the incident to be retrieved
Returns:	The full json response object from the IR-Flow API
Return type:	dict

get_picklist(picklist_id)[source]¶

Retrieve the picklist with the desired ID

Parameters:	picklist_id (int) – The IR-Flow assigned id of the picklist to be retrieved
Returns:	The full json response object from the IR-Flow API
Return type:	dict

get_picklist_item(picklist_item_id)[source]¶

Retrieve the picklist item corresponding to the specified ID

Parameters:	picklist_item_id (int) – The IR-Flow assigned ID of the picklist item to be retrieved
Returns:	The full json response object from the IR-Flow API
Return type:	dict

get_version()[source]¶

Function to get Current IR-Flow Version

Returns:	IR-Flow Version Number Example: 4.6.0
Return type:	str

list_picklist_items(picklist_id, with_trashed=False, only_trashed=False)[source]¶

Retrieve a list of all picklist items in a specified list

Parameters:	picklist_id (int) – The IR-Flow Assigned ID of the picklist whose items to list with_trashed (bool) – Include deleted items - False by default only_trashed (bool) – Only list deleted items - False by default
Returns:	The full json response object from the IR-Flow API
Return type:	dict

list_picklists(with_trashed=False, only_trashed=False)[source]¶

List all picklists

Parameters:	with_trashed (bool) – Include deleted picklists - False by default only_trashed (bool) – List only deleted picklists - False by default
Returns:	The full json response object from the IR-Flow API
Return type:	dict

put_fact_group(fact_group_id, fact_data)[source]¶

Put new or updated fact data in the specified fact group

Parameters:	fact_group_id (int) – The IR-Flow assigned ID of the fact_group to be updated fact_data (dict) – Key, Value pairs of fact fields as specified in IR-Flow and their values
Returns:	The full json response object from the IR-Flow API
Return type:	dict

restore_picklist_item(picklist_item_id)[source]¶

Restore a previously deleted picklist item

Parameters:	picklist_item_id (int) – The IR-Flow assigned ID of the picklist item to be restored
Returns:	The full json response object from the IR-Flow API
Return type:	dict

update_incident(incident_num, incident_fields, incident_type_name, owner_id, group_ids, incident_subtype_name=None, description=None, priority_id=None)[source]¶

Update the incident of the provided number, type, and subtype with the provided: fields and description

Parameters:	incident_num (int) – The IR-Flow assigned ID of the incident to update incident_fields (dict) – Key, Value pairs of fields configured in IR-Flow and their values incident_type_name (str) – The string name of the incident type of the desired incident owner_id (int) – The id of the user that will own this incident group_ids (list of int) – The ids of the groups this incident will belong to. incident_subtype_name (str) – The string name of the incident subtype of the desired incident (optional) description (str) – An optional string description for the incident
Returns:	The full json response object from the IR-Flow API
Return type:	dict

upload_attachment_to_alert(alert_num, filename)[source]¶

Upload an attachment to the specified alert

Parameters:	alert_num (int) – The IR-Flow Assigned Alert number of the Alert to which the desired filed should be uploaded filename (str) – The path to the file to be uploaded
Returns:	The full json response object returned by the IR-Flow API
Return type:	dict

upload_attachment_to_incident(incident_id, filename)[source]¶

Upload an attachment to the specified incident

Parameters:	incident_id (int) – The ID of the Incident to which the desired file should be uploaded filename (str) – The path to the file to be uploaded
Returns:	The full json response object returned by the IR-Flow API
Return type:	dict

upload_attachment_to_task(task_id, filename)[source]¶

Upload an attachment to the specified task

Parameters:	task_id (int) – The ID of the task to which the desired file should be uploaded filename (str) – The path to the file to be uploaded
Returns:	The full json response object returned by the IR-Flow API
Return type:	dict

exception irflow_client.irflow_client.IRFlowClientConfigError[source]¶

Bases: Exception

Raised on Config Errors

exception irflow_client.irflow_client.IRFlowMaintenanceError[source]¶

Bases: Exception

Raised on HTTP 503 from IR-Flow App, likely being upgraded.

class irflow_client.irflow_client.IRFlowClient(config_args=None, config_file=None)[source]

Bases: object

Python SDK for the IR-Flow REST API.

__init__(config_args=None, config_file=None)[source]

Create an API Client instance

Creates API Client to IR-Flow API. Default timeout is 5 seconds on connect and 30 seconds on response.

Parameters:	config_args (dict) – Key, Value pairs of IR-Flow API configuration options config_file (str) – Path to a valid Ir-Flow configuration file

static _build_user_agent()[source]

Builds the current version User-Agent String

Returns:	user-agent
Return type:	str

_get_config_args_params(config_args)[source]

Helper function to check/parse configuration arguments provided as a dict

Parameters:	config_args (dict) – A dict of the following keys:
Keys:	address (str) – IR-Flow Server FQDN or IP Address api_user (str) – IR-Flow API User api_key (str) – above user’s api key protocol (str) – https unless otherwise specified, default = HTTPS debug (bool) – enable debug output, default = None verbose (int) – turn up the verbosity default = 0 (optional)

_get_config_file_params(config_file)[source]

Helper function to parse configuration arguments from a valid IR-Flow configuration file

Parameters:	config_file (str) – Path to a valid IR-Flow configuration file

add_item_to_picklist(picklist_id, value, label, description=None)[source]

Add an item with the provided value, label, and description to the picklist: matching the provided ID

Parameters:	picklist_id (int) – The IR-Flow assigned ID of the picklist to which the new item should be added value (str) – The string value submitted to actions and integrations for this picklist item label (str) – The label to be displayed for this picklist item description (str) – An optional description for this picklist item
Returns:	The full json response object from the IR-Flow API
Return type:	dict

assign_user_to_alert(alert_num, username)[source]

Assign a user to an Alert

Parameters:	alert_num (int) – The IR-Flow Assigned Alert Number of the Alert to attach to the specified incident username (string) – The IR-Flow User to assign to an alert
Returns:	The full json response object returned by the IR-Flow API.
Return type:	dict

attach_alert_to_incident(alert_num, incident_num)[source]

Attach the specified alert to the specified incident

Parameters:	incident_num (int) – The Incident Number of the Incident to which the specified alert should be attached alert_num (int) – The IR-Flow Assigned Alert Number of the Alert to attach to the specified incident
Returns:	The full json response object returned by the IR-Flow API
Return type:	dict

attach_field_to_object_type(object_type_name, field_name, object_type_id=None, field_id=None)[source]

Attach an existing field to an object of the specified name or id

Parameters:	object_type_name (str) – The string name of the object to which the specified field should be added - required only if no object_type_id is provided field_name (str) – The string name of the field to be added to the specified object - required only if no field_id is provided object_type_id (int) – The IR-Flow assigned ID of the object to which the specified field should be added - required only if no object_type_name is provided field_id (int) – The IR-Flow assigned IF of the field to be added to the specified object - required only if no field_name is provided
Returns:	The full json response object from the IR-Flow API
Return type:	dict

attach_incident_to_alert(incident_num, alert_num)[source]

Attach the specified alert to the specified incident

Note

This API endpoint will be deprecated in a future release. You should use attach_alert_to_incident(), which accomplishes the same outcome, and is how this would be done naturally in the interface. No new code should use this function.

Parameters:	incident_num (int) – The Incident Number of the Incident to which the specified alert should be attached alert_num (int) – The IR-Flow Assigned Alert Number of the Alert to attach to the specified incident
Returns:	The full json response object returned by the IR-Flow API
Return type:	dict

close_alert(alert_num, close_reason)[source]

Close the alert with the provided number, for the provided reason

Parameters:	alert_num (int) – The IR-Flow assigned alert number of the alert to close close_reason (str) – The reason for which to close the desired alert
Returns:	The full json response object returned by the IR-Flow API
Return type:	dict

create_alert(alert_fields, description=None, incoming_field_group_name=None, suppress_missing_field_warning=False)[source]

Create an alert of the desired field group name with the specified fields and description

Parameters:	alert_fields (dict) – Key, Value pairs of fields configured in IR-Flow and their values description (str) – An optional string description for the alert incoming_field_group_name (str) – The string name of the incoming field group name for this alert as specified in IR-Flow suppress_missing_field_warning (bool) – Suppress the API warnings indicating missing fields if True - defaults to False
Returns:	The full json response object from the IR-Flow API
Return type:	dict

create_incident(incident_type_name, incident_fields=None, incident_subtype_name=None, description=None, priority_id=None, owner_id=None)[source]

Create an incident of the desired type and subtype with the specified fields: and description

Parameters:

incident_type_name (str) – The string name of the incident type with which this incident should be created
incident_subtype_name (str) – The string name of the incident subtype with which this incident should be created (optional)
incident_fields (dict) – Key, Value pairs of fields configured in IR-Flow and their values (optional)
description (str) – An optional string description for the incident
priority_id (str) – ID of the priority to set
owner_id (str) – ID of the user to set incident owner to

create_object_type(type_name, type_label, parent_type_name=None, parent_type_id=None)[source]

Create an object type of the provided parent type or id with the provided name and label

Parameters:	type_name (str) – The string name for this object type type_label (str) – The label for this object type parent_type_name (str) – The string name of the parent object type - required if no parent_type_id is specified parent_type_id (int) – The id of the parent object type - required if no parent_type_name is specified
Returns:	The full json response object from the IR-Flow API
Return type:	dict

create_picklist_item(picklist_id, value, label, description=None)[source]

Create a new item in a specified picklist

Parameters:	picklist_id (int) – The IR-Flow assigned ID of the picklist to which the new item should be added value (str) – The string value submitted to actions and integrations for this picklist item label (str) – The label to be displayed for this picklist item description (str) – An optional description for this picklist item
Returns:	The full json response object from the IR-Flow API
Return type:	dict

delete_picklist_item(picklist_item_id)[source]

Mark a picklist item as deleted

Parameters:	picklist_item_id (int) – The IR-Flow assigned ID of the picklist item to be deleted
Returns:	The full json response object from the IR-Flow API
Return type:	dict

download_attachment(attachment_id, attachment_output_file)[source]

Download the attachment with the specified ID

Parameters:	attachment_id (int) – The ID of the attachment to be downloaded attachment_output_file (str) – The full path to the file on disk to which the desired attachment should be saved

download_attachment_string(attachment_id)[source]

Download an attachment and return it as text

Parameters:	attachment_id (int) – The ID of the attachment to be downloaded
Returns:	The textual contents of the downloaded file
Return type:	str

dump_request_debug_info(heading, url, headers=None, data=None, params=None)[source]

Helper function to dump request info to the debug stream on the logging bus

Parameters:

heading (str) – A string heading for the debug message - typically the name of the endpoint being queried
url (str) – The full url of the API endpoint
headers (dict) – The headers of this request, if desired
data (dict) – Key, Value pairs of data in the body of a request, if desired
params (dict) – Key, Value pairs of parameters passed in a request, if desired

dump_response_debug_info(heading, status, json)[source]

Helper function to dump response info from a request to the debug stream: on the logging bus

Parameters:	heading (str) – A string heading for the debug message, the word ‘Response’ will be appended status (int) – The HTTP response code of the previously made request json (dict) – The full json response body as returned by the IR-Flow API

dump_settings()[source]: Helper function to print configuration information

get_alert(alert_num)[source]

Retrieve the alert with the specified alert number

Parameters:	alert_num (int) – The IR-Flow assigned alert number of the alert to retrieve
Returns:	The full json response object from the IR-Flow API
Return type:	dict

get_fact_group(fact_group_id)[source]

Retrieve the current data in the specified fact group

Parameters:	fact_group_id (int) – The IR-Flow assigned IF of the fact_group to retrieve
Returns:	The full json response object from the IR-Flow API
Return type:	dict

static get_field_by_name(field_name, field_list)[source]

Helper function to return a field via a string name match given a field and field list

Parameters:	field_name (str) – The string name of the desired field field_list (list) – A list of field objects
Returns:	The field object if found, None otherwise
Return type:	dict

get_incident(incident_num)[source]

Retrieve the incident with the specified ID

Parameters:	incident_num (int) – The IR-Flow assigned ID of the incident to be retrieved
Returns:	The full json response object from the IR-Flow API
Return type:	dict

get_picklist(picklist_id)[source]

Retrieve the picklist with the desired ID

Parameters:	picklist_id (int) – The IR-Flow assigned id of the picklist to be retrieved
Returns:	The full json response object from the IR-Flow API
Return type:	dict

get_picklist_item(picklist_item_id)[source]

Retrieve the picklist item corresponding to the specified ID

Parameters:	picklist_item_id (int) – The IR-Flow assigned ID of the picklist item to be retrieved
Returns:	The full json response object from the IR-Flow API
Return type:	dict

get_version()[source]

Function to get Current IR-Flow Version

Returns:	IR-Flow Version Number Example: 4.6.0
Return type:	str

list_picklist_items(picklist_id, with_trashed=False, only_trashed=False)[source]

Retrieve a list of all picklist items in a specified list

Parameters:	picklist_id (int) – The IR-Flow Assigned ID of the picklist whose items to list with_trashed (bool) – Include deleted items - False by default only_trashed (bool) – Only list deleted items - False by default
Returns:	The full json response object from the IR-Flow API
Return type:	dict

list_picklists(with_trashed=False, only_trashed=False)[source]

List all picklists

Parameters:	with_trashed (bool) – Include deleted picklists - False by default only_trashed (bool) – List only deleted picklists - False by default
Returns:	The full json response object from the IR-Flow API
Return type:	dict

put_fact_group(fact_group_id, fact_data)[source]

Put new or updated fact data in the specified fact group

Parameters:	fact_group_id (int) – The IR-Flow assigned ID of the fact_group to be updated fact_data (dict) – Key, Value pairs of fact fields as specified in IR-Flow and their values
Returns:	The full json response object from the IR-Flow API
Return type:	dict

restore_picklist_item(picklist_item_id)[source]

Restore a previously deleted picklist item

Parameters:	picklist_item_id (int) – The IR-Flow assigned ID of the picklist item to be restored
Returns:	The full json response object from the IR-Flow API
Return type:	dict

update_incident(incident_num, incident_fields, incident_type_name, owner_id, group_ids, incident_subtype_name=None, description=None, priority_id=None)[source]

Update the incident of the provided number, type, and subtype with the provided: fields and description

Parameters:	incident_num (int) – The IR-Flow assigned ID of the incident to update incident_fields (dict) – Key, Value pairs of fields configured in IR-Flow and their values incident_type_name (str) – The string name of the incident type of the desired incident owner_id (int) – The id of the user that will own this incident group_ids (list of int) – The ids of the groups this incident will belong to. incident_subtype_name (str) – The string name of the incident subtype of the desired incident (optional) description (str) – An optional string description for the incident
Returns:	The full json response object from the IR-Flow API
Return type:	dict

upload_attachment_to_alert(alert_num, filename)[source]

Upload an attachment to the specified alert

Parameters:	alert_num (int) – The IR-Flow Assigned Alert number of the Alert to which the desired filed should be uploaded filename (str) – The path to the file to be uploaded
Returns:	The full json response object returned by the IR-Flow API
Return type:	dict

upload_attachment_to_incident(incident_id, filename)[source]

Upload an attachment to the specified incident

Parameters:	incident_id (int) – The ID of the Incident to which the desired file should be uploaded filename (str) – The path to the file to be uploaded
Returns:	The full json response object returned by the IR-Flow API
Return type:	dict

upload_attachment_to_task(task_id, filename)[source]

Upload an attachment to the specified task

Parameters:	task_id (int) – The ID of the task to which the desired file should be uploaded filename (str) – The path to the file to be uploaded
Returns:	The full json response object returned by the IR-Flow API
Return type:	dict

IR-Flow Client¶

Indices and tables¶