Space banner This version of the product is in limited support. However, the documentation is available for your convenience. You will not be able to leave comments.

v4.0 Events API


TrueSight Network Automation REST API – EventService
The base URL for the API is:

https://serverName:portNumber/bca-networks/api

events

{{status subtle="false" colour="Green" title="POST"/}}

 /v4.0/events
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

body

body

Complete attributes of the new system event


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

201

Created: New system event successfully logged


400

Bad request: Input DTO is missing or new system event is invalid


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Blue" title="GET"/}}

 /v4.0/events/device/{nameOrKey
}
Click here to expand...


Description

Retrieves the events that have occurred since the specified device was found to have a discrepancy, where the device appears as the target of the event; no events are returned if the device has no discrepancies

Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the device for which events areto be retrieved


string *

orderBy

query

Sort by the specified attribute (category, description, severity, source, target, threadId, timestamp, or type) in the specified order (prefix with a '+' for ascending or a '-' for descending)

"+timestamp"

string 
Enum: [
 "+category",
 "-category",
 "+description",
 "-description",
 "+severity",
 "-severity",
 "+source",
 "-source",
 "+target",
 "-target",
 "+threadId",
 "-threadId",
 "+timestamp",
 "-timestamp",
 "+type",
 "-type"
]

offset

query

Return the specified page number

1

integer

limit

query

Define the number of rows in a page or the maximum number of events to return

25

integer

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

[ 
  EventDTO
]

401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to access events


404

Not found: No single matching accessible device found


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Green" title="POST"/}}

 /v4.0/events/device/{nameOrKey}/emailed_file
Click here to expand...


Description

Exports and then emails events that have occurred since the specified device was found to have a discrepancy, where the device appears as the target of the event

Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the device for which events areto be emailed


string *

body

body

Parameters for emailing the events; any filter included here is ignored


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

OK: Exported events file successfully emailed


400

Bad request: Input email parameters are missing or invalid


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to access events


404

Not found: No single matching accessible device found


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Green" title="POST"/}}

 /v4.0/events/device/{nameOrKey}/exported_file
Click here to expand...


Description

Exports events that have occurred since the specified device was found to have a discrepancy, where the device appears as the target of the event

Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the device for which events areto be exported


string *

body

body

Parameters for exporting the events; any filter included here is ignored


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

400

Bad request: Input export parameters are missing or invalid


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to access events


404

Not found: No single matching accessible device found


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Green" title="POST"/}}

 /v4.0/events/emailed_file
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

body

body

Parameters for emailing the events


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

OK: Exported events file successfully emailed


400

Bad request: Input email parameters are missing or invalid


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to access events


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Green" title="POST"/}}

 /v4.0/events/exported_file
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

body

body

Parameters for exporting the events


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

400

Bad request: Input export parameters are missing or invalid


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to access events


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Green" title="POST"/}}

 /v4.0/events/filtered
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

body

body

Filter for events matching the various criteria specified in the EventFilterDTO; when null, no filtering occurs


view

query

Filter for events per the named private or shared view; any input orderBy parameter overrides the ordering settings in the view; any input EventFilterDTO overrides the filter in the view


string

orderBy

query

Sort by the specified attribute (category, description, severity, source, target, threadId, timestamp, or type) in the specified order (prefix with a '+' for ascending or a '-' for descending)


string 
Enum: [
 "+category",
 "-category",
 "+description",
 "-description",
 "+severity",
 "-severity",
 "+source",
 "-source",
 "+target",
 "-target",
 "+threadId",
 "-threadId",
 "+timestamp",
 "-timestamp",
 "+type",
 "-type"
]

offset

query

Return the specified page number

1

integer

limit

query

Define the number of rows in a page or the maximum number of events to return

25

integer

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

[ 
  EventDTO
]

400

Bad Request:Input event filter contains invalid selections


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to access events


404

Not found: No matching view found


500

Internal server error: Unexpected exception occurred



Object Definitions

Object

Schema

ComponentId


Click here to expand...


{ 
    id: string 
    The database key of the component; an incoming component can be identified either by its database key, or by its unique name, or by its name with qualifiers which are unique when combined; when this database key is present, it takes precedence and componentName and qualifiers(when present) are used to verify the retrieved component 

     componentName: string 
    The name of the component; an incoming component can be identified either by its database key, or by its unique name, or by its name with qualifiers which are unique when combined; this name is used to verify any component retrieved by database key, and is used if there is no database key or if the database key fails to resolve; for componentType Configuration and HardwareInventory, componentName is the created timestamp (in milliseconds); for componentType SecurityVulnerability, componentName is the securityVulnerabilityID; for componentType SnmpManagerStation, componentName is the address 

     componentType: string * 
    The type of the component, used to verify what is retrieved by key/name; valid values are: Combogroup, Condition, Configuration, Device, DeviceAdapter, DeviceAgent, DeviceSecurityProfile DynamicField, EmailDistributionList, Group, HardwareInventory, JobApprovalType, Keyword, Model, OsImage, PredefinedJob, Realm, RemoteFileServer, Role, Rule, RuleSet, SecurityVulnerability, SnmpManagerStation, Template, and User 

     qualifiers: { 
      Any additional single qualifier needed to identify the component uniquely, when the name alone is not sufficient; the map key is the extra attribute name string; the map value string completes the identification of the component; for componentType Configuration and HardwareInventory: key=deviceKey, value=database key of the device the item belongs to, key=deviceName, value=name of the device the item belongs to, key=timestamp, value=creation date/time in server display format; for componentType DeviceAdapter: key=adapterType, value=type of the device adapter, key=parent, value=parent or owner used for organizing certain types of adapters, key=vendorName, value=name of the vendor that owns a device type; for componentType DynamicField: key=type, value=base class name of the component associated with the dynamic field; for componentType Group, ComboGroup: key=realmName, value=name of the realm the group belongs to; for componentType Model: key=vendorGuid, value=the vendor GUID; for componentType OsImage: key=filename, value=name of the file(s) making up the image; for componentType SecurityVulnerability: key=vendorGuid, value=the vendor GUID 
    } 
}

DeviceResultFilterDTO


Click here to expand...


{ 
    actionNumber: integer 
    Include the results from this one action within the job; action numbers start with 1 

     errorMessageMatch: string 
    Include the results that failed with this error message, asterisk wildcards allowed 

     statusId: integer 
    Include the results with this numeric completion status 

     subactionNumber: integer 
    Include the results from this one sub-action within the action specified by the actionNumber field; sub-action numbers start with 1; this is ignored if you fail to specify an actionNumber 
}

EmailParametersDTO


Click here to expand...

Subclasses:
JobEmailParametersDTO
EventEmailParametersDTO

{ 
    formatId: integer * 
    The format of the exported file (CSV, HTML, PDF, or RTF) 

     hideHeaderAndFooterFlag: boolean 
    When the format is CSV, whether or not to hide the header and footer; when false, the header/title and footer/selections are included in the CSV file; when true, parts of the header and footer are excluded from the CSV file, making the file more easily imported into a spreadsheet; ignored when the format is not CSV 

     hideSensitiveDataFlag: boolean 
    For those exports that carry configuration data, whether or not the exported file masks sensitive configuration data, when false, the exported file contains the same data as the viewed data (which may already have masked its sensitive data, if you are not granted the "Access Sensitive Data" system right); when true, the exported file masks sensitive configuration data 

     includeAllDetailsFlag: boolean 
    Whether or not the exported file contains all the details associated with the main report or owned by the selected job; when false, the exported file contains only the selected report or job; when true, the exported file contains the selected report and its details subreports, or the selected job and its device transcripts; for reports, the number of details subreports is limited by the system parameter "Maximum Number of Details in Exported Reports"; ignored when the selected report supports no details (such as system diagnostics, device inventory, and OS image History reports) 

     orderBy: string 
    Sort details by the specified attribute in the specified order (prefix with a '+' for ascending order or a '-' for descending order); each type of export supports different attributes that can be sorted; not applicable to exports that lack sortable rows (such as configurations, transcripts, system diagnostics report, and all details-type reports); ignored when not applicable 

     subject: string 
    The subject of the email message carrying the exported content 

     toAdhocAddresses: [ 
      Any ad-hoc email addresses of the other interested recipients of the exported content 

       string 
    ] 

     toEmailListIds: [ 
      Any email distribution lists to receive the exported content 

       ComponentId
    ] 

     toUserIds: [ 
      Any users to receive the exported content 

       ComponentId
    ] 
}

EventDTO


Click here to expand...


{ 
    categoryId: integer 
    The event category 

     categoryName: string 
    The meaning of the numeric categoryId 

     currentThreadId: integer 
    Session number in which the event was logged 

     description: string 
    Description of the event 

     descriptionExtension: string 
    More details about the event, used by the system to help link events to their source 

     realmName: string 
    Realm that the target belongs to, when the target is a network span 

     rootThreadId: integer 
    Root session number in which the event was logged 

     severityId: integer 
    The event severity 

     severityName: string 
    The meaning of the numeric severityId 

     sourceName: string 
    The source of the event, or what caused the event 

     targetId: string 
    The database key of the target 

     targetName: string 
    The target of the event, or what was acted on 

     timestamp: date-time 
    Date and time the event was created 
    Example: 2018-01-31T13:45:00.000+0000

     typeId: integer 
    The event type 

     typeName: string 
    The meaning of the numeric typeId 
}

EventEmailParametersDTO


Click here to expand...

Discriminator: "@class" : "com.bmc.bcan.rest.services.v4_0.EventService$EventEmailParametersDTO"

{ 
    formatId: integer * 
    The format of the exported file (CSV, HTML, PDF, or RTF) 

     hideHeaderAndFooterFlag: boolean 
    When the format is CSV, whether or not to hide the header and footer; when false, the header/title and footer/selections are included in the CSV file; when true, parts of the header and footer are excluded from the CSV file, making the file more easily imported into a spreadsheet; ignored when the format is not CSV 

     hideSensitiveDataFlag: boolean 
    For those exports that carry configuration data, whether or not the exported file masks sensitive configuration data, when false, the exported file contains the same data as the viewed data (which may already have masked its sensitive data, if you are not granted the "Access Sensitive Data" system right); when true, the exported file masks sensitive configuration data 

     includeAllDetailsFlag: boolean 
    Whether or not the exported file contains all the details associated with the main report or owned by the selected job; when false, the exported file contains only the selected report or job; when true, the exported file contains the selected report and its details subreports, or the selected job and its device transcripts; for reports, the number of details subreports is limited by the system parameter "Maximum Number of Details in Exported Reports"; ignored when the selected report supports no details (such as system diagnostics, device inventory, and OS image History reports) 

     orderBy: string 
    Sort details by the specified attribute in the specified order (prefix with a '+' for ascending order or a '-' for descending order); each type of export supports different attributes that can be sorted; not applicable to exports that lack sortable rows (such as configurations, transcripts, system diagnostics report, and all details-type reports); ignored when not applicable 

     subject: string 
    The subject of the email message carrying the exported content 

     toAdhocAddresses: [ 
      Any ad-hoc email addresses of the other interested recipients of the exported content 

       string 
    ] 

     toEmailListIds: [ 
      Any email distribution lists to receive the exported content 

       ComponentId
    ] 

     toUserIds: [ 
      Any users to receive the exported content 

       ComponentId
    ] 

     filter: EventFilterDTO
    Filter for events matching the various criteria specified in the EventFilterDTO; when null, no filtering occurs 

     viewNameForTitle: string * 
    The name of the view being exported, used only for display in the exported file's header 
}

EventExportParametersDTO


Click here to expand...

Discriminator: "@class" : "com.bmc.bcan.rest.services.v4_0.EventService$EventExportParametersDTO"

{ 
    formatId: integer * 
    The format of the exported file (CSV, HTML, PDF, or RTF) 

     hideHeaderAndFooterFlag: boolean 
    When the format is CSV, whether or not to hide the header and footer; when false, the header/title and footer/selections are included in the CSV file; when true, parts of the header and footer are excluded from the CSV file, making the file more easily imported into a spreadsheet; ignored when the format is not CSV 

     hideSensitiveDataFlag: boolean 
    For those exports that carry configuration data, whether or not the exported file masks sensitive configuration data, when false, the exported file contains the same data as the viewed data (which may already have masked its sensitive data, if you are not granted the "Access Sensitive Data" system right); when true, the exported file masks sensitive configuration data 

     includeAllDetailsFlag: boolean 
    Whether or not the exported file contains all the details associated with the main report or owned by the selected job; when false, the exported file contains only the selected report or job; when true, the exported file contains the selected report and its details subreports, or the selected job and its device transcripts; for reports, the number of details subreports is limited by the system parameter "Maximum Number of Details in Exported Reports"; ignored when the selected report supports no details (such as system diagnostics, device inventory, and OS image History reports) 

     orderBy: string 
    Sort details by the specified attribute in the specified order (prefix with a '+' for ascending order or a '-' for descending order); each type of export supports different attributes that can be sorted; not applicable to exports that lack sortable rows (such as configurations, transcripts, system diagnostics report, and all details-type reports); ignored when not applicable 

     filter: EventFilterDTO
    Filter for events matching the various criteria specified in the EventFilterDTO; when null, no filtering occurs 

     viewNameForTitle: string * 
    The name of the view being exported, used only for display in the exported file's header 
}

EventFilterDTO


Click here to expand...


{ 
    categoryId: integer 
    Search for events in this category; a null or a zero value means do not filter on this field 

     descriptionMatch: string 
    Search for events whose description matches this wildcard-enabled string; a null means do not filter on this field 

     groupId: string 
    Search for events related to the group or the combo group specified by this database key; this field can be used only in transient filters (not in any views), as it is an input-only field and is not persisted to the database 

     maxEvents: integer 
    The maximum number of events returned by a database query that uses this filter, from which a selected page is extracted; setting a value improves performance when there are many events in the database; a value of zero or less means an unlimited number of events are returned 

     realmNameMatch: string 
    Search for events whose realm matches this wildcard-enabled string; a null means do not filter on this field 

     rootThreadId: integer 
    Search for events that were logged in this parent or root database session; a null or a zero value means do not filter on this field 

     severityIds: [ 
      Search for events of this severity; a null or an empty list means do not filter on this field 

       integer 
    ] 

     sourceNameMatch: string 
    Search for events whose source matches this wildcard-enabled string; a null means do not filter on this field 

     targetNameMatch: string 
    Search for events whose target matches this wildcard-enabled string; a null means do not filter on this field 

     timestamp: TimePeriodDTO
    Search for events that occurred within this time period; a null means do not filter on this field 

     typeId: integer 
    Search for events of this type; a null or a zero value means do not filter on this field 
}

ExportParametersDTO


Click here to expand...

Subclasses:
EmailParametersDTO
JobExportParametersDTO
EventExportParametersDTO

{ 
    formatId: integer * 
    The format of the exported file (CSV, HTML, PDF, or RTF) 

     hideHeaderAndFooterFlag: boolean 
    When the format is CSV, whether or not to hide the header and footer; when false, the header/title and footer/selections are included in the CSV file; when true, parts of the header and footer are excluded from the CSV file, making the file more easily imported into a spreadsheet; ignored when the format is not CSV 

     hideSensitiveDataFlag: boolean 
    For those exports that carry configuration data, whether or not the exported file masks sensitive configuration data, when false, the exported file contains the same data as the viewed data (which may already have masked its sensitive data, if you are not granted the "Access Sensitive Data" system right); when true, the exported file masks sensitive configuration data 

     includeAllDetailsFlag: boolean 
    Whether or not the exported file contains all the details associated with the main report or owned by the selected job; when false, the exported file contains only the selected report or job; when true, the exported file contains the selected report and its details subreports, or the selected job and its device transcripts; for reports, the number of details subreports is limited by the system parameter "Maximum Number of Details in Exported Reports"; ignored when the selected report supports no details (such as system diagnostics, device inventory, and OS image History reports) 

     orderBy: string 
    Sort details by the specified attribute in the specified order (prefix with a '+' for ascending order or a '-' for descending order); each type of export supports different attributes that can be sorted; not applicable to exports that lack sortable rows (such as configurations, transcripts, system diagnostics report, and all details-type reports); ignored when not applicable 
}

JobEmailParametersDTO


Click here to expand...

Discriminator: "@class" : "com.bmc.bcan.rest.services.v4_0.JobService$JobEmailParametersDTO"

{ 
    formatId: integer * 
    The format of the exported file (CSV, HTML, PDF, or RTF) 

     hideHeaderAndFooterFlag: boolean 
    When the format is CSV, whether or not to hide the header and footer; when false, the header/title and footer/selections are included in the CSV file; when true, parts of the header and footer are excluded from the CSV file, making the file more easily imported into a spreadsheet; ignored when the format is not CSV 

     hideSensitiveDataFlag: boolean 
    For those exports that carry configuration data, whether or not the exported file masks sensitive configuration data, when false, the exported file contains the same data as the viewed data (which may already have masked its sensitive data, if you are not granted the "Access Sensitive Data" system right); when true, the exported file masks sensitive configuration data 

     includeAllDetailsFlag: boolean 
    Whether or not the exported file contains all the details associated with the main report or owned by the selected job; when false, the exported file contains only the selected report or job; when true, the exported file contains the selected report and its details subreports, or the selected job and its device transcripts; for reports, the number of details subreports is limited by the system parameter "Maximum Number of Details in Exported Reports"; ignored when the selected report supports no details (such as system diagnostics, device inventory, and OS image History reports) 

     orderBy: string 
    Sort details by the specified attribute in the specified order (prefix with a '+' for ascending order or a '-' for descending order); each type of export supports different attributes that can be sorted; not applicable to exports that lack sortable rows (such as configurations, transcripts, system diagnostics report, and all details-type reports); ignored when not applicable 

     subject: string 
    The subject of the email message carrying the exported content 

     toAdhocAddresses: [ 
      Any ad-hoc email addresses of the other interested recipients of the exported content 

       string 
    ] 

     toEmailListIds: [ 
      Any email distribution lists to receive the exported content 

       ComponentId
    ] 

     toUserIds: [ 
      Any users to receive the exported content 

       ComponentId
    ] 

     filter: DeviceResultFilterDTO
    Which device results are included in the emailed file 
}

JobExportParametersDTO


Click here to expand...

Discriminator: "@class" : "com.bmc.bcan.rest.services.v4_0.JobService$JobExportParametersDTO"

{ 
    formatId: integer * 
    The format of the exported file (CSV, HTML, PDF, or RTF) 

     hideHeaderAndFooterFlag: boolean 
    When the format is CSV, whether or not to hide the header and footer; when false, the header/title and footer/selections are included in the CSV file; when true, parts of the header and footer are excluded from the CSV file, making the file more easily imported into a spreadsheet; ignored when the format is not CSV 

     hideSensitiveDataFlag: boolean 
    For those exports that carry configuration data, whether or not the exported file masks sensitive configuration data, when false, the exported file contains the same data as the viewed data (which may already have masked its sensitive data, if you are not granted the "Access Sensitive Data" system right); when true, the exported file masks sensitive configuration data 

     includeAllDetailsFlag: boolean 
    Whether or not the exported file contains all the details associated with the main report or owned by the selected job; when false, the exported file contains only the selected report or job; when true, the exported file contains the selected report and its details subreports, or the selected job and its device transcripts; for reports, the number of details subreports is limited by the system parameter "Maximum Number of Details in Exported Reports"; ignored when the selected report supports no details (such as system diagnostics, device inventory, and OS image History reports) 

     orderBy: string 
    Sort details by the specified attribute in the specified order (prefix with a '+' for ascending order or a '-' for descending order); each type of export supports different attributes that can be sorted; not applicable to exports that lack sortable rows (such as configurations, transcripts, system diagnostics report, and all details-type reports); ignored when not applicable 

     filter: DeviceResultFilterDTO
    Which device results are included in the exported file 
}

NewSystemEventDTO


Click here to expand...


{ 
    description: string * 
    Description or explanation of the event; will be truncated at 255 characters 

     eventSeverityId: integer * 
    The event severity, or how important this event is 

     targetId: string 
    The database key of the target 

     targetName: string 
    The target of the event, or what was acted on; will be truncated at 255 characters 
}

TimePeriodDTO


Click here to expand...


{ 
    timePeriodTypeId: integer * 
    What sort of time period this is 

     timePeriodTypeName: string 
    The meaning of the numeric timePeriodTypeId (read-only) 

     startTimestamp: date-time 
    The start date/time. Required only for certain user-defined time period types of After and Range; when the timestamp is missing the timezone, the server local timezone is assumed 
    Example: 2017-01-31T13:45:00.000+0000

     endTimestamp: date-time 
    The end date/time. Required only for certain user-defined time period types of Before and Range; when the timestamp is missing the timezone, the server local timezone is assumed 
    Example: 2017-01-31T13:45:00.000+0000
}

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*