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