User Guide

From FireScope Documentation Site
Jump to: navigation, search

Contents

User Guide

This section is a deep dive into every aspect of FireScope configuration, from populating Configuration Items (CIs), to Data Collection, to Event Analysis, to Visualization and Notifications. 

Credentials

Credentials are used to discover additional information within your environment. Credentials also allow a Configuration Item to gather information from your environment without loading or enabling additional agents and services. Depending on your environment, valid Credentials may be required. Use the Credentials Management page to add and update Credentials.

In order for FireScope to connect to or collect data from your infrastructure, an SNMP community string or username and password may be required.  This includes APIs such as VMware, NetApp, Cisco UCS, Amazon AWS and others. These credentials are also used by Discovery to collect details regarding a discovered asset, such as configuration information and potential Attributes for monitoring. To simplify configuration, all credential configuration is centralized in the Credentials section of the Configuration menu.  From here you can create or edit any Credentials that FireScope SPM may need.

Note:  Credentials are Edge Device specific. This allows you to designate shared Credentials (such as SNMP) per environment with a dedicated Edge Device.

LDAP Credentials

FireScope SPM has the ability to perform queries against LDAP servers such as Microsoft Active Directory, for e.g. identifying user privilege escalation, changes in Group Policy and more.  In order to perform these queries, proper authentication information will need to be provided by adding an LDAP Credential. LDAP credentials allow you to add LDAP connections which can be associated with a CI to collect data.

To create an LDAP Credential,# Click on Configuration > Discovery > Credentials Managements. Credential Management page will be displayed. Credentials Management.png-798x252.png

  1. Click on View next to LDAP credentials. LDAP Credentials Management page will be displayed.

7065.LDAP.png-800x160.png

  1. Click on Create button in the upper right hand corner. Create LDAP Credentials Management form will be displayed.

8270.LDAP Create.png-800x560.png

  1. Name: Enter a name which will be used to identify these credentials.
  2. Description: Enter helpful description that will help to understand these credentials.
  3. URL: Enter a path to an LDAP server. For e.g. Enter the path as LDAP://<server dns or IP>.Note: Do not put a trailing / at the end of the path.
  4. Port: Enter a port LDAP server will respond to. Mostly it is port 389
  5. Bind DN: Enter the container name of the account to be used. For e.g Bind DN: CN=Test
  6. Bind Password: Enter the password for the account.
  7. Base DN: Enter the entire container path for the account. For e.g. CN=Users,DC=firescope,DC=comIn the following example, the account to be used is “Test” and the full LDAP path to this account is CN=Test,CN=User,DC=firescope,DC=com.
  8. Click Save to complete the setup of the LDAP credentials.
     Note:
    • Once a LDAP credential have been defined, a CI can be associated to a single LDAP credential, via the CI Form.
    • Now that you have working LDAP credentials attached to the CI, you can create the LDAP check attributes. Only attributes of CI’s associated to an LDAP credentials will be able to collect LDAP data.
    • Attributes will need to be created with a type of LDAP check. Attributes of CI’s associated to an LDAP connection will be able to collect LDAP data.Data can be viewed by clicking on data history icon

SNMP Credentials

SNMP credentials are utilized by the following: * CI/Attributes - SNMP attributes within a CI will utilize the SNMP credential linked to the CI to establish connection and access

  • Network Discovery Jobs - Network discovery jobs will utilize SNMP credentials on a first-match basis. If you want to create and configure CIs with discovery profiles, order your SNMP credentials with the setting that can the most access first.Note: All credentials are associated to an Edge Device to better target multiple environments that may have different settings for community or authentication. Discovery job and CIs can only utilize credentials that have the same Edge Device.
  1. Click on Configuration > Discovery > Credentials. Manage Credentials page will be displayed.

2335.SNMP.png-798x230.png

  1. Click on View next to SNMP credentials, SNMP Credentials Management page will be displayed.

5224.SMIS Credentials.png-800x178.png

  1. Click on the Create button (upper right hand corner), SNMP Credentials Management create form will be displayed.

Create SNMP.png-794x263.png

  1. Edge Device: Select an Edge Device to designate the data collection or operation target.
  2. Name: Enter a descriptive name for this item.
  3. Description: Enter description
  4. Port: Enter port number
  5. SNMP Setting:
    • SNMP V1:
      • Requirement: Device must be SNMPv1 compatible or have an SNMP Agent installed. This includes most networked assets.
      • Information: The SNMPv1 SMI specifies the use of a number of SMI-specific data types, which are divided into two categories:
        • Simple data types
        • Application-wide data types
      • Access Requirement: Community for e.g. most devices have a setting for public

SNMP V1.png-428x157.png

    • SNMP V2: 
      • Requirement: Device must be SNMPv2 compatible or have an SNMP Agent installed.  
      • Information: The SNMPv2 SMI is described in RFC 2578. It makes certain additions and enhancements to the SNMPv1 SMI-specific data types, such as including bit strings, network addresses, and counters. Bit strings are defined only in SNMPv2 and comprise zero or more named bits that specify a value. Network addresses represent an address from a particular protocol family. SNMPv1 supports only 32-bit IP addresses, but SNMPv2 can support other types of addresses as well. Counters are non-negative integers that increase until they reach a maximum value and then return to zero. In SNMPv1, a 32-bit counter size is specified. In SNMPv2, 32-bit and 64-bit counters are defined.Additionally, SNMPv2 also specifies information modules, which specify a group of related definitions. Three types of SMI information modules exist: MIB modules, compliance statements, and capability statements.MIB modules contain definitions of interrelated managed objects.Compliance statements provide a systematic way to describe a group of managed objects that must be implemented for conformance to a standard.Capability statements are used to indicate the precise level of support that an agent claims with respect to a MIB group. An NMS can adjust its behavior toward agents according to the capabilities statements associated with each agent.
      • Access Requirement: Community for e.g. most devices have a setting for public
SNMP V2.png-476x182.png
    • SNMP V3:
      • Requirement: Device must be SNMPv3 compatible or have an SNMP Agent installed.
      • Information: Essentially offers the same information as SNMPv2, with the addition of 3 important security features:
        • Message integrity to ensure that a packet has not been tampered with in transit.
        • Authentication to verify that the message is from a valid source.
        • Encryption of packets to prevent snooping by an unauthorized source.
      • Access Requirement: SNMPv3 has several variations of access control. You will need to provide some of the following values based on the type of authentication required by the device's settings.
        • security name
        • security level
        • authentication type
        • auth passphrase
        • privacy type
        • priv passphrase

SNMP V3.png-540x220.png

  1. Click on the Save button.

User Management

Your FireScope appliance has two Admin User accounts, one for the FireScope SPM interface and one for the Configuration Management Interface (CMI). The Admin User is a reserved and restricted FireScope Administrator that has accessibility of all privileges granted to User Groups but cannot be a member of any groups. This user should perform administration and configuration tasks but not as an actual user.

These two Admin User accounts are separate for security purposes. The default password to both of these accounts is password.FireScope recommends that you change the passwords for both Admin accounts to two different passwords at your earliest convenience.             

User Access Level

FireScope SPM has several access levels to allow your users the necessary accessibility for their assigned tasks.

The access roles from least access to most access are as follows:* Dashboard User


Dashboard User

Dashboard users are restricted to the Dashboard Pages only. Lens content accessibility is restricted to associated Logical or Service Groups, based on User Group membership. Although the Users cannot create reports, they can access reports shared based on User Group membership (or public reports). They can create their own Dashboard Pages and Spaces. For Trend Graph or Pie/Bar charts, Dashboard users can also create their own graphs from accessible CI Attributes.

Services Supervisor

Services Supervisor have all the access of Dashboard users plus access to Service Management and Analysis sections of the application. Some Dashboard content will also provide additional contextual links to allow further analysis your issues or services. In addition to services and analysis views, supervisor users can create and manage their own reports. CI access is based on user group membership.

Services Manager

Services Manager user have access to Dashboard, Analysis, Service Management, and Service based Configuration (Service Groups, Policy, etc) but not device level Configuration (CI).

Configuration Administrator

Configuration Administrator have the ability to edit the configuration of your CIs, Visual Controls and other Data Collection or Data presentation settings. CI access is based on user group membership.

FireScope Administrator

FireScope Administrator have the ability  to edit settings that affects users, groups or properties that has impact on accessibility. Batch configuration functions such as Blueprint linkage and Migrate CIs requires this level of access. FireScope Administrators has access to all Service Groups, Logical Groups and CIs. They can also administer other users' Dashboards and Reports.

Account Administrator

Global Settings that affects all configurations and evaluations within the account requires this level of access. Limit this user access level to those you wish to conduct global setting configurations only. Account Administrators have access to all Service Groups, Logical Groups and CIs. This level of access can also administer other users' Dashboards and Reports.


    Dashboard only   Services Supervisor   Services Manager   Configuration Administrator   Firescope Administrator    Account Administrator
Dashboard      
View Dashboard √  √  √  √  √  √ 
Pages √  √  √  √  √  √ 
Spaces √  √  √  √  √  √ 
Service Management      
Business Services    Dashboard only   Services Supervisor   Services Manager Configuration Administrator     Firescope Administrator     Account Administrator
Service Policy Status ×
Service Explorer ×
Service Dependency Maps ×
Service Level Agreement ×
SLA Projection ×
Events   Dashboard only  Services Supervisor  Services Manager Configuration Administrator    Firescope Administrator    Account Administrator  
Recent Events × √   √ 
Recent Event Timeline × √  √ 
Policy Event Timeline × √  √ 
Notification × √  √ 
Incident Management × √  √ 
Storage Management    Dashboard only    Services Supervisor  Services Manager Configuration Administrator   Firescope Administrator     Account Administrator
Overview ×
Usage × √ 
Infrastructure ×
Virtual/Cloud    Dashboard only Services Supervisor    Services Manager Configuration Administrator   Firescope Administrator    Account Administrator  
Amazon AWS Infrastructure × √  √ 
VMWare Infrastracture ×
VMWare Explorer × √  √ 
Network    Dashboard only Services Supervisor   Services Manager Configuration Administrator    Firescope Administrator     Account Administrator
Explorer × √  √ 
Port Visualizer × √  √ 
Port Details × √  √ 
Infoblox Grid Management × √  √ 
Infoblox IPAM Explorer ×  √ 
User Experience Check    Dashboard only Services Supervisor   Services Manager  Configuration Administrator    Firescope Administrator    Account Administrator  
Web ×
User Experience Check × √ 
ServiceNow   Dashboard only  Services Supervisor   Services Manager  Configuration Administrator    Firescope Administrator     Account Administrator
ServiceNow Statistics ×
Analysis      
CI Analysis    Dashboard only  Services Supervisor   Services Manager  Configuration Administrator    Firescope Administrator    Account Administrator  
CI Quick View ×
Latest Data ×
CI Profile Overview ×
Visualization Analysis    Dashboard only  Services Supervisor   Services Manager Configuration Administrator    Firescope Administrator     Account Administrator
Data Center View ×
Virtual Controls ×
Historical Trend View ×
Graphic Data Analysis ×
Maps   Dashboard only Services Supervisor    Services Manager Configuration Administrator     Firescope Administrator     Account Administrator
Custom Maps ×
Google Maps ×
Data Center Google Map ×
Logs   Dashboard only  Services Supervisor   Services Manager  Configuration Administrator    Firescope Administrator     Account Administrator
SNMP Traps ×
Syslog ×
Window Log ×
Log Attribute ×
Reports   Dashboard only  Services Supervisor   Services Manager  Configuration Administrator    Firescope Administrator     Account Administrator
Quick Start Report ×
Manage Reports ×
Schedule Report ×
Firescope Analytics ×
Infrastructure    Dashboard only Services Supervisor   Services Manager  Configuration Administrator    Firescope Administrator    Account Administrator  
Cisco UCS Report ×
Flexpod for Vmware ×
Rack Infrastructure ×
Cloud Migration    Dashboard only Services Supervisor   Services Manager  Configuration Administrator    Firescope Administrator    Account Administrator  
Risk Analysis ×
Configuration      
CIs   Dashboard only  Services Supervisor  Services Manager  Configuration Administrator    Firescope Administrator     Account Administrator
CI × ×
Attribute × × ×
Attribute Set × × ×
User Experience Check × × ×
ESB × × ×
Group    Dashboard only Services Supervisor    Services Manager  Configuration Administrator    Firescope Administrator     Account Administrator
Logical Group × ×
Service Management × ×
Tag Management × × ×
Evaluation   Dashboard only  Services Supervisor   Services Manager Configuration Administrator     Firescope Administrator     Account Administrator
Event Definition × ×
AED × ×
Policies × ×
Notification × ×
Dependencies × ×
Maintenance Window × × ×
Service Level Agreement × ×
Service Dependency   Dashboard only Services Supervisor   Services Manager   Configuration Administrator    Firescope Administrator     Account Administrator
Dependency Editor × × × ×
Network Traffic × × × ×
Network URLs × × × ×
Network Destination × × × ×
Discovery    Dashboard only Services Supervisor    Services Manager  Configuration Administrator    Firescope Administrator     Account Administrator
Network Discovery × × × ×
Manage Clusters × × × ×
Topology Discovery × × × ×
Virtual Discovery × × × ×
Storage Discovery × × × ×
Amazon AWS Discovery × × × ×
Cisco UCS Discovery × × × ×
Infoblox Discovery × × × ×
SMI-S Discovery × × × ×
Credential Management × × × ×
Virtualization   Dashboard only  Services Supervisor   Services Manager  Configuration Administrator    Firescope Administrator    Account Administrator  
Visual Control × ×
CI MultiView × ×
Performance Grid × ×
Map & Infrastructure    Dashboard only  Services Supervisor   Services Manager Configuration Administrator    Firescope Administrator     Account Administrator
Custom Map × ×
Google Maps × ×
Icons and Images × ×
Facilities × ×
Racks × ×
FlexPod for Vmware × ×
Blueprint    Dashboard only Services Supervisor    Services Manager Configuration Administrator     Firescope Administrator     Account Administrator
Ci × × ×
Attribute × × ×
Attribute Set × × ×
Event Definition × × ×
Visual Control × × ×
Blueprint Group × × ×
Administration      
Permission   Dashboard only   Services Supervisor   Services Manager  Configuration Administrator    Firescope Administrator     Account Administrator
Users × × × ×
User Group × × × ×
AD User Configuration × × × × ×
External Authentication × × × × ×
Application Settings   Dashboard only  Services Supervisor   Services Manager  Configuration Administrator    Firescope Administrator     Account Administrator
Ci Type × × × × ×
Data Retention × × × × ×
Google Map Key × × × × ×
Locale × × × × ×
Service Rules Settings × × × × ×
Severity Colors × × × × ×
Syslog Facilities × × × × ×
Syslog Priorities × × × × ×
Theme Management × × × × ×
Value Translation × × × × ×
Utilities    Dashboard only  Services Supervisor   Services Manager  Configuration Administrator    Firescope Administrator     Account Administrator
Agent Management × × × × ×
Agent Upgrades × × × × ×
Edge Device × × × × ×
Blueprint Linkage × × × ×
Service Modeler × × × ×
Export × × × ×
Import × × × ×
Migrate CIs × × × ×
Integration   Dashboard only  Services Supervisor  Services Manager   Configuration Administrator    Firescope Administrator    Account Administrator  
Integration Information × × × ×
Service Now × × × ×
Cherwell × × × ×
Landesk × × × ×
System Reports   Dashboard only   Services Supervisor  Services Manager  Configuration Administrator    Firescope Administrator     Account Administrator
Audit Log × × × ×
Administrative Notification × × × ×
Edge Device Scorecard × × × ×
System Messages × × × ×
Config and Usage Statistics × × × ×

Create, Update and Delete SPM User

Create a SPM User:

  1. Log in to FireScope SPM as a FireScope Administrator.
  2. Click Administration > Permissions > Users. The Users page will be displayed with list of the current Users, their access level, user group(s) and online status.1220.Users.png-737x350.png
  3. Click on the Create button(on the upper, right side of the page). The Create User page will be displayed.

4152.Users Create.png-838x453.png

  1. Complete the form.
  2. Click on the Save button.                                                                 


 User Profile


Alias (Login Name) User name used to log into SPM.
Name User's first name.
Surname User's last name.
Password User's password to log in to SPM.

User Locale


Language  Preferred language used in the SPM user interface.
Time Zone & Date Format The settings here are used to interpret the time displayed for data history, events, and all time related displays.

Contact Media


Contact Media This is the contact SPM will use to contact the user in case of an event. You can configure multiple contact methods for a user, and for each contact method, you can detail hours of the day to use this method as well as filter the severity of events that trigger notifications.

 User Access Level


User Access Level Defines what this user can access in SPM.


User Access Level Available Menus
Account Administrator Highest level user access; access to all global Administration options
FireScope Administrator Has access to common administrative tasks,except for access to global account controls
Configuration Administrator Dashboard, Service Management, Analysis, Configuration
Services Supervisor Dashboard, Service Management, Analysis
Dashboard User Only Dashboard
User Groups User Groups this user will be associated with. The primary purpose of User Groups is to define what assets this user can manage. Select the User Group names and use the Add and Remove buttons to configure User Groups for this user.

Application Settings


Default location Default page displayed when this user logs in.
Auto-logout How many seconds of inactivity will trigger this user's session to be automatically logged out. To disable automatic logout, check the Never box.
Refresh Default polling period to refresh data in SPM interface items.You can override this value for Dashboard Lenses by adjusting their individual settings.
Related Events and Display Types Options - Event type (Shown in Non-Dashboard) You choose to only show failed, ok, or unknown events only. In some views, unknown events are counted as failed as well. You can override this value for Dashboard Lenses by adjusting their individual settings.
Global style setting for 'corrected' event display style Options "with strike-through"  OR "regular text"Sets how to display 'corrected' events. with strike-through Place a line through the event; this is useful for color blind users and emphasizes the failed events.

 

Update a SPM User:

Refer to Create User for Screen Shots#  Log in to FireScope SPM as a FireScope Administrator.

  1. Click Administration > Permissions > Users. The Users page will be displayed with list of the current Users, their access level, user group(s) and online status.
  2. Click on User's Alias (Login Name). Edit User page will be displayed.
  3. Add, delete or update the User information.
  4. Click on the Save button. 


Delete a SPM User:

Note: Deleting a User consists a some considerations.# If this User is Active Directory created, deleting this user will simply cause the user to be recreated in the next synchronization.

  1. Determine the reassignment of any objects that may belong to this user. For example, you may choose to reassign ownership and persist and pass control to another user.
  2. Below is the reassignment screen you will see after clicking delete on an individual User's Configuration form. (not from the grid)

6471.Delete User.png-904x308.png       

User Groups

User Groups are used to manage access for a group of Users. They are commonly used to represent a team within an organization that shares common responsibilities or tasks related to managing the IT assets.While User Group membership determines which assets are accessible to Users, User Access Level(link) determines the level of access rights (read-only, read-write) the user has to those assets.

 User Groups linked to a Service Group - will allow users access to all Logical Groups, CIs and related elements (Attributes, Event Definitions, Events, etc) under that Service Group & its Logical Groups.

 User Groups linked to a Logical Group - will allow users access to all CIs and related elements (Attributes, Event Definitions, Events, etc) under that Logical Group.

 User Groups linked to a Blueprint Group - will allow users access to view and edit Blueprint Groups and their associated Blueprint elements.

Creating and Managing a User Group

 Note: Although users can belong to more than one User Group, it is easier to manage permissions by NOT overlapping User and Group memberships with complex Service and Logical Group assignments.# Log in to FireScope SPM as a FireScope or Account Administrator.

  1. Click Administration > Permissions > User Groups. The User Groups page will be displayed with list of the current User Groups.

User Group.png-798x232.png

  1. Click on the Create button. Create User Groups page will be displayed.

7776.User Group Create.png-792x555.png

  1. Group Name: Create your user groups to organize asset access.
  2. Users: Select which groups this new user will be associated with for access to assets. User group assignment also determine visibility to group shared dashboard pages.
  3. Service Group/Logical Group
    • User groups linked to a Service Group - will allow users access to all Logical Groups, CIs and related elements (attributes, event definitions, events, etc) under that Service Group & its Logical Groups.
    • User groups linked to a Logical Group - will allow users access to all CIs and related elements (attributes, event definitions, events, etc) under that Logical Group.
  4. Blueprint Group:
    • User groups linked to a Blueprint Group - will allow users access to view and edit Blueprint Groups and their associated Blueprint elements.
  5. Click on the Save button.

External Authentication(SAML)

If you have SAML Identity Provider or Windows Active Directory deployed in your organization for user access management, you can utilize SPM External Authentication to use the same Credentials as the organization's login Credentials. 

To Select a Method of Authentication: # Login in to Firescope SPM as an Account Administrator.

  1. Click on Administrator > Permissions > External Authentication. External Authentication page will be displayed.

[File:EXternal Auth Local Page.png-748x225.png]]

  1. Select the Authentication Method from the drop down list. For more information on each method refer toAuthentication Methods section.
  2. Complete the form.
  3. Click on Enable and Save button.


Authentication Methods

  1. Local Authentication OnlyThis is the default Authentication method. It authenticates against local Users only. This method does not require any type of integration with other authentication sources or organizations within the company. 

Extrernal Auth Local Only New.png-801x244.png

  1. Active Directory Authentication
    This is a method that authenticates against local Users and Windows Active Directory. This method requires SPM cloud to have access to the Windows Active Directory to verify user credentials. It also requires configuration provided by Active Directory and Users should be already imported through AD User Configuration. The Active Directory may be provided by a different organization within your company.

AD Authentication.png-801x383.png

  1. SAML AuthenticationThis is a method that authenticates against local Users and SAML. SAML authentication is a method that authenticate Users against a remote service, know as a SAML Identity Provider (IdP), instead of authenticating against SPM which is considered to be the SAML Service Provider (SP). SAML Identity Provider may be provided by a different organization within the company.
    Successful SAML authentication requires following:
    • SPM cloud to have access to your SAML Identity Provider.
    • Configuration and exchange of SAML metadata between SPM and your SAML Identity Provider.
    • Changes to the customer's authentication server (idP ie PingID) and to the customer’s account in SPM (SP).


Select the SAML Authentication method from the drop down list on External Authentication page. SAML Authentication page will be displayed. This page has three sections which are explained below.# Remote Identity Provider(IdP) -  This information must be provided by your Remote Identity Provider. Coordinate SAML configuration with your Remote Identity Provider. For more information on the fields refer to the Section Description Table 1 below. 8204.SAML Auth IdP New.png-806x715.pngSection Description Table 1



Entity ID URL (Metadata) Identifier of the IdP entity
Single Sign On Service URL (SSO) URL Target of the IdP where the SP will send the Authentication Request Message
Log Out Service URL


Single Log Out Service URL (SLO) URL of the IdP where the SP will send the SLO Request
Log Out Redirect URL URL where the SP will perform a simple non-SAML redirect
X.509 Certificate IdP public certificate used in verifying signed SAML responses
  1. Local Service Provider(SP) - SAML configuration must be provided to your Remote Identity Provider and must match your Remote Identity Provider configuration. Coordinate SAML configuration with your Remote Identity Provider. This information is provided by SPM. For more information on the fields refer to the Section Description Table 2 below.

5811.SAML Auth SP New.png-514x488.pngSection Description Table 2



Entity ID URL (Metadata) Identifier of the SP entity
User Alias Mapping Enter the SAML attribute which maps to a SPM user Alias, such as NameId or User.sAMAccount
NameID Format Format of the name identifier to be used in SAM requests and responses
Single Log Out Service URL (SLS) URL where the IdP will issue a log out request to SPM
Assertion Consumer Services URL(ACS) URL where the response from the IdP will be returned
X.509 Certificate IdP public certificate used in verifying signed SAML responses

 

  1. Options - This section has additional SAML configuration which must match your Remote Identity Provider configuration.Coordinate SAML configuration with your Remote Identity Provider. For more information on the fields refer to the Section Description Table 3 below.4338.SAML Auth Options New.png-780x379.pngSection Description Table 3



 Sign Requests/Response


Authn Requests Signed SP Specified user authentication mechanism to request the IdP to use for user authentication
Logout Request Signed The logout Request messages sent by this SP will be signed
Logout Response Signed  The logout Response messages sent by this SP will be signed
Sign Metadata The Metadata provided by this SP will be signed
Messages Signed Require the Response, LogoutRequest and LogoutResponse received by this SP to be signed
Assertions Signed Require the Assertion elements received by this SP to signed
Authentication Context  SP specified user authentication mechanism to request the IdP to use for user authentication
Signature Algorithm Algorithm that will be used for signing

Configuring SAML with ADFS

The following guide explains the key settings required to setup SAML authentication using ADFS

 

Prerequisites:* ADFS 2.0 / 3.0

  • FireScope Edge must be able to connect via LDAP to a domain controller
  • FireScope Cloud must be able to connect to your ADFS server (Authentication is performed between FireScope web servers and ADFS)


  # First import the users that will be using FireScope using the AD Import feature at Administration menu à AD User Configuration.

  1. Create the Relying Trust Party in ADFS. We recommend having a browser window open, connected to FireScope and with the Administration à External Authentication page open, with SAML Authentication selected.
    1. Choose import data about the relying party published online. Use the url in the Entity ID URL (Metadata) field in the Local Service Provider section in the FireScope interface.
    2. Follow the wizard, be sure to select “Select Permit all users to access the relying party”
  2. Add a Rule in the Issuance Transform Rules tab. Add NameID as "Claim rule name", choose "Active Directory" as Attribute store, choose "SAM-Account-Name" as LDAP Attribute and "Name ID" (Space between Name and ID) as "Outgoing claim type."
  3. In the ADFS management console, click the Certificatesfolder and double-click on the Token Signing certificate, then Click the Details tab and the Button Copy To File. Export the certificate as Base-64 encoded X.509
  4. Open the exported file in a text editor and copy the content, paste into the X.509 Certificate field in the Remote Identity Provider section in the FireScope interface.
  5. Set the following fields to complete the FireScope side of the SAML integration:


 


Field Sample Value Notes
Entity ID URL http:// [your-adfs-server.domain.com].com/adfs/services/trust If you’re not sure what your Entity ID URL is, go to https://[your-adfs-domain.com]/FederationMetadata/2007-06/FederationMetadata.xml one of the first elements in this document is your Entity ID URL
Single Sign On Service URL (SSO) https://[your-adfs-server.domain.com] /adfs/ls/IdpInitiatedSignOn.aspx?LoginToRp=https://[yourFireScopeInstance].firescope.com  
Single Log Out Service URL (SLO) Optional  
Log Out Redirect URL Optional  
User Alias Mapping NameID  
ADFS - Lower case URL-Encoding Should be checked  
Authentication Context None  
Signature Algorithm SHA-256  

  

Finally, visit the home page of your instance of FireScope, fill in your account name and leave username and password blank.  Click on Enter and you should be re-directed to your ADFS server to complete authentication.

 

 

 

Common Errors

Invalid issuer in the Assertion/Response

Check that you have the correct Entity ID URL, and also verify that you are using the appropriate http or https at the beginning.

 

NameID was not in the Assertion Response

Check your claim rule and make sure you are sending SAM-Account-Name matched to Name ID.

 

User was not found

Check to make sure that you have imported users through the Administration menu à AD User Configuration page in FireScope. This should be in active status, and you can validate the correct users are created by checking the Users page.  AD imported users are noted with a “synced from AD” message immediately beneath the user’s name.

AD User Configuration

SPM allows the user to configure access to Windows AD from a deployed Edge device which provides users a more secure method to access user information to setup accounts in SPM cloud. The connection is assigned to a single Edge device which is already deployed within the user’s network and utilizes an already open connection between the Edge device and the SPM cloud to deliver the user data.

Note: Make sure the AD account user you enter here has visibility to the users you wish to import.# Log in to FireScope SPM as a Account Administrator.

  1. Click Administration > Permissions > AD User Configuration. The Users Configuration page will be displayed.

User Configuration.png-761x692.png

  1. Complete the form, for more information refer to the Section Description Table below.
  2. Click on Save button.


Note: If a user is matched on more than one filter, their user account will have the highest level of permissions.

Section Description Table


Section Description
Edge Device Select an Edge Device to designate the data collection or operation target.
Change Edge Device Click on the Change Edge Device button to select an Edge Device.Note: Changing the Edge device setting will require configuration update to move the access to your data from one Edge to another.
Windows AD Connection


AD Server Your internal AD server such as ad.company.com or 10.0.0.123
Port Default port is 389
Domain Your Domain, often the text following the @ in your email, such as company.com
Account User User used to find other users in AD. User must have permission to the provided Server, Domain, and User Group.Do not include your domain again i.e. text after (and including) the @ symbol
Password Enter New Password
Import Users


Status  You can select the status(Enabled or Disable)from the drop down list.
Mode You can create active directory query filter and user assignment rules to process users as they are imported into SPM.  The Preview Results Only mode lets you review the results without actually creating or updating Users.You can change the Mode to Import Users in Results once you have the expected results.
Frequency or Run Once You can schedule import configuration by entering frequency time in minutes. OrCheck the Run Once on Save check box to run it only once.
 Last check  Displays the date and time of last configuration..
AD User Group AD User Group: This is the actual location of the User.----The full baseDN path to the main user group. 'CN=Users,DC=companyname,DC=int'
Query Filter Query Filter: This is utilized to narrow the user list down to the ones you wish to import with this rule.---- “(sAMAccountName=*)(mail=*)(sn=*)(givenName=*)” portion of the query is required to retrieve  valid users.How-to guide on writing filters https://technet.microsoft.com/en-us/library/aa996205(v=exchg.65).aspxNote: Consult your security administrator and test the search filters with AD administrative tools before trying it in SPM.Note 2: Useful for getting membership of nested user groups is the bolded OID in the following example  (memberOf:1.2.840.113556.1.4.1941:=cn=Test,ou=East,dc=Domain,dc=com) 
User Access Level You can select the user access level for the imported or updated user from the drop down list. If the user is part of multiple rule results, the highest level will be granted.
 User Group You can select the user group of which the imported or updated user will become a member. Note: This is additive only. When a user does NOT match a user group assignment, the update import will NOT remove the user from any group or groups.
Last Scan Summary  Displays the record of updated and imported users. Click on the Results to see detailed view.Pastedimage1479141953622v1.png-320x240.png
Remove  You can delete the Rules by clicking on the X.

Configuration of Monitored Assets

Configuration Items (CI) are the assets (e.g. servers, routers, VMs, applications) on your network that FireScope SPM will be monitoring. Grouped into Logical Groups and Service Groups, CIs contain Attributes, which are the metrics or logs you want to track (e.g., Processor Utilization, Free Disk Space, log entries). Each CI can be connected with FireScope SPM using an optional agent or through SNMP, Syslog, or other communication methods. Highway map.png-973x228.png

Each monitored asset includes four key elements:# The Configuration Item - The CI acts as a container that identifies the IP Address or FQDN of the asset.

  1. Attributes - Attributes are the individual metrics, logs, and operational states of the CI.
  2. Event Definitions - Events can be configured to identify when a CI has an error or an Attribute's value is outside of operational thresholds.
  3. Visualization - Visualize current and trending conditions by building visual controls, which can be added to your custom Dashboards.
    • Adding a Performance Data Display
    • Adding a Pie or Bar Chart
    • Adding a Trend Graph

Please note that this section describes the manual process for creating an individual CI, and is rarely followed. In most cases, CIs are created automatically using Discovery, Integration or the configuration web service. Additionally, attributes, event definitions and visual controls are ideally applied via Blueprints in any scenario where you have more than one of a given class of CI.


Configuration Item

In the first step to monitoring a server, networked device or application, we need to create a Configuration Item (CI)–also called a Device. Although the steps below follow the manual process of CI creation, FireScope SPM does include a Discovery feature that can automate this process. For more information, see Discovery

Create CI

Following are the steps to create CIs manually. # Log in to FireScope SPM.

  1. Click Configuration > CIs > CI. The Configuration Items page will be displayed. 

CI Page1.png-735x285.png

  1. Click on the Create button (in the top right corner). The Create Configuration Item page will be displayed.

1134.CI Create.png-730x864.png

  1. Complete the form. Refer to the Section Description Table for information on each field.
  2. Click on the Save button.


Section Description


Section Description
Edge Device Edge Device is the main connection point that is required for SPM to collect data from this CI. This is server (or VM) that is connected to theSPM cloud application but is local to your CIs that are monitored. Select an Edge Device to designate the data collection or operation target.
Settings Basic information about the CI:Name - Enter a descriptive name for this item. A Configuration Item (CI) is any device, platform, or software that is required for the delivery of an IT service. When creating a CI for an application on a server, you may want to use the format: 'server name - application'. Status - Indicates if the CI is monitored or not. If you set this field to Not Monitored, FireScope SPM will not collect data for this CI.
Data Collection and Evaluation for this device There are two ways to quickly configure your CI to collect data and evaluate for events.1. Link with blueprints - Select blueprints to apply to this CI. Blueprints are already configured with attributes (data collection), event definitions (data evaluation) and visual controls (graphs). When you link a blueprint to a CI, that CI inherits all defined blueprint elements and can be managed via the linkage. This is a quick way to start collecting data with your configuration. 2. Scan CI on Create - Selecting this option will set the system to run discovery on the IP/DNS - and create configuration base on results (applies profiles). Note: CI Scanning utilizes the discovery profiles feature and requires proper agent installation or SNMP authentication for results.CI to collect  data and evaluate for events:Update CI InventoryApply Profiles and Update CI InventoryBlueprint linkage for CI Inventory: Blueprint linked to this CI will try to expand dynamic elements with appropriate macros.
Connection Settings This section defines how FireScope should connect to this Configuration Item; by IP Address or DNS Name. The port field is only required if you are using the FireScope Agent, which by default uses port 8042. Connect to - DNS name or IP address for this asset's network address. IP address is faster since it doesn't require a DNS lookup process.DNS name - Fully qualified DNS address of the asset. Only required if you selected DNS name in the Connect to field.IP address - IP address of the asset. Only required if you selected IP address in the Connect to field.Port - Port the agent is listening on. Only required if you are using the FireScope Agent, which uses port 8042 by default.
Credentials And Additional Connection Settings These settings are required for some specific types of data collection which may need additional connection associations.SNMPCredentials: SNMP access credentials which allows attributes to connect to the SNMP device .VMware Virtual Center Credential: VMware Virtual Center access credentials which allows attributes to connect to the VMware device and determine data relationships.Associate with Virtual Center : A CI associated with a Virtual Center connection has the ability to gather Host and Guest informationfrom your Virtual Environment (vCenter) without loading or enabling additional agents and services. This feature could also be used to gather capacity information across your virtual infrastructure.Virtual Center Infrastructure:Virtual Center Infrastructure Client Name - used as the unique lookup to locate the associated virtual center host or guest.NetApp ONTAP Credential: NetApp ONTAP access credentials allows attributes to connect to the NetApp device and determine data relationships NetApp DFM Credential: NetApp DFM access credentials which allows attributes to connect to the NetApp device and determine data relationshipsCisco UCS Credential: Cisco UCS credentials allows attributes to connect to the Cisco device and determine data relationships.Infoblox Connection: Requires an account login with proper access for API data retrieval. Please validate the accessibility of the IP and Port from SPM. Amazon AWS Connection: Requires an Access ID and Access Key with proper permissions for data retrieval. Please validate the accessibility of the Service from the Edge Device that will make the connection. Sentinel:              Domain            Proxy Configuration ItemsLDAP Credential: To allow the CI to use the LDAP credentials, you need to link them. This is done from the CI itself. Edit the CI and scroll down to the Credentials and additional settings. Select the LDAP tab then select the appropriate credentials from the drop down. Linking CI to LDAP credentials allows attribute of this CI to connect to LDAP service.LDAP Association.png-320x240.png

SMI-S Connection: Allows attributes to connect to the SMI-S device.See Connections to Device API for more information.

Inventory Inventory for a CI's assets in terms of Storage, CPU, Interface, and Memory. This information can be populated with the inventory feature enabled from a discovery job or you can populate the list manually. On certain asset types, Macros can be used in associated Blueprints to dynamically create Attributes and Event Definitions.  This list can be populated manually or generated by a Discovery job.
 Groups Logical Group: Grouping of CIs based on location, type of hardware, or another common factor between CIs. You can add or remove the association(s) between this CI and the listed Logical Groups. User groups linked to a Logical Group will allow users access to all CIs and related elements (attributes, event definitions, events, etc) under that Logical Group.Service Group :Grouping of CIs based on functionality or service provided by CIs. Add or remove the association(s) between this CI and the listed Service Groups. User groups linked to a Service Group will allow users access to all Logical Groups, CIs and related elements (attributes, event definitions, events, etc) under that Service Group & its Logical Groups.
Profile This section contains additional information about this Configuration Item that might be helpful for other users or for asset tracking. Asset type is the only required field in this section, all other fields are completely optional.
Tag Management Tags are additional identification applied to the main configuration elements: Service Groups, Logical Groups, Configuration Items, Attributes, Event Definitions, Aggregate Event Definitions, Policies, and Visual Controls.Tags are used for search, reports and some specialized displays in the application. System default tags are applied to most agent attributes and some common SNMP (OID) attributes upon creation. You can always create or apply additional tags to any element to further identify each asset. 

 

Clone CI

  1. Open an existing CI.
  2. Edit the form. See Creating a Configuration Item for more information on the CI fields.
  3. Click Clone (on the bottom of the page). The Create Configuration Item page will be displayed, duplicating the field values of the CI you choose.
  4. Click on the Save button.  


Edit CI

  1. Open an existing CI.
  2. Edit the form. For more information on the CI fields, see Creating a Configuration Item.
  3. Click on the Save button.


Activate or Disable CI

  1. Click on Configuration > CIs > CI. The Configuration Items page lists all the current CIs.Note: You can filter this display by Service Group or Logical Group using the global navigation. You can sort the information by clicking a column header.
  2. Check the box next to the CI you want to activate or disable.
  3. In the drop-down at the bottom right corner of the page, select Activate selected or Disable selected.
  4. Click Update. A confirmation window will be displayed. Note: Disabling a CI sets FireScope SPM to no longer collect data from that CI, but all previously collected data will still be accessible.
  5. Click OK


Delete CI

  1. Check the box next to the CI you want to delete.
  2. In the drop-down at the bottom right corner of the page, select Delete selected.
  3. Click Update. A confirmation window appears.Note: Deleting a CI will not delete any data but will mark this device and its historical data for deletion during the next Housekeeping cycle. For information on Housekeeping timing, please see History Settings and Cleaning History, in the Ongoing Administrative Tasks section.
  4. Click OK.


Association with Credentials

Credentials are used to discover additional information within your environment. Credentials also allow a Configuration Item to gather information from your environment without loading or enabling additional agents and services. Depending on your environment, valid credentials may be required. Use the Credentials Management page to add and update credentials.Credentials are Edge device specific. This allows you to designate shared credentials (such as SNMP) per environment with a dedicated Edge device.

Batch Update CI Properties

To Update CI properties:

  1. Log in to FireScope SPM with configuration or administration privileges.
  2. Click Configuration > CIS > CI. The Configuration Items page lists all the current CIs.Note: You can filter this display by Service Group or Logical Group using the global navigation. You can sort the information by clicking a column header.

CI Create Image 1.png-882x182.png

  1. Check the box next to the CI you want to update.
  2. From the drop-down at the bottom right corner of the page, Select Update CI Profiles from the following options:
    1. Activate
    2. Disable
    3. Delete
    4. Update CI Profiles
    5. Update Business Availability


Update CI Profiles

CI properties are populated by Discovery profiles but are not updated by BP linkage. To edit several CIs at the same time,

  1. Select the Check boxes next to the CIs you wish to update.
  2. Select Update CI Profiles action from drop down box (bottom right hand corner)

6562.CI Profile Update.png-678x221.png

  1. Click on the Update button. Batch update CI Profile form will be displayed.Note: Leaving a field blank will preserve the existing values per CI.

7024.Update CI Profile New.png-680x341.png

  1. The table below Selected CIs (at the end of the form) shows the existing values of the selected CIs prior to the batch update.


Update Business Availability

CI Business Availability are populated by Discovery profiles (typically defaults to a ping status) but are not updated by BP linkage. To edit several CIs at the same time,
  1. Select the Check boxes next to the CIs you wish to update.
  2. Select Update Business Availability action from drop down box (bottom right hand corner)

7411.CI Create Image 1.png-748x156.png

  1. Click on the Update button. Batch update CI Profile form will be displayed.

Update CI Bunissess Avail New.png-738x256.png

  1. Business Availability drop-down list displays Event Definitions of all selected CIs have in common, matching by description. Selecting an Event Definition and clicking Update Business Availability will assign each CI the corresponding ED as the new business availability.
  2. The table below Selected CIs (at the end of the form) shows the current business availability assignments and the current status.

Connections to Device API

Connections to Device API for Data Collection

Linking a CI to stored credentials will allow attributes within this CI to connect to the device and collect data. Depending on the type of attribute used (SNMP, LDAP, NetApp, etc), you must provide the right type of credential. For example, to use the VM attributes, such as "vm_guest_cpu_host_util" will require connectivity to the VMWare API to collect this metric. The CI must have the reference link to the VM connection credential.

All credentials can be managed from Configuration > Discovery > Credential Management page.

SNMP CredentialSNMP access credentials which allows attributes to connect to the SNMP enabled devices. User must provide community

LDAP ConnectionA LDAP access credentials allows attributes to connect to the LDAP service. User must provide login as well as binding information. Use with "ldap_check" attributes.

VMware Virtual Center CredentialA CI associated with a Virtual Center connection has the ability to gather Host and Guest information from your Virtual Environment (vCenter) without loading or enabling additional agents and services. This feature could also be used to gather capacity information across your virtual infrastructure. Virtual Center Infrastructure Client Name - used as the unique lookup to locate the associated virtual center host or guest. Use with VM Center, Host and Guest attributes.

NetApp ONTAP This access credentials allows attributes to connect directly to the NetApp device and determine data relationships. Use with NetApp Check attribute type. (Ex. "netapp_perf")

NetApp DFMThis access credentials allows attributes to connect to the DFM to collect data regarding a volume usage. Used with NetApp DFM Attribute type. (Ex "netapp_dfm_volume")

Cisco UCS CredentialCisco UCS access credentials which allows attributes to connect to the Cisco device API to collect performance data regarding it's components. Use with Cisco UCS attribute type. (Ex. "cisco_ucs_stat")

Infoblox ConnectionInfoblox Connection - Requires an account login with proper access for API data retrieval. Use with Infoblox Attribute type. (Ex. "infoblox_range")

Migrate CI's

Prerequisite

Before migrating any CIs, make sure that the FireScope agents running on the CIs are configured to point to the new Edge device IP address. This can be done by editing the Server property field in the agent configuration. For more information on how to include the new Edge device IP address, go to  Agent Configuration page.

Migrate CI's

There may be times, either because of growth in your infrastructure or for performance tuning reasons, where you may need to redistribute data collection for Configuration Items (CIs) across your Edge devices.  FireScope includes a mass-migration utility for these occasions.  It is important to note that CI GUIDs include the associated Edge device's GUID, and therefore moving a CI to a different Edge device requires re-creating the CI with a new GUID.  While this has no impact on integration, AEDs or Policies, it does mean that the history of the CI will have to be recreated, which is why the migration capability includes options for the length of history to retain.

  To migrate CIs# Click on Administration > Utilities > Migrate CIs, Migrate CIs page will be displayed. Migrate CIs Page.png-980x304.png

  1. Click on the Create button. Create Migration CI Job page will be displayed.
  2. Select Edge Device from Migrate from drop down menu.
  3. Select a type of item to migrate from Select Configuration Items To Migrate: drop down menu.

Migrate CIs Create.png-971x487.png

  1. Click on the Select button, a Select (item type) page will be displayed.

Migration Select CI.png-801x256.png

  1. Click on the check box next to the item to select it, then click on the Select button.
  2. You will be redirected to the Create Migration CI Job page.
  3. Enter Days of CI History Data to Migrate: or No history (0 days) option, on the Create Migration CI Job page.
  4. Click on the Next button.

Data History.png-790x205.png

  1. . Confirm Migration Job page will be displayed.

Confirm Migrate CIs Create Job.png-916x475.png

  1. Click on the check box to confirm the migration and then click on the Execute button.

Data Collection

In order to ensure you are receiving the richest set of system events and data possible, FireScope offers a variety of data collection types to choose from. You can select data collection methods on a host-by-host basis. For instance, data on network equipment can be collected through SNMP, while servers communicate through rich agents. Not all data collection methods offer the same range of data types, and each has its own set of limitations and prerequisites. The table below will guide you through the available collection methods to help you strategize the best deployment for your unique environment.


Method Requirements Additional Information
Agent Remote     A type of FireScope agent data access where agent sends data back to the Edge device periodically vs. utilizing the poller service from the Edge device.
Attribute Incoming          This is also referred to as a Dynamic Data Attribute
Attribute JSON  Incoming                    This is also referred to as a Dynamic Data Attribute 
Calculated Attribute   You can use this attribute to combine other attributes' values. Configuring a Calculated Attribute
Cisco UCS Requires CI to have a link to Cisco UCS Credential Collect metrics using Cisco UCS API
Derived Check   Internal metrics such as number of attributes or event definitions.
FireScope Agent Agent must be installed on device. Currently available for most operating systems, including Windows, Linux, Unix, BSD. This method offers the largest scope of information collection. It includes log data from any log file on the host machine as well as system performance data and direct database connectivity.See Installing an Agent.
Grouped Check   Calculated values within a logical group of CI's for a given an attribute's operationGrouped Check Attribute 
Infoblox Attributes Requires CI to have a link an Infoblox API credential Collect network information defined in Infoblox Manager (ex. network ranges, etc)
LDAP Check Requires CI to have a link to LDAP credential Collect metrics using LDAP queries
NetApp Check Requires CI to have a link to NetApp ONTAP credential Collect metrics directly from a NetApp Filer using ONTAP API
NetApp DFM Check Requires CI to have a link to NetApp DFM credential Collect filer volume metrics from a NetApp DFM
Percentile Attribute   Value of other attributes at specified percentile for a specific time window in days. (information on percentile calculations)
SNMP Trap   Collects messages forwarded to FireScope from SNMP devicesConfiguring an SNMP Trap Attribute
SNMP v1 Device must be SNMPv1 compatible or have an SNMP agent installed. This includes most networked assets. The SNMPv1 SMI specifies the use of a number of SMI-specific data types, which are divided into two categories:Simple data typesApplication-wide data types
SNMP v2 Device must be SNMPv2 compatible or have an SNMP agent installed. The SNMPv2 SMI is described in RFC 2578. It makes certain additions and enhancements to the SNMPv1 SMI-specific data types, such as including bit strings, network addresses, and counters. Bit strings are defined only in SNMPv2 and comprise zero or more named bits that specify a value. Network addresses represent an address from a particular protocol family. SNMPv1 supports only 32-bit IP addresses, but SNMPv2 can support other types of addresses as well. Counters are non-negative integers that increase until they reach a maximum value and then return to zero. In SNMPv1, a 32-bit counter size is specified. In SNMPv2, 32-bit and 64-bit counters are defined.Additionally, SNMPv2 also specifies information modules, which specify a group of related definitions. Three types of SMI information modules exist: MIB modules, compliance statements, and capability statements.MIB modules contain definitions of interrelated managed objects.Compliance statements provide a systematic way to describe a group of managed objects that must be implemented for conformance to a standard.Capability statements are used to indicate the precise level of support that an agent claims with respect to a MIB group. An NMS can adjust its behavior toward agents according to the capabilities statements associated with each agent.
SNMP v3 Device must be SNMPv3 compatible or have an SNMP agent installed. Essentially offers the same information as SNMPv2, with the addition of 3 important security features:Message integrity to ensure that a packet has not been tampered with in transit.Authentication to verify that the message is from a valid source.Encryption of packets to prevent snooping by an unauthorized source.
Syslog Message Device must have Syslog agent, which is common on most non-Microsoft operating systems. Limited to data stored in log files, which does not include most system performance metrics. However, on most platforms the administrator can define what information to log.
TCP Check   Collects information by connecting via IP and Port.
Simple Check No requirements. Performed directly through the FireScope SPM appliance. A simple check is ping testing to verify a host is reachable. Available/Unavailable and response times are the only types of information this method can collect.
VM Guest Requires CI to have a link to VM credential Collects metrics regarding VM Guests
VM Host Requires CI to have a link to VM credential Collects metrics regarding VM Hosts
VM Virtual Center Requires CI to have a link to VM credential Collects metrics regarding VM Virtual centers
Web Monitoring (User Experience Checks) No requirements. Performed directly through the FireScope SPM installation.  Web monitoring simulates a user experience on a web-based application and measures response and download times.See User Experience


Data Collection Settings

Data Retention

You can control how long historical data is stored in the SPM database. This affects how much storage space is required for saving the history. This will also affect how much storage space is required for creating backups.

Attribute Data Retention by Type* Numeric (float, 1.4, 235.2): (default: 7 Days)

  • Numeric (integer 64bit): (default: 7 Days)
  • Character: (default: 14 Days)
  • Text: (default: 14 Days)
  • Log: (default: 14 Days)
  • JSON: (default: 14 Days)
  • Trends older than: days (default: 90 Days)Trends are hourly and daily averages of numeric (float and integer) data stored separately from detailed data points. Each average entry also keeps track of maximum, minimum, average and number data points collected. This allows data to be stored for longer periods of time and still be usable for analysis.


Notifications and Events Retention* Notifications older than: days (default: 90 Days)

  • Events older than: days (default: 30 Days)
  • SLA older than: days (default: 90 Days)SLA trends are hourly and daily averages of availability percentage data calculated hourly and average daily. Each average entry also keeps track of number of Ok events, Failed events, Unkown events, up-time, down-time, business impact and any maintenance window results.


Log Retention by Type* Audit logs older than: days (default: 90 Days)

  • Reports older than: days (default: 30 Days)
  • ServiceNow CMDB auditlog older than: days (default: 30 Days)
  • SNMP trap: (default: 90 Days)
  • Syslogs older than: days (default: 90 Days)
  • System messages older than: days (default: 90 Days)
  • Windows event logs older than: days (default: 90 Days)

Value Translation

For UI displays of data, you can assign value translation to be associated with attributes. For example, 'Ping' values of 0 and 1 can be associated to display.

0  ⇒  Down 1  ⇒  Ok 

Value translation are helpful to provide readable formats corresponding numeric status or codes. Often status values are dependent on individual vendor APIs and protocols. For example, for VMWare API, the following are some mappings:


VM Guest State reset  ⇒  Reset suspended  ⇒  Suspended poweredOn  ⇒  Powered On poweredOff  ⇒  Powered Off
VM Host State connected  ⇒  Connected disconnected  ⇒  Disconnected notResponding  ⇒  Not Responding
VM Tools Information toolsNotInstalled  ⇒  Not Installed toolsNotRunning  ⇒  Not Running toolsOld  ⇒  Out of Date toolsOk  ⇒  Ok

These values can be populated either manually by users, imported with CI definition XMLs, or results from discovery jobs.

Applying Translation to Attributes

Whenconfiguring an attribute, change the 'Show value' setting under Attribute Display Options.

Attribute Show Value.png-320x240.png

Flexible Collection Schedule

Data collected by Attributes can be collected at flexible intervals.

To set the Flexible Collection Schedule:# Log in to FireScope SPM.

  1. Click Configuration > CIS > Attributes. The Attributes page displays the Attributes for the selected Configuration Item (in the top left corner).
  2. In Navigate or Search for a description, select the CI you want to create the Attribute for.
  3. Click Create (in the top right corner). The Create Attribute page will be displayed.   
  4. Click on the Flexible Intervals, Flexible Intervals section will be displayed. 

AttributeFlex Intervals.png-514x209.png

  1. Select Delay Period, Days of WeekStart TimeEnd Time or select Preset options    
  2. Click Add to set the Flexible Intervals.                                                                              
  3. Complete rest of the form.
  4. Click on the Save button.

Data Collection Methods

In order to ensure you are receiving the richest set of system events and data possible, FireScope offers a variety of data collection types to choose from. You can select data collection methods on a host-by-host basis. For instance, data on network equipment can be collected through SNMP, while servers communicate through rich agents. Not all data collection methods offer the same range of data types, and each has its own set of limitations and prerequisites. The table below will guide you through the available collection methods to help you strategize the best deployment for your unique environment.


Method Requirements Additional Information
Agent Remote   A type of FireScope agent data access where agent sends data back to the Edge device periodically vs. utilizing the poller service from the Edge device.
Attribute Incoming   This is also referred to as a Dynamic Data Attribute
Attribute JSON Incoming   This is also referred to as a Dynamic Data Attribute 
Calculated Attribute   You can use this attribute to combine other attributes' values. Configuring a Calculated Attribute
Cisco UCS Requires CI to have a link to Cisco UCS Credential Collect metrics using Cisco UCS API
Derived Check   Internal metrics such as number of attributes or event definitions.
FireScope Agent Agent must be installed on device. Currently available for most operating systems, including Windows, Linux, Unix, BSD. This method offers the largest scope of information collection. It includes log data from any log file on the host machine as well as system performance data and direct database connectivity.SeeInstalling an Agent.
Grouped Check   Calculated values within a logical group of CI's for a given an attribute's operationGrouped Check Attribute 
Infoblox Attributes Requires CI to have a link an Infoblox API credential Collect network information defined in Infoblox Manager (ex. network ranges, etc)
LDAP Check Requires CI to have a link to LDAP credential Collect metrics using LDAP queries
NetApp Check Requires CI to have a link to NetApp ONTAP credential Collect metrics directly from a NetApp Filer using ONTAP API
NetApp DFM Check Requires CI to have a link to NetApp DFM credential Collect filer volume metrics from a NetApp DFM
Percentile Attribute   Value of other attributes at specified percentile for a specific time window in days. (information on percentile calculations)
SNMP Trap   Collects messages forwarded to FireScope from SNMP devicesConfiguring an SNMP Trap Attribute
SNMP v1 Device must be SNMPv1 compatible or have an SNMP agent installed. This includes most networked assets. The SNMPv1 SMI specifies the use of a number of SMI-specific data types, which are divided into two categories:Simple data typesApplication-wide data types
SNMP v2 Device must be SNMPv2 compatible or have an SNMP agent installed. The SNMPv2 SMI is described in RFC 2578. It makes certain additions and enhancements to the SNMPv1 SMI-specific data types, such as including bit strings, network addresses, and counters. Bit strings are defined only in SNMPv2 and comprise zero or more named bits that specify a value. Network addresses represent an address from a particular protocol family. SNMPv1 supports only 32-bit IP addresses, but SNMPv2 can support other types of addresses as well. Counters are non-negative integers that increase until they reach a maximum value and then return to zero. In SNMPv1, a 32-bit counter size is specified. In SNMPv2, 32-bit and 64-bit counters are defined.Additionally, SNMPv2 also specifies information modules, which specify a group of related definitions. Three types of SMI information modules exist: MIB modules, compliance statements, and capability statements.MIB modules contain definitions of interrelated managed objects.Compliance statements provide a systematic way to describe a group of managed objects that must be implemented for conformance to a standard.Capability statements are used to indicate the precise level of support that an agent claims with respect to a MIB group. An NMS can adjust its behavior toward agents according to the capabilities statements associated with each agent.
SNMP v3 Device must be SNMPv3 compatible or have an SNMP agent installed. Essentially offers the same information as SNMPv2, with the addition of 3 important security features:Message integrity to ensure that a packet has not been tampered with in transit.Authentication to verify that the message is from a valid source.Encryption of packets to prevent snooping by an unauthorized source.
Syslog Message Device must have Syslog agent, which is common on most non-Microsoft operating systems. Limited to data stored in log files, which does not include most system performance metrics. However, on most platforms the administrator can define what information to log.
TCP Check   Collects information by connecting via IP and Port.
Simple Check No requirements. Performed directly through the FireScope SPM appliance. A simple check is ping testing to verify a host is reachable. Available/Unavailable and response times are the only types of information this method can collect.
VM Guest Requires CI to have a link to VM credential Collects metrics regarding VM Guests
VM Host Requires CI to have a link to VM credential Collects metrics regarding VM Hosts
VM Virtual Center Requires CI to have a link to VM credential Collects metrics regarding VM Virtual centers
Web Monitoring(User Experience Checks) No requirements. Performed directly through the FireScope SPM installation. Web monitoring simulates a user experience on a web-based application and measures response and download times.See User Experience Checks.

Attribute

.An Attribute is a specific metric or log you wish to collect data for–such as CPU load average or response time–and is associated with a Configuration Item (CI). An Attribute can refer to a metric obtained via any of FireScope SPM' data collection methods. Attributes can be configured as the following value types:


Value Type Description
0 Float Double e.g. 3.14
1 String Character (max size 1024) e.g. "Hello world"
2 Log Actual lines from a log attribute / Windows Event log attribute (Max size 65535)
3 Long Integer e.g. 2147483647
4 Text Very large "String" equivalent of a CLOB (Max size 65535)
9 JSON  (Max size 4096)e.g. {"first_name":"Bryan","company_name":"FireScope"}

 

The easiest way to add Attributes for a CI is to associate the CI with a Blueprint. Blueprints are pre-configured CIs of a specific type–such as Windows Server or Cisco 2600–and include a list of commonly used Attributes, Event Definitions, and Visual Controls. You can associate more than one Blueprint with a CI.

Create an Attribute:

  1. Log in to FireScope SPM.
  2. Click on Configuration > CIs > Attributes. The Attributes page displays the Attributes for the selected Configuration Item (in the top left corner).

Attribute.png-799x178.png

  1. In Navigate or Search for a description, select the CI you want to create the Attribute for.
  2. Click on the Create button  (in the top right corner). The Create Attribute page will be displayed.

1185.Attribute Create.png-800x1068.png

  1. Configuration Item : Attributes are associated with a specific CI. Select a Configuration Item that you want this attribute to be associated with.
  2. Description: Enter a descriptive name for this item.
  3. Status: This field indicates whether FireScope is actively collecting data for this attribute. Not Supported indicates that there is a problem with the data being collected.
  4. Data Collection Settings: This section defines how FireScope should gather values for this attribute, either through the FireScope Agent, SNMP or other means. If you are using FireScope agent please make sure the selected operation is defined in the FireScope Agent's configuration. For SNMP, you must enter the credentials required to access the SNMP connection (port 161) of the device. The Update interval tells FireScope how often to check values. The Value field allows you to either collect the raw value or its rate of change over time.
    1. Type: This determines how FireScope SPM should gather values for the Attribute. Depending on what you select, additional form fields may appear.  For information on each type click here.
    2. Operation: Select the operation for gathering data. For e.g. If you are using FireScope agent please make sure the selected operation is defined in the FireScope Agent's configuration. For SNMP, you must enter the credentials required to access the SNMP connection (port 161) of the device.
    3. Base Units: Select base unit type appended to the end of all values for this Attribute whenever they are displayed. For example, (%) Percent for processor utilization, (B) Bytes for file system size, and (Bps) Bytes Per Second for network performance.
    4. Use multiplier: In case you want to convert the value mathematically before storing, such as converting bits to bytes, select Custom multiplier. Type the number to multiply in the Custom multiplier field.
    5. Type of Information: Format of values that will be returned by this Attribute.
    6. Value: Option to find how much a value has changed since the last time this Attribute was queried. In this case, select Delta (speed per second) or Delta (simple change) to have FireScope SPM only record these values. Select As is to record the actual value.
    7. Update interval (in sec): This field determines how often, in seconds, FireScope SPM should retrieve or listen for new data.E.g. Enter 60 to check every minute, 3600 for once an hour, or 86400 for once a day.
    8. CI Profile Field: Name of a field (default or custom) to update for this CI's profile section. This feature is useful for selecting certain attributes as asset or CMDB information for a particular CI.
  5. Flexible intervals (sec): Use this setting to vary how often you want this data sampled.
  6. Attribute Display Options: Other options that will be affect the displaying method the data.
    1. Show value: Is the raw value of this attribute meaningful? If not, FireScope can display an alternative value using this setting.For example, if the possible results of this attribute are either 1 or 0, you can use value translations to display 'Good' for 1 and 'Bad' for 0.
    2. Item Type: Classify whether or not this attribute impacts the Security, Availability, Performance or Business Impact of the CI this attribute is associated with. Choose all that apply.
      1. Availability
      2. Performance
      3. Security
      4. Key Performance Indicator: Setting this property will enable some summary views of CIs to display the attributes labeled as KPI.
  7. Attribute Sets: Attribute Sets are related groups of attributes, such as MySQL performance attributes or Active Directory lookup metrics.
  8. Visual Control Display Setting: Use this section to automatically create graphs, gauges and meters based on the value of this attribute.
    1. Show Performance Display:
    2. Display Type:
  9. CI Metadata:
     Options for using metadata.
    1. Asset Name
    2. Type
    3. Detail
    4. SubType
    5. Index
    6. Vendor
    7. Label
  10. Tags: Tags are additional identification applied to the main configuration elements: Service Groups, Logical Groups, Configuration Items, Attributes, Event Definitions, Aggregate Event Definitions, Policies, and Visual Controls.Tags are used for search, reports and some specialized displays in the application. System default tags are applied to most agent attributes and some common SNMP (OID) attributes upon creation. You can always create or apply additional tags to any element to further identify each asset.
  11. Click on the Save button.


Note: To save time when configuring multiple similar CIs, use a Blueprint.

Edit an Attribute:

  1. In the Description column, click on the name of the Attribute you want to edit.
  2. If an Attribute is associated with a Blueprint, the Blueprint name precedes the Attribute name and not all fields are editable–such as the operation and type information. If you need to edit an Attribute associated with a Blueprint, select the Blueprint in the Configuration Field (step 3), and edit this Attribute.
  3. Edit the form. For more information about the Attribute fields, see Create Attribute.
  4. Click on the Save button.


Clone an Attribute:

  1. In the Navigation bar, select the appropriate CI and click on the Apply button, Attributes list refreshes for the selected CI.
  2. In the Description column, click on the name of the Attribute you want to clone.
  3. Edit the form. For more information about the Attribute fields, see Create Attribute.
  4. Click on the Save button.      


Delete Attribute

  1. In the Navigation bar, select the appropriate CI and click on the Apply button, Attributes list refreshes for the selected CI.
  2. In the Description column, check the box next to Attribute name you want to delete.
  3. From the drop-down in the bottom right corner of the page, select Delete selected.
  4. Click Update. A confirmation window will appears.Note: Deleting an Attribute will have a cascading delete effect. All elements that are based on this Attribute will be effected (for e.g.  Dashboards, AEDs, ED, Policies etc.. Data collected by this Attribute will be lost for good.)

Pastedimage1489786137139v1.png-622x171.png

Types of Attributes

Types of attribute defines how FireScope SPM gather values for an attribute, it could be either through the FireScope Agent, SNMP or other means.
Agent Remote

In the case of Agent Remote attributes, the Edge Device does not request the values from the Agent, instead the Agent periodically (as configured in the Agent configuration file) retrieves the list of currently active Agent Remote attributes from the Edge Device. After retrieving the list of Agent Remote attributes, the Agent periodically sends the values for those attributes back to the Edge Device.

 Agent configuration file refers to either firescope_agentd_posix.xml or firescope_agentd_win.xml file

This functionality is configured with following two properties in the FireScope Agent configuration file.# Agent should know which Edge Device has the list of agent remote attributes. This is configured in the Server property by adding the IP address of the Edge Device as the first entry in the command delimited list.
<prop>      <key>Server</key>      <value>10.0.12.64,10.0.12.61,10.22.121</value>      <description>List of comma delimited IP addresses of FireScope servers. First entry is used for sending active checks.</description>      <flags>0</flags></prop>In the example above, the agent will only request a list of agent remote attributes from the edge device with the IP "10.0.12.64" because it is the first (or only) IP in the list.

  1. The actual CI name should be set as the value for Hostname property. (Please note that the Hostname value is Case Sensitive)
     <prop>      <key>Hostname</key>      <value>eas-cent67</value>      <description>Unique hostname. Required for active checks and sentinel checks. For active checks, this unique host name must be same as the corresponding CI name.</description      <flags>0</flags></prop>
    In order to make sure that everything is setup correctly, set the value of DebugLevel property as 5 in the Agent Configuration file. 
     <prop>      <key>DebugLevel</key>      <value>5</value>      <description>Debug level for FireScope Agent. 0 - none, 1 - critical, 2 - error (default), 3 - warnings, 4 - info, 5 - debug (max info)</description>      <flags>2</flags></prop>


     Verify following two items inside the Agent log file firescope_agentd.log # This debug line indicates that that the agent is requesting the list of Agent Remote attributes (Message sent: FSC_GET_ACTIVE_CHECKS) for the CI with the name "eas-cent67".|DEBUG |2016-02-03|11:49:17|Thread[ 1495]|[TcpSenderReceiver.cpp:250]| Message sent: FSC_GET_ACTIVE_CHECKS eas-cent67

  1. A few lines below the FSC_GET_ACTIVE_CHECKS line, you should see the list of agent remote attributes and their "operation" field displayed.|DEBUG  |2016-02-04|11:07:55|Thread[236223207096]|[TcpSenderReceiver.cpp:146]| Received:agent_cpu_util:60:0:56b26a42ef134456164f344eagent_check:60:0:56b26de3ef13445e384f305cIn this case two operation are received which means there are two Agent Remote attributes configured for this CI.


Below is an example along with the description of Agent Remote Attribute.


Operation Description Examples
windows_eventvwr(parm)return type: LogMicrosoft Windows ONLYType: Agent Remote**Remote Only Collects events from Microsoft Windows Eventlog subsystemParameters:Log name: application, security, system,Optional Filter: * filters can be constructed with basic AND structure only* ,Here are the only valid values for optional filter:Type, Source, Category, EventID, Domain, User, Computer, Message  Example using multiple filters with pipe '|' delimeters:,windows_eventvwr(security,Type:Infomation|Source:Microsoft Windows security|Category:12800|EventID:5156|Domain:firescope|User:N/A|Computer:N/A|Message:Junk) 
Amazon AWS Attribute
Operation Description Examples
amazon_aws_metric(namespace, instanceId, metric)return type: Numeric (float)Type: Amazon AWS Attribute                       Value returned is a float Returns the current value of the specified AWS metricParameters:namespace = namespace of the target metricinstanceId = unique id of the target instancemetric = name of the metric                                        Example: amazon_aws_metric(AWS/EC2,i-f0016099,DiskReadOps)Returns the number of read operations for the specified instance 
Calculated Attribute

Calculated Attributes are metrics that FireScope SPM collects and evaluates against for events and performance. Calculated Attributes combine existing Attributes and logic that can include other Attributes.

To create a Calculated Attribute:# Create an Attribute. For more information, see Creating an Attribute. Specifically, set the following Data Collection Settings:

  1. In Type, select Calculated Attribute. The Calculated Attribute Builder section will be displayed.

8032.Calculated Attribute.png-776x434.png

  1. In the Calculated Attribute Builder section, click Select. The Attribute pop-up window will be displayed.

1108.Select Attribute.png-799x333.png

  1. Check the box next to all the Attributes you want to use, you can select multiple attributes.
  2. Click Select. The Create Attribute page is updated with the selected Attributes. Each Attribute is represented as a variable.   
  3. Select the appropriate math symbol(s) from the drop down box and click << to add the symbol to the expression.
  4. Base Units: Select base unit type appended to the end of all values for this Attribute whenever they are displayed. For example, (%) Percent for processor utilization, (B) Bytes for file system size, and (Bps) Bytes Per Second for network performance.
  5. Use multiplier: In case you want to convert the value mathematically before storing, such as converting bits to bytes, select Custom multiplier. Type the number to multiply in the Custom multiplier field.
  6. Type of Information: Format of values that will be returned by this Attribute.
  7. Value: Option to find how much a value has changed since the last time this Attribute was queried. In this case, select Delta (speed per second) or Delta (simple change) to have FireScope SDDM only record these values. Select As is to record the actual value.
  8. Update interval (in sec): This field determines how often, in seconds, FireScope SDDM should retrieve or listen for new data.E.g. Enter 60 to check every minute, 3600 for once an hour, or 86400 for once a day.
  9. CI Profile Field: Name of a field (default or custom) to update for this CI's profile section. This feature is useful for selecting certain attributes as asset or CMDB information for a particular CI.                     
  10. Click on the Save button.
Cisco UCS
Operation Description Examples
cisco_ucs_stat(dn, classname, statname)return type: CharacterType: Cisco UCSValue returned is stat dependent Returns the latest stat value for the specified dn and classnameParameters:dn = distinguished nameclassname = UCS class name statname = name of the stat  Example: cisco_ucs_stat(sys/chassis-1/blade-1/board/cpu-1/env-stats,processorEnvStats, temperature)Returns temperature of cpu-1 in blade-1 
Collecting Log Data(Windows Event Viewer, Application Logs)

FireScope SPM is capable of aggregating any standard OS or application log file and parsing it for Events. As log entries are sent to SPM, the entire log entry is stored as an Attribute. From this, you can create Event Definitions using simple text matches or complex regular expressions.

Before You Begin

  • Install the FireScope Agent on the asset where the log file is stored.
  • Ensure that the FireScope Agent has access to the asset's file system in order to read the log file.
  • Create a CI for the asset. For more information, see Creating a Configuration Item.


Application Logs:

  1. Log in to FireScope SPM as a FireScope or Configuration Administrator.
  2. Click Configuration > CIs > Attributes. The Attributes page displays the Attributes for the selected CI (in the top right corner).
  3. In Configuration Item, select the CI you want to create the Attribute for.
  4. Click Create. The Create Attribute page will be displayed.

2818.Create ATB.png-870x908.png  

  1. In Description, enter a descriptive name for the log file.
  2. In the Data Collection Settings section
    1. In Type, select Agent Remote.
    2. In Operation, type filesystem_logreader(<path to log file>, <optional parameters>). Refer to the table below for an example.
    3. In Type of Information, select Log
    4.  Complete the rest of the form. For more information about the Attribute fields, see Creating an Attribute.
    5. Click Save. All log entries for this asset will now be collected, associated with this Attribute, and stored as text-based data.


Example


Examples:
filesystem_logreader(/var/log/boot.log, ORA,1234)
filesystem_logreader(c:\Windows\setuplog.txt)


Windows Event Logs

For Microsoft Windows event logs, the process differs in one way. In Operation, type windows_eventvwr(<name of event log>,<optional filter with regex pattern>).

Log name: application, security, system, Optional Filter: Here are the only valid values for <optional filter>:Type, Source, Category, EventID, Domain, User, Computer, Message. Filters are delimited by pipe '|'.Example: windows_eventvwr(system) configures SPM to read the System Event Log.

Example:windows_eventvwr(security,Type:Infomation|Source:Microsoft Windows security|Category:12800|EventID:5156|Domain:firescope|User:N/A|Computer:N/A|Message:Junk)Note: You do not need to know the exact path for event logs.

Once this data is being collected, you can also quickly access the log entries via the search feature.

Days to Target Attribute
Operation Description Examples
days_to_target(operation,targetValue,type)return type: Numeric (integer 64bit)Type: Days to Target AttributeValue return is Long Returns the predicted number of days for the specified attribute to reach the specified targetParameters:operation = operation of the target attributetargetValue = target value (can be any value)type = one of above, below. Default is above  Example:days_to_target("infoblox_range(range/ZG5zLmRoY3BfcmFuZ2UkMTAuMC4xMy4xLzEwLjAuMTMuMjM5Ly8vMC8x,percentActive)",90)Returns the predicted number of days until the specified attribute hits 90 
[1]
Derived Check
Operation Description Examples
firescope_db(attributes)return type: Numeric (integer 64bit)Type: Derived Check Number of attributes in the FireScope database   
firescope_db(attributes_disabled)return type: Numeric (integer 64bit)Type: Derived Check Disabled Attribute count  A count of all disabled attributes for all accounts in the system 
firescope_db(attributes_enabled)return type: Numeric (integer 64bit)Type: Derived Check Enabled Attribute count  A count of all enabled attributes for all accounts in the system 
firescope_db(attributes_unsupported)return type: Numeric (integer 64bit)Type: Derived Check Number of unsupported attributes in the FireScope database   
firescope_db(cis)return type: Numeric (integer 64bit)Type: Derived Check Total CI count  A count of all CI's for all accounts in the system 
firescope_db(cis_disabled)return type: Numeric (integer 64bit)Type: Derived Check Disabled CI count  A count of all disabled CI's for all accounts in the system 
firescope_db(cis_enabled)return type: Numeric (integer 64bit)Type: Derived Check Enabled CI count  A count of all enabled CI's for all accounts in the system 
firescope_db(eventdefs)return type: Numeric (integer 64bit)Type: Derived Check Number of event definitions in FireScope database   
Dynamic Data Attributes

FireScope offers the Dynamic Data Attribute (DDA), which allows you to send data from your system to FireScope SPM proactively, as opposed to FireScope SPM polling your system for data. This method requires you to configure your system to send data via Transmission Control Protocol (TCP).

You can use this tool as the need arises to send as much data as you like. You can send single or multiple Attributes at once. You also determine the schedule and frequency for sending data using the DDA.

To make it easier to get started with Dynamic Data Attributes, we have sample scripts in Powershell (Click here for the Powershell sample script), and in Python (Click here to grab the Python sample script).

Creating the TCP Message

To use the DDA, you must send a TCP message via port 8043, with the following tags and variables. The message format will differ depending on the type of DDA you want to use (see the subsequent sections).


Tag/Variable Description
FSCP_PAYLOAD# Alerts FireScope SPM that the following is an fs_incoming message.This tag is required to start an inbound message.
<ATTRS></ATTRS> Denotes multiple Attributes. Include <ATTRS> before the first <ATTR> tag and </ATTRS> after the last </ATTR> tag.
<ATTR></ATTR> Denotes an Attribute.
CIname Name of the required CI.
operation Unique operation of the Attribute for this CI (i.e., fs_incoming(status) where status can be replaced with any descriptive and unique value for the Attribute to collect).
value Value of the Attribute (e.g., 42, "Success"), which must match the data type of the Attribute that is in the template (e.g., JSON, integer, float, character).
timestamp Time stamp value of the actual time (seconds from epoch) that the value sample occurred.Timestamp is optional. When timestamp is omitted, the time FireScope received the value is used.

There are two types of DDAs:* Incoming - For sending data elements to view, search, and graph in FireScope SPM.

  • JSON - For sending associated data elements that will be correlated in FireScope SPM. You can view, search, and graph this data too.


The following sections provide examples of each DDA type.

Incoming

The basic template for an Incoming DDA message is:

FSCP_PAYLOAD#<ATTRS><ATTR>CIname,operation,value,timestamp</ATTR></ATTRS>

The following example message illustrates a CI named myCI with an Attribute using the fs_incoming(status) operation:

FSCP_PAYLOAD#<ATTRS><ATTR>myCI,fs_incoming(status),"Failed"</ATTR></ATTRS>

Here is the same example as above, plus the time stamp:

FSCP_PAYLOAD#<ATTRS><ATTR>myCI,fs_incoming(status),"Failed",1349297031</ATTR></ATTRS>

To send multiple attributes, use the following examples for guidance.

Example 1

The following Incoming DDA message is formatted to send four separate Attributes at once.

FSCP_PAYLOAD#<ATTRS>
<ATTR>myCI,fs_incoming(A1),12345</ATTR>
<ATTR>myCI,fs_incoming(A2),753861.001</ATTR>
<ATTR>myCI,fs_incoming(A3),60812</ATTR>
<ATTR>myCI,fs_incoming(status),Success,1349297031</ATTR>
</ATTRS>

Example 2

This example shows another way to format an Incoming DDA message. This message sends two Attributes.

FSCP_PAYLOAD#<ATTRS>

<ATTR>
<CINAME>myCI</CINAME>
<OPERATION>fs_incoming(A1)</OPERATION>
<VALUE>12345</VALUE>
<TIMESTAMP>5678</TIMESTAMP>
</ATTR>
<ATTR>
<CINAME>myCI</CINAME>
<OPERATION>fs_incoming(A2)</OPERATION>
<VALUE>12345</VALUE>
<TIMESTAMP>5678</TIMESTAMP>
</ATTR>
</ATTRS>


Operation Description Examples
fs_incoming_json(uniqueTag)return type: JSONType: Attribute JSON IncomingValue is a JSON payload An attribute with JSON payload which allows incoming TCP message to update its valueParameters:uniqueTag = any value that can be used to uniquely identify this attribute  Example: fs_incoming_json(service1) 


JSON

If you want to send correlated data to FireScope SPM, use the JSON DDA. With JSON formatting, you can send multiple pieces of data from your system and ensure that those pieces of data will be correlated and available for viewing, searching, and graphing in FireScope SPM. (see Adding a Trend Graph )

For example, you want to find all the transactions that completed successfully but exceeded your elapsed time threshold. To accomplish this, create a JSON DDA with the following data elements:* Transaction ID

  • Status
  • Error Code
  • Elapsed Time


The following example is a message in JSON format that will send correlated data to FireScope SPM:

FSCP_PAYLOAD#<ATTRS>
    <ATTR>
        <CINAME>myCI</CINAME>
        <OPERATION>fs_incoming_json(J1)</OPERATION>
        <VALUE>{"transactionid":11111,"status":"Success","elapsedtime":10,"errorcode":400}</VALUE>
        <TIMESTAMP>5678</TIMESTAMP>
    </ATTR>
</ATTRS>

Note: You can also format a basic Incoming DDA message in the JSON DDA format.


Operation Description Examples
fs_incoming_json(uniqueTag)return type: JSONType: Attribute JSON IncomingValue is a JSON payload An attribute with JSON payload which allows incoming TCP message to update its valueParameters:uniqueTag = any value that can be used to uniquely identify this attribute  Example:fs_incoming_json(service1) 


Using the Dynamic Data Attribute in FireScope SPM

Once you send data using the DDA, you can view, search, and graph it just like any other system data you use in FireScope SPM. Each of the following sections gives you more information about the ways you can use the data you submitted via the DDA.

Attribute

To use the DDA in CIs and Templates, create an Attribute in FireScope SPM and:# In Type, select the Attribute type you are creating from the following options:

    1. Attribute Incoming
    2. Attribute JSON Incoming
  1. In Operation, insert a unique value (e.g., fs_incoming(status), fs_incoming_json(J1))Note: The value is case-sensitive and must be an exact match to an existing CI
  2. In Type of Information, select the appropriate option (e.g., JSON, integer, float, character).
  3. Complete the form.
  4. Click Save.


Once the Attribute is populated with data, the Last Value is displayed on the Attributes page. When you click the link in the Last Value column, a pop-up window displays more information.

  [[File:Dynamic Data Attribute Last Val.png-707x506.png ]]  Note: You can also create CIs, Logical Groups, and Service Groups, and link CIs to Templates and Groups via FireScope's REST API.

Event Definition

The following two screen shots show the JSON DDA used in an Event Definition.* Configuration for an Event Definition using the JSON DDA                                                                                                Dynamic Data ED.png-938x455.png


Visual Controls

Visual Controls are available with data obtained by the DDA just as they are for any data in FireScope SPM.

Reports

You can use the Reports in FireScope SPM to present your data obtained through DDA in an organized, meaningful way.

Firescope Agent

Following screen shot shows Firescope Agent Attributes collecting data.

 

Bp for hitesh 2.jpg-985x468.jpg

 

 Following is a list of all the agent attributes available.


Operation Description Parameters Win32/64 Linux  Solaris AIX
agent_attribute_timeoutsreturn type: Numeric (integer 64bit) Number of Attribute process timeouts in the last 1 Minute Measure of Attribute operation executions that time out    X X X X
agent_avg_processing_timereturn type: Numeric (float)Values in seconds Average time spent processing Attributes in the last 1 Minute Per attribute processing time average for allattributes in the past 1 minute    X X X X
agent_checkreturn type: Numeric (integer 64bit)Values: 0 (Failed) , 1 (OK) Check the availability of agent Checks whether the agent port (default 8042) is listening    X X X X
agent_cpu_utilreturn type: Numeric (float)Values in percentage CPU utilization generated by the FireScope Agent Percentage of total processor utilization by FireScope Agent.   X X X X
agent_current_versionreturn type: Character Version of Agent running o n host An Example of returned value is: 3.0.1    X X X X
agent_failed_attributesreturn type: Numeric (integer 64bit) Number of failed attributes processed in last 1 Minute Failed Attributes are Operations that are valid but are not supported by a particular OS or Host. EX: checking drive space on F: drive when that driveletter does not exist    X X X X
agent_invalid_attributesreturn type: Numeric (integer 64bit) Number of Invalid Attribute Operations in the last 1 Minute Invalid Attributes are the result of bad Operation Syntax (operation_)    X X X X
agent_memory_utilreturn type: Numeric (integer 64bit)Value in Bytes Memory consumed by FireScope Agent           
agent_store_and_fwdreturn type: Numeric (integer 64bit)Values: 0 (disabled) or 1 (enabled) Is Agent Batch Mode enabled Used to determine if Agent storing values to beforwarded to FireScope Appliance at a later time. Used for slow / WAN links    X X X X
agent_stored_bufferreturn type: Numeric (integer 64bit) Number of attributes stored in the buffer to be sent to Appliance Configure number of attribute values queued beforeforwarding to FireScope Appliance    X X X X
agent_successful_attributesreturn type: Numeric (integer 64bit) Number of successful attributes processed in last 1 Minute Attributes Operations that succeed whose values are forwarded to the Appliance    X X X X
agent_tcp_sessions(type)return type: Numeric (integer 64bit) TCP Session InformationParameters:type = one of listen, established, synsent,synrecv, finwait1, finwait2, timewait,close, closewait, lastack, closing Provides TCP Session information for the FireScope Agent           
type listen X X X N/A
established X X X N/A
synsent X X X N/A
synrecv X X X N/A
finwait1 X X X N/A
finwait2 X X X N/A
timewait X X X N/A
close X X X N/A
closewait X X X N/A
lastack X X X N/A
closing X X X N/A
deletetcb X N/A N/A N/A
idle N/A N/A X N/A
bound N/A N/A X N/A
agent_thread_countreturn type: Numeric (integer 64bit) Number of threads spawned by FireScope Agent Value is total number of thread beingbeing used by FireScope Agent agent_buildtag   X X X X
agent_buildtag Returns the current build tag   X X X X
cpu_interruptsreturn type: Numeric (integer 64bit) Number of Device interrupts. Will display the number of context switches currently inuse.    N/A X X X
cpu_switchesreturn type: Numeric (integer 64bit) Context switches.    N/A N/A X X
cpu_utilization([cpu] [,type] [,parameters])return type: Numeric (float)Values in percentage CPU(s) utilization.Parameters:cpu = CPU number (default is all CPUs)type = one of idle, nice, user (default), system, system_userparameters = one of avg1 (default), avg5, avg15    X X X X
type idle N/A X X X
nice N/A X N/A N/A
user N/A X X X
kernel N/A N/A X N/A
wait N/A N/A X X
system X X N/A X
parameters avg1 X X N/A X
avg5 X X N/A X
avg15 X X N/A X
filesystem_checksum(file)return type: Numeric (integer 64bit) Calculate file check sumParameters:file = full path to file Example of returned value:1938292000Example:filesystem_checksum(/etc/passwd)    X X X X
filesystem_device_read(device [,type])return type: Numeric (integer 64bit) Disk read statistics.Parameters:device = disk device, type - one of sectors (Linux default), operations, bytes (Solaris Default)bytes N/A for Linux, sectors N/A for Solaris    N/A X X N/A
type sectors N/A X N/A N/A
operations N/A X X N/A
bytes N/A N/A X N/A
filesystem_device_write(device [,type])return type: Numeric (integer 64bit) Disk write statistics.Parameters:device = disk device, type - one of sectors (Linux default), operations, bytes (Solaris Default)bytes N/A for Linux, sectors N/A for Solaris Example: filesystem_device_write(sda,operations)    N/A X X N/A
type sectors N/A X N/A N/A
operations N/A X X N/A
bytes N/A N/A X N/A
filesystem_file_exists(file)return type: Numeric (integer 64bit)Values: 0 (file does not exist), 1 (file exists) Check if file existsParameters:file = full path to file Example:filesystem_file_exists(/tmp/application.pid)    X X X X
filesystem_file_md5sum(file)return type: CharacterType: FireScope AgentMD5 hash of the file. Can be used only for files less than 64MB, unsupported otherwise. File's MD5 check sum Example of returned value:b5052decb577e0fffd622d6ddc017e82Example:filesystem_file_md5sum(/etc/FireScope/FireScope_agentd.conf)    X X X X
filesystem_filesize(file)return type: Numeric (integer 64bit)Values in bytes Return size of specified fileValue returned in bytesParameters:filesize = full path to file File must have read permissions for user FireScopeExample:filesystem_filesize(/var/log/syslog)    X X X X
filesystem_filesystemsreturn type: CharacterValue returned as a comma separated list Drives/Filesystems currently mapped/mountedParameters:None           
filesystem_inode(filesystem [,parameters])return type: Numeric (float)Type: FireScope Agent Number of inodesParameters:parameters - one of total [default], free, used, pfree[free, percentage], pused [used, percentage]  system X X N/A X
parameters total N/A X X X
free N/A X X X
used N/A X X X
pfree N/A X X X
pused N/A X X X
filesystem_logreader(fullpath)     X X X X
filesystem_regexpression(file, regex)return type: Character Find string in a file nameParameters:file = full path to file, regex = GNU regular expression Example:filesystem_re   X X X X
filesystem_regmatch(file, regex)return type: Numeric (integer 64bit)Values: 0 (expression not found), 1 (expression found) Find string in a file nameParameters:file = full path to file, regex = GNU regular expression Example:filesystem_regmatch(/var/log/app.log,error)    X X X X
filesystem_size(fs [,parameters])return type: Numeric (float)Values in Kbytes Disk spaceParameters:parameters - one of total [default], free, used, pfree [free, percentage], pused [used, percentage] In case of a mounted volume, disk space for local file system is returned.    X X X X
parameters total X X X X
free X X X X
used X X X X
pfree X X X X
pused X X X X
filesystem_time(file[, parameters])return type: Numeric (integer 64bit)Values in seconds File time information.Parameters:file = full path to fileparameters = one of modify [default, modification time], access = last access time, change = last change time Example:filesystem_time(/etc/passwd,modify)    X X X X
parameters modify X X X X
access X X X X
change X X X X
host_boottimereturn type: Numeric (integer 64bit) Unix time when the machine was booted    N/A X N/A N/A
host_connected_usersreturn type: Numeric (integer 64bit) Number of users connected. Counts number of users currently connected to host    N/A X X X
host_informationreturn type: Character Returns detailed host information. Example of returned value:FreeBSD localhost 4.4-RELEASE FreeBSD 4.4-RELEASE #0: Tue Sep 18 11:57:08 PDT 2001 murray@builder.FreeBSD.org: /usr/src/sys/compile/GENERIC i386    X X X X
host_local_timereturn type: Numeric (integer 64bit)Values in seconds System local time returned in the number of seconds since Jan 1, 1970    X X X X
host_namereturn type: Character Returns the name of the host. Example of returned valuewebserv01.firescope.com    X X X X
host_run(command[,parameters])return type: Character Run specified command on the host.Parameters:command = command for executionparameters = one of wait [default, wait end of execution],nowait [do no wait] Example:host_run[ls -l /] - detailed file list of root directory.Note:To enable this functionality, agent configuration file must have EnableRemoteCommands=1 option.    X X X X
parameters wait X X X X
nowait X X X X
host_uptimereturn type: Numeric (float)Values in seconds System's uptime in seconds. Use Units s or uptime to get readable values.    X X X N/A
jmx_delegate(parm)return type: CharacterType: FireScope AgentJMX attribute value Collect JMX valueParameters:parm = JMX attribute    X X X X
memory_size([parameters])return type: Numeric (float)Values in bytes Memory sizeParameters:parameters - one of total [default], shared, total, buffers, cached, free, pfree, available    X X X X
parameters total X X X X
shared N/A X N/A N/A
buffers N/A X N/A N/A
free X X X X
pfree X X X X
used N/A N/A N/A N/A
pused N/A N/A N/A N/A
cached X X N/A N/A
available N/A N/A X N/A
mongostat(insert)return type: CharacterValue is user specified Collect mongo statisticsParameters:Valid column names are: insert, query, update, delete, getmore, command, flushes, mapped, vsize, res, faults, locked_%, idx_miss_%, qr, qw, ar, aw, netIn, netOut, conn, set, repl, time Example: mongostat(insert)    X X X X
mqseries_queue([queuemanager],queuename[,param])return type: Numeric (integer 64bit)Value returned as count Returns statistics on an MQSeries queueParameters:queuemanager = queue manager name, queuename = queue name, param = one of curdepth or maxdepth Example: mqseries_queue(myqueuemgr,myqueue,curdepth)    N/A N/A X N/A
parameters curdepth X X X X
maxdepth N/A N/A X N/A
mqseries_queuemanager(queuemanager)return type: CharacterReturns one of: Starting Running Quiescing Ending immediately Ending preemptively Ended normally Ended immediately Ended unexpectedly Ended preemptively Returns status of MQSeries queue managerParameters:queuemanager = queue manager name Example: mqseries_queuemanager(myqueuemanager)    N/A N/A X N/A
network_dns_availability(ipaddress, domain)return type: Numeric (integer 64bit)Values: 0 (DNS down), 1 (DNS up) Checks the availability of a DNS service.Parameters:ipaddress = IP address of DNS serverDomain- Domain to check on DNS Example:network_dns_availability (192.168.0.1,FireScope.com)    N/A X X X
network_interface_collision(interface)return type: Numeric (integer 64bit) Out-of-window collision. Total number of collisions for interface.An Example of returned value is: 55    N/A X X X
network_interface_incoming(interface[, parameters])return type: Numeric (integer 64bit) Incoming network statistics per interface.Parameters:parameters = bytes total number of bytes by interface. This is the default.packets = total number of packets by interfaceerrors = total number of errors by interfacedropped - total number of dropped packets by interface Example:network_interface_incoming(eth1,packets)This operation can be used with Delta (speed per second) in order to get bits per second statistics.    X X X X
parameters bytes X X X X
packets X X X X
errors X X X X
dropped X X N/A N/A
network_interface_outgoing(interface [,parameters])return type: Numeric (integer 64bit) Outgoing network statistics per interface.Parameters:parameters = bytes total number of bytes by interface. This is the default.packets = total number of packets by interfaceerrors = total number of errors by interfacedropped = total number of dropped packets by interface Example:network_interface_outgoing(eth1,packets)You can combine this operation with Delta (speed per second) and get bits per second statistics per interface.    X X X X
parameters bytes X X X X
packets X X X X
errors X X X X
dropped X X N/A N/A
network_interface_total(interface[, parameters])return type: Numeric (integer 64bit) Total network statistics per interface.Parameters:parameters = bytes total number of bytes by interface. This is the default.packets = total number of packets by interfaceerrors = total number of errors by interfacedropped - total number of dropped packets by interface Example:network_interface_total(eth1,packets)This operation can be used with Delta (speed per second) in order to get bits per second statistics.    X X X X
parameters bytes X X X X
packets X X X X
errors X X X X
dropped X X N/A N/A
network_listen(port)     N/A N/A N/A N/A
network_performance_tcp_service(service [,ipaddress] [,port])return type: Numeric (float)Values: 0 (service down), sec (number of seconds spent while connecting to service) Check performance of service Parameters:service = one of ssh, nntp, ldap, smtp, ftp, http, pop, imap, tcp, etcipadd = IP address [The default is 127.0.0.1]port - port number [by default standard service port number is used] Example:network.tcp.service.perf(ssh) = Used to test speed of initial response from SSH server.    X X X X
service ssh X X X X
nntp X X X X
ldap X X X X
smtp X X X X
ftp X X X X
http X X X X
pop X X X X
imap X X X X
tcp X X X X
network_tcp_port_check([ipaddress], port)return type: Numeric (integer 64bit)Values: 0 (cannot connect to port), 1 (can connect to port) Check, if it is possible to make TCP connection to the given port.Parameters:ipaddress = IP address. The default is 127.0.0.1port = The port number  Example:network_tcp_port_check (192.168.0.1,80) = Can be used to test availability of WEB server running on port 80.    X X X X
network_tcp_service_check(service [,ipaddress] [,port])return type: Numeric (integer 64bit)Values: 0 (service down), 1 (service running), 2 (timeout connecting) Check if service is running and accepting TCP connections.Parameters:"service = one of ssh, nntp, ldap, smtp, ftp, http, pop, imap, tcp, etcipaddress = IP address [the default is 127.0.0.1]"ipaddress = IP address [the default is 127.0.0.1]port = port number [by default standard service port number is used] Example:network_tcp_service(ftp,,45) = Can be used to test availability of FTP server using TCP port 45.    X X X X
service ssh X X X X
nntp X X X X
ldap X X X X
smtp X X X X
ftp X X X X
http X X X X
pop X X X X
imap X X X X
tcp X X X X
number_processes([name] [,account] [,state][,commandline])return type: Numeric (integer 64bit) Number of processes by name having state running under authenticated accountParameters:name = process nameaccount = account name [the default is all users]state = one of all [default], run, sleep, zombcommandline = filter by command line Example:number_processes [apache2,www-data] = The total number of apache2 processes running under the www-data accountnumber_processes [,oracle,sleep,oracleFireScope] = number of processes in sleep state running under oracle having oracleFireScope in its command line    X X X X
state all X X X X
run N/A X X X
sleep N/A X X X
zomb N/A X X X
idle N/A N/A N/A N/A
stopped N/A N/A N/A N/A
process_cpu(regex)return type: Numeric (float)Values in percentage CPU utilization of an individual processParameters:regex = regex that should match the contents of the /proc//cmdline file Example: process_cpu(httpd)CPU utilization of the h   X X X X
process_memory([processname] [,account] [,parameters][,commandline])return type: Numeric (float) Total memory used by each process running under agiven authenticated accountParameters:processname = the name of the processaccount = user name [the default is all users]parameters = one of avg, max, min, sum [default]commandline = filter by command line syntax Example:process_memory[,root] = memory used by all processes running under user "root".proc.mem[,oracle,max,oracleFireScope] = The amount of memory used by most memory hungry process running under oracle having oracleFireScope in its command line   N/A X X X
parameters avg N/A X X X
max N/A X X X
min N/A X X X
sum N/A X X X
swap_in([device] [,type])return type: Numeric (integer 64bit)Swap statistics Swap in.Parameters:device - swap device (default is all),type - one of count (default, number of swapins), pages (pages swapped in), sectors (sectors swapped in) Example:system.swap.in(,bytes)    X X X X
type count N/A X X N/A
pages N/A X X N/A
sectors N/A X N/A N/A
swap_out([device] [,type])return type: Numeric (integer 64bit)Swap statistics Swap in.Parameters:device - swap device (default is all),type - one of count (default, number of swapouts), pages (pages swapped out), sectors (sectors swapped out) Example:system.swap.out(,pages)    N/A X X N/A
type count N/A X X N/A
pages N/A X X N/A
sectors N/A X N/A N/A
swap_size([device] [,parameters])return type: Numeric (float)Values in bytes or percentage Swap space.Parameters:device - swap device (default is all),type - one of free (default, free swap space), total (total swap space), pfree (free swap space, percentage), pused (used swap space, percentage)pfree and pused are Linux only Example:swap_size(,pfree) - returnspercentage of free swap spaceswap_size(,free) returns bytesof free swap space    N/A X X X
type free X X X X
used N/A N/A N/A N/A
total X X X X
pfree N/A X X X
pused N/A X X X
system_load([parameters])return type: Numeric (float) Current load by CPU(s).Parameters:parameters = one of avg1 [default], avg5, avg15 (average within 15 minutes) Example:system_load(avg5)           
parameters avg1 X X X X
avg5 X X X X
avg15 X X X X
webpage_get(host,[path],[port])return type: Log Get content of WEB pageParameters:WEB page source as text Returns EOF on fail.Example:webpage_get(www.FireScope.com,index.php,80)    X X X X
webpage_performance(host,[path],[port])return type: Numeric (float)Values in seconds Get timing of loading full WEB pageParameters:host - hostname, path - path to HTML document (default is /), port - port number (default is 80) Example:webpage_performance(www.FireScope.com,index.php,80)    X X X X
webpage_regexpression(host, [path], [port], [regexp], [length,)return type: Character Get first occurence of regexp in WEB pageParameters:host - hostname, path - path to HTML document (default is /), port - port number (default is 80), regexp - GNU regular expression, length - number of characters to return Example:webpage_regexpression(www.FireScope.com,index.php,80)    X X X X
windows_eventvwr(parm[,{custom}])     X N/A N/A N/A
parameters application X N/A N/A N/A
security X N/A N/A N/A
system X N/A N/A N/A
{custom} X N/A N/A N/A
windows_perfmon(parm)return type: Numeric (float)Microsoft Windows ONLY Value from Windows Perfmon metricParameters:Path to Perfmon metric. See "typeperf" Windows command to locate Path Example: windows_perfmon(\Terminal Services\Total Sessions)    X N/A N/A N/A
windows_process(processName [,attribute] [,type])return type: Numeric (integer 64bit)Microsoft Windows ONLY Information on specific Windows ProcessesParameters:processName = process nameattribute = one of vmsize,wkset,pf,ktime,utime,gdiobj,userobj,io_read_b,io_read_op,io_write_bio_write_opio_other_b,io_other_optype = one of min,max,avg,sum Example:windows_process(outlook.exe,utime,avg)    X N/A N/A N/A
attribute vmsize X N/A N/A N/A
wkset X N/A N/A N/A
pf X N/A N/A N/A
ktime X N/A N/A N/A
utime X N/A N/A N/A
gdiobj X N/A N/A N/A
userobj X N/A N/A N/A
io_read_b X N/A N/A N/A
io_read_op X N/A N/A N/A
io_write_b X N/A N/A N/A
io_write_op X N/A N/A N/A
io_other_b X N/A N/A N/A
io_other_op X N/A N/A N/A
type min X N/A N/A N/A
max X N/A N/A N/A
avg X N/A N/A N/A
sum X N/A N/A N/A
windows_service_status(Service)return type: Numeric (integer 64bit)Microsoft Windows ONLY Values: 0 (running), 1 (paused), 2 (start pending), 3 (pause pending), 4 (continue pending), 5 (stop pending), 6 (stopped), 7 (unknown), 255 (error) Staus of Windows ServiceNOTE: Microsoft Windows ONLYParameters:Must be the"Service name"as displayed on the General tab in Windows Service Control Panel Example:Service Name: Spoolerwindows_service_status(Spooler   X N/A N/A N/A
wmi_delegate(parm)     X N/A N/A N/A

 

 

Group Checked Attribute

Grouped Check Attributes let you group and perform calculations on the same Attribute across multiple Configuration Items (CIs) within a single Logical Group. Multiple functions are supported, including averaging the current attribute value, identifying the maximum or minimum current value, and adding the values together for a group sum. This allows you to define a single event trigger that monitors a metric across multiple CIs, which is especially useful in web farm scenarios. As add or remove CIs from the Logical Group specified, you do not need to modify the Grouped Check Attribute.

Grouped Checks are ideal for scenarios where all CIs in the Logical Group are similar models of hardware, software, and production utilization.

Format

The format for a Grouped Check Attribute is as follows:

grouped_operation(group,operation,function,parm)

The following table describes each variable used in the Grouped Check Attribute operation:


Variable Description
group Existing Logical Group.
operation Exact operation syntax of the Attribute you're grouping.
function Operator that works with the parameter to determine how many samples or over what time period you want to calculate.
parm Parameter–time period or number of samples.

Variable

Supported Operations

The following operations are supported with the Grouped Check Attribute:


Operation Description
grouped_average Average of the values taken for the group.
grouped_maximum Maximum value of those taken for the group.
grouped_minimum Minimum value of those taken for the group.
grouped_sum Sum of the values taken for the group.

 

Supported Functions

The following functions are supported in the Grouped Check Attribute operations:


Function Description
avg Average value.
count Number of values.
last Last value.
max Maximum value.
min Minimum value.
sum Sum of values.


 

 Examples

Additional examples of keys for Grouped Check Attributes: * Example 1: Total disk space of Logical Group 'MySQL Servers' grouped_sum("MySQL Servers","vfs.fs.size[/,total]","last","0")

  • Example 2: Average processor load of Logical Group 'MySQL Servers' grouped_average("MySQL Servers","system.cpu.load[,avg1]","last","0")
  • Example 3: Average (5min) number of queries per second for Logical Group 'MySQL Servers' grouped_average("MySQL Servers","mysql.qps","avg","300")
Infoblox Attribute
Operation Description Examples
infoblox_range(ibRef, statname)return type: CharacterType: Infoblox AttributeValue returned is stat dependent Returns the latest range stat value for the specified ibRefParameters:ibRef = id of the rangestatname = percentActive, totalSize, totalActive, totalFree  Example: infoblox_range(range/ZG5zLmRoY3BfcmFuZ2UkMTAuMC4xMy4xLzEwLjAuMTMuMjM5Ly8vMC8x,percentActive)Returns the percent of Active leases for the specified range 
JMX

JMX is a Java standard for monitoring and managing applications written in the Java development language. JMX supports distributed monitoring and management capabilities and allows access to JMX attributes and operations via a variety of access protocols.

Firescope leverages the access capabilities made available in JMX to deliver the ability to monitor or manipulate many JMX data attributes or operations. In order to deliver these capabilities several configurations must be initiated. The following document is intended to guide you through the necessary configurations required to enable JMX capabilities for use with the FireScope appliance.

Firescope JMX Monitoring Architecture

The figure below details a simple FireScope appliance monitoring two hosts, each of which houses two Java applications.

JMX diagram 002.png-818x491.png

Configuration Summary The following points highlight the necessary steps required for JMX monitoring with FireScope:* Configure your Java virtual machine (JVM) to allow access to its MbeanServer.

  • Use JConsole if necessary to discover deployed Mbean names, attribute names and operation names.
  • Create new UserParameters in your remote FireScope agent which will in turn make invocations through the jmxdelegate.jar file to interact with your targeted JMX beans.
  • Create items on the FireScope server which reference the newly created UserParameters.


JVM Configuration

Each JVM that will be monitored must be configured to allow access to the JMX server that runs inside of each monitored JVM. Configuration is accomplished by providing a few system parameters to the JVM upon application startup. The parameters are listed below along with their description.


Parameter Value Type Example Description Required
com.sun.management.jmxremote None   Instruct the JVM to enable remote JMX access Yes
com.sun.management.jmxremote.port Numeric 3900 Server port that JMX server allows access on. Yes
com.sun.management.jmxremote.authenticate Boolean 0 Currently authenticated access is not supported. Yes

Example:/ /java -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=3306 -Dcom.sun.management.jmxremote.authenticate=false

Warnings: * Each configured Java virtual machine must use a separate port configuration.

  • Configured ports must not conflict with any ports currently in use on the system being configured.
  • Use netstat to ensure valid selection of configured ports.
  • On Unix / Linux systems use ports > than 1000


Use netstat prior to starting or restarting your application to ensure that the configured port is not in use. Restart your Java application using the new configuration. Then run netstat again to ensure that the system reports a listening port on the selected configuration port.

JMX Discovery

JConsole is a JVM monitoring application that has been in existence since the release of Java JDK 1.5.x. With JConsole it is possible to explore all JMX managed beans in a virtual machine once the JVM is configured to allow JMX remote access as described above. The JConsole executable can be found in the bin directory for your JDK1.5.x or greater installation.

Launch JConsole and select the "Remote Process" option button. Enter "localhost: " in the entry text box, where the port is the configured JMX listener port. Then select the "Connect" button.

Once started, JConsole will display several tabs. Select the "Mbeans" tab. Along the left hand side is a tree view that lists each deployed Mbean in the JMX Managed Bean Server. The treeview allows exploring down to each Mbean and displays each Mbean attribute or operation. Once you have navigated down to the bean level JConsole will display the Mbean name in the display on the right hand side.

Notes:* JConsole is not required for use with the FireScope monitoring. It is described here for the user's understanding and for exploring beans deployed to your Mbean server.

  • JConsole is part of the JDK download, not the JRE.
  • All Mbeans are uniquely identified by name.
  • In order to access the attributes or operations of an Mbean you must reference the bean using its unique name.
  • In order to maintain uniqueness in names servers such as Tomcat and JBoss, use complex nested names.


Individual JMX Attribute Access

FireScope makes available a client access tool called jmxdelegate for querying and setting individual Mbean attributes and invoking Mbean operations. As described above, the JConsole utility can be used to determine the names and attributes of Mbeans deployed in a particular java virtual machine. The bean names, attributes names and operation names are passed to the jmxdelegate tool for access.

First deploy the jmxdelegate.jar file to an appropriate location on your monitored system. The following example uses a bean names from a system that has a default Tomcat version 6.0.13 deployed running and configured for JMX access.

The jmxclient tool uses the following command format:/java -Dhost= -Dport= -DbeanName= -Dattribute= -Dparameters= -DnestedResult= -jar /jmxdelegate.jar

 


Parameter Required Description
  Yes Path to the Java VM executable file
  Yes Host for JMX access. Typically is localhost.
  Yes Port for JMX access.
  Yes Name of the managed bean of interest obtained via JConsole.
  No Name of the manager bean attribute or operation of interest obtained via JConsole.
  No The attribute or operation parameters if any
  No The name of a sub-element in a CompositeResult.

The following example command line will retrieve the requestCount? Attribute from the deployed tomcat manager application that comes as a part of the standard Tomcat deployment:

/java -Dhost=localhost -Dport=3306 -DbeanName= Catalina:j2eeType=Servlet,name=HTMLManager,WebModule=//localhost/manager,J2EEApplication=none,J2EEServer=none -Dattribute=requestCount -jar jmxdelegate.jar

Note the nested / complex bean name created by Tomcat shown again as follows:Catalina:j2eeType=Servlet,name=HTMLManager,WebModule=//localhost/manager,J2EEApplication=none,J2EEServer=none

Invoking the above command returns the current requestCount.

Now invoke the manager via a web browser as follows:http://localhost:8080/manager/html

Then re-invoke jmxclient tool to show that the request count increases with each manager invocation.

Example of FireScope JMX Managed Beans

The FireScope solution is delivered with an application called SyslogListener. The SyslogListener application receives syslog messages over TCP/IP and transfers these messages to the FireScope database. The SyslogListener application contains a few managed beans which expose some data points which may be of interest to FireScope users. The exposed beans are described in the following table:

 


Bean Name Bean Attribute / Operation Description
com.firescope.sysloglistener:name=ReceiveMessageCount PerMinuteMessageCount Number of messages received during the last minute of operation
com.firescope.sysloglistener:name=ReceiveMessageCount DailyMessageCount Cumulative number of messages received since midnight
com.firescope.sysloglistener:name=PersistedMessageCount PerMinuteMessageCount Number of messages saved during the last minute of operation
com.firescope.sysloglistener:name=PersistedMessageCount DailyMessageCount Cumulative number of messages saved since midnight
com.firescope.sysloglistener:name=MessageExecutionTime DurationMilliSeconds Processing time in milli-seconds for the last received message
com.firescope.sysloglistener:name=DatabaseRefresher ForceDatabaseRefresh Force all queries to re-issue queries for the next message

Accessing the FireScope managed beans can be accomplished via the following jmxclient invocations:

/java -Dhost=localhost -Dport=3306 -DbeanName=com.firescope.sysloglistener:name=ReceiveMessageCount -Dattribute=PerMinuteMessageCount -jar jmxdelegate.jar /java -Dhost=localhost -Dport=3306 -DbeanName=com.firescope.sysloglistener:name=ReceiveMessageCount -Dattribute=DailyMessageCount -jar jmxdelegate.jar /java -Dhost=localhost -Dport=3306 -DbeanName=com.firescope.sysloglistener:name=PersistedMessageCount -Dattribute=PerMinuteMessageCount -jar jmxdelegate.jar /java -Dhost=localhost -Dport=3306 -DbeanName=com.firescope.sysloglistener:name=PersistedMessageCount -Dattribute=DailyMessageCount -jar jmxdelegate.jar /java -Dhost=localhost -Dport=3306 -DbeanName=com.firescope.sysloglistener:name=MessageExecutionTime -Dattribute=DurationMilliSeconds -jar jmxdelegate.jar /java -Dhost=localhost -Dport=3306 -DbeanName=com.firescope.sysloglistener:name=DatabaseRefresher -Dattribute=ForceDatabaseRefresh -jar jmxdelegate.jar

Note:  The managed beans listed above will not appear or be available until after the SyslogListener has received at least 1 message.

FireScope JMX Agent Configuration

The following list outlines prerequisites for enabling FireScope JMX monitoring on remote hosts:* A valid Java runtime (JRE) must be deployed and available on the remote host

  • The jmxdelegate.jar file must be deployed and executable on the remote host.
  • UserParameters must be defined and added to the agent configuration file on the remote host.
  • The remote agent must be restarted
  • It is recommended that the new UserParameter be tested on the remote host


For the purposes of this example we shall assume each of the following has been configured as described below:* A Java VM has already been configured for JMX access on port 4900

  • A Java executable exists in the path
  • The jmxdelegate.jar file has been deployed to /jars directory
  • Our new user parameter shall be called “java.application.monitored.valueâ€?
  • Our JMX bean name is called “application.MBeanâ€?
  • The property of interest on this Mbean is called “propertyâ€?


To configure our new user parameter we edit the agent configuration file by adding the following line:UserParameter=java.application.monitored.value,java -Dhost=localhost -Dport=4900 -DbeanName=application.MBean -Dattribute=property -jar /jars/jmxdelegate.jar

FireScope JMX Server Configuration

Create a Configuration Item (CI) that references the UserParameter that was created in the previous section. See Creating a Configuration Item.

JMX Enabling Your Own Java Applications

The code listed below describes the steps necessary to make your applications JMX capable. The process covered outlines only standard Mbeans. For more information regarding other typs of Mbeans such as MXBeans, or DynamicBeans refer to the following JMX API documentation or Java tutorial: http://java.sun.com/javase/6/docs/api/.

http://java.sun.com/javase/6/docs/technotes/guides/jmx/tutorial/tutorialTOC.html.

For any class that you wish to make available to JMX you must write an Mbean interface that lists the available JMX methods. The Mbean interface name must have the same prefix name as the implementing class.

public interface ExecutionMessageCounterMBean { public long getPerMinuteMessageCount(); public long getDailyMessageCount(); }

Then provide an implementation for the above interface such as the following:

package example:

import java.util.Calendar; 
public class ExecutionMessageCounter implements ExecutionMessageCounterMBean 
{ 
private int lastIndex; 
private long[] perMinuteMessageCount; 
public ExecutionMessageCounter() 
{ 
super(); 
lastIndex = 0; 
perMinuteMessageCount = new long[1440]; 
} 
public long getPerMinuteMessageCount() 
{ 
int perMinuteMessageCountIndex = getMinuteIndexNow();
return perMinuteMessageCount[perMinuteMessageCountIndex];
} 
public long getDailyMessageCount() 
{ 
long dailyMessageCount = 0; 
for(long oneMinuteCount : perMinuteMessageCount) 
{ dailyMessageCount += oneMinuteCount; }
return dailyMessageCount; }
private synchronized int getMinuteIndexNow() 
{ 
Calendar calendar = Calendar.getInstance(); 
int resultIndex = calendar.get(Calendar.HOUR_OF_DAY) * 60 + calendar.get(Calendar.MINUTE); return resultIndex; 
} 
}

Now register your managed bean with the local Mbean server. Each bean must be registered using a unique name. For purposes of this example we shall use the domain of “example†and a name of “MessageCounter†as shown below:

ExecutioinMessageCounter counter = new ExecutionMessageCounter(); 
MBeanServer mBeanServer = ManagementFactory.getPlatformMBeanServer(); 
try { ObjectName objectName = new ObjectName(“example:name=MessageCounterâ€); mBeanServer.registerMBean(counter, objectName); } 
catch(Exception exception) 
{ // Add appropriate exception handling }
LDAP Check

Creating an LDAP Check attribute

Note: Before you can create LDAP Check attributes, you should define appropriate credentials to be used to execute the LDAP Queries.

Once you have working LDAP credentials attached to the CI, you can create the LDAP check attributes. Only attributes of CI’s associated to an LDAP credentials will be able to collect LDAP data.# Click on create button on the upper right hand corner of the Attribute page.Note: Make sure appropriate CI is selected.

  1. In the Data Collection Settings section select LDAP Check from the Type dropdown list.

LDAP Check Attribute.png-800x193.png

  1. Click on the Select Operation button and click on LDAP_Check. This will give you the syntax and examples for this attribute.



Operation Description Example
(searchDN,ldapAttrName,ldapFilter)return type: CharacterType: LDAP CheckValue returned is attribute dependent Retrieves information from LDAPParameters:searchDN = LDAP search DN, ldapAttrName = LDAP attribute to be searched, ldapFilter = LDAP search filter  Example: ldap_check("ou=Users,dc=YourCompany,dc=com","mail","dn=Bugs Bunny") 
  1. When defining the LDAP query ensure that you retrieve information which you can use as an attribute. For e.g. If you wanted to test if any account that begins “SVC-“ is locked out, you could write an LDAP query to simply return true or false, but it may well be more useful to write one which returns a list of those accounts which are locked out. This way, when you add this to a notification, the recipient knows which account(s) to investigate. As an example the following LDAP_Check attribute returns a list of accounts starting “SVC-“ which are currently locked out
    ldap_check("CN=Users,DC=firescope,DC=com","cn","(&(cn=SVC-*)(lockoutTime>=1))")
  2. Select appropriate data type returned from the query from Type of Information dropdown list. In the above example it would be character.
  3. Set the Update Interval.
  4. Click Save. 
NetApp DFM Attribute
Operation Description Examples
netapp_dfm_volume(volumeId, volumeKey)return type: CharacterType: NetApp DFM AttributeValue returned is stat dependent Returns the latest volume stat value for the specified volumeId and volumeKeyParameters:volumeId = id of the volumevolumeKey = name of the stat  Example: netapp_dfm_volume(123,volume-size:afs-used)Returns the number of bytes used on volume 123 
Netapp Check
Operation Description Examples
netapp_capacity(algorithm)return type: Numeric (integer 64bit)Type: NetApp CheckValue returned in Bytes Returns the latest filer capacity for the specified algorithmParameters:algorithm = The algorithm to be performed:totalRawCapacity,totalFormattedCapacity,totalSpareCapacity,totalCapacityInRaidSpace,totalCapacityInWaflReserve,totalCapacityInReservedSpace,totalCapacityForProvisioning,totalCapacityAllocated,totalCapacityOfUserUsableData,totalCapacityAvailable  Example:netapp_capacity(totalSpareCapacity)Returns the capacity of all spares on the filer 
netapp_disk(aggregateName, diskUid, diskKey)return type: CharacterType: NetApp CheckValue returned is stat dependent Returns the latest disk stat value for the specified aggregateName, diskUidAnd diskKeyParameters:aggregateName = name of the aggregatediskUid = UID of the diskdiskKey = name of the stat  Example:netapp_disk(aggr0,5000CCA0:0996A808:00000000:00000000:00000000:00000000:00000000:00000000:00000000:00000000,rpm)Returns the rpm for the specified disk on aggr0 
netapp_perf(object, instance, counter)return type: CharacterType: NetApp CheckValue returned is counter dependent Returns the latest counter value for the specified object and instanceParameters:object = the perf objectinstance = the perf instancecounter = the perf counter  Example:netapp_perf(system, system, http_ops)Returns number of http ops for system instanceof the system object 
netapp_snapshot(volumeName, snapshotName, snapshotKey)return type: CharacterType: NetApp Check Value returned is snapshotKey dependent Returns the latest snapshot stat value for the specified volumeName, snapshotNameAnd snapshotKeyParameters:volumeName = name of the volumesnapshotName = name of the snapshotsnapshotKey = name of the stat  Example: netapp_snapshot(vol0,hourly.0,total)Returns total snapshot space for hourly.0 on vol0 
netapp_snapshot_aggregate(volumeName, snapshotKey)return type: Numeric (integer 64bit)Type: NetApp CheckValue returned is Long Returns the latest aggregate snapshot stat value for the specified volumeNameAnd snapshotKeyParameters:volumeName = name of the volumesnapshotKey = name of the stat  Example:netapp_snapshot_aggregate(vol0,total)Returns total aggregate snapshot space on vol0 
  Value returned is Longnetapp_spare(diskUid, diskKey)return type: CharacterType: NetApp CheckValue returned is stat dependent Returns the latest spare disk stat value for the specified diskUid and diskKeyParameters:diskUid = UID of the diskdiskKey = name of the stat  Example:netapp_spare(5000CCA0:0996A808:00000000:00000000:00000000:00000000:00000000:00000000:00000000:00000000,rpm)Returns the rpm for the specified spare disk 
netapp_volume(volumeName, volumeKey)return type: CharacterType: NetApp CheckValue returned is stat dependent Returns the latest volume stat value for the specified volumeName and volumeKeyParameters:volumeName = name of the volumevolumeKey = name of the stat  Example:netapp_volume(vol0,size-used)Returns the number of bytes used on vol0 
Percentile
Operation Description Examples
percentile_attribute(operation,days_in_period,percentile)return type: Numeric (float)Percentile resultType: Percentile Value of other attributes at specified percentileParameters:Example: percentile_attribute("netapp_volume(vol0,size-used)",30,95)   
SMIS
Operation Description Examples
smis_disk_metric(objectpath, property)return type: CharacterType: SMISValue returned is property dependent Returns the current value of the specified SMIS metricParameters:objectPath = SMI-S path to retrieve the Block Storage Statistical Data instance for the attributeproperty = The name of the property  Example: smis_disk_metric(10.83.26.34/root/emc:Symm_BlockStorageStatisticalData.InstanceID="SYMMETRIX-+-000198701245-+-Disk-+-0",TotalIOs)Returns the toal number of IO operations for the specified instance 
smis_system_metric(objectpath, property)return type: CharacterType: SMISValue returned is property dependent Returns the current value of the specified SMIS metricParameters:objectPath = SMI-S path to retrieve the Block Storage Statistical Data instance for the attributeproperty = The name of the property  Example: smis_system_metric(10.83.26.34/root/emc:Symm_BlockStorageStatisticalData.InstanceID="SYMMETRIX-+-000198701245-+-Array-+-0",EMCTotalHitIOs)Returns the number of hit IO's for the specified instance 
smis_volume_metric(objectpath, property)return type: CharacterType: SMISValue returned is property dependent Returns the current value of the specified SMIS metricParameters:objectPath = SMI-S path to retrieve the Block Storage Statistical Data instance for the attributeproperty = The name of the property  Example: smis_volume_metric(10.83.26.34/root/emc:Symm_BlockStorageStatisticalData.InstanceID="SYMMETRIX-+-000198701245-+-Volume-+-00000",ReadIOs)Returns the total number of read IO's for the specified instance 


REST API

FireScope SPM includes a REST-based API that allows you to automatically configure key SPM components, such as Configuration Items (CI), Policies, Notifications, etc. The intent of this API is to provide customers with in-house applications for asset management, CMDB, or automation to interface with SPM and streamline the management of SPM.

Before You Begin Before you use this interface, make sure you have:* A working SPM instance and Account

  • A FireScope Administrator user in the SPM Account
    • It's recommended to create a separate REST-only user
    • These credentials will be passed via Basic Authentication on the REST calls
  • Experience creating REST-based JSON for use with the SPM API
  • Access to TCP port 38050 on the SPM application nodes (or VIP if in load-balanced mode)


If you are new to using REST APIs or building applications with Web Services, see our sample guide.

You can use the REST API for the following high-level functions:* Creating, updating, deleting, and retrieving information for:

    • CIs
    • Service Groups
    • Logical Groups
    • Notifications
  • Linking CIs to Logical Groups
  • Linking CIs and Logical Groups to Service Groups
  • Applying Blueprints to CIs


The API consists of REST-based Web Services that expect a JSON-formatted object to be posted to the interface. For more information on JSON, see http://www.json.org/. Following is an example of a generic JSON-formatted request for SPM:

JSON Formatting Example

{

 "account_id" : "firescope",

 "edge_device_id" : "Edge 1",

 "available" : 0,

 "ciname" : "REST Configuration Item 1",

 "ip" : "0.0.0.0",

 "port" : 8042,

 "status" : 0,

 "useip" : 1,

 "logicalgroup" : ["REST Logical Group 1"],

 "ci_bp" : [],

 "ci_profile" : {

   "contact" : "John Smith",

   "devicetype" : "Server",

   "location" : "Dallas Data Center",

   "notes" : "Ordering server",

   "os" : "Linux Mint 14",

   "serialno" : "0U812",

   "software" : "Tomcat"

  }

}

Using the Firefox RESTClient Plugin

If you are new to REST or not skilled in writing utilities around Web Services, you can experiment with FireScope SPM API interfaces. Installing and using the Firefox RESTClient Plugin is one way to write utilities for the REST API. 

Before You Begin

Before you begin using the Firefox RESTClient Plugin, make sure you have:* The Firefox RESTClient Plugin

  • A working SPM instance and Account
  • An Admin level User in the SPM Account
  • At least 1 Edge Device defined for the SPM Account
  • A sample JSON payload


Configuring the RESTClient Once you have installed RESTClient in Firefox, you must configure the authentication as required for REST calls. To configure the RESTClient:# At the top of your web browser, click the RESTClient icon  Rest API Page.png-748x232.png . The RESTClient tool page will be displayed.Note:  If you do not see the RESTClient icon, you can click Tools > RESTClient instead. Rest API Authentication.png-705x345.png

  1. Click Authentication > Basic Authentication. The Basic Authorization window will be displayed.

Rest API Request Header.png-592x285.png

  1. Enter the Username and Password for your SPM Admin account.
  2. Click on Okay.
  3. Click on Headers > Custom Header. The Request Header window will be displayed.

Rest API Response.png-683x396.png

  1. Enter the Name and Value.
  2. Click on the Okay button.
  3. Configure the Request for the operation you want to use.


Note:* To create or update an element in SPM, use the POST method to the target Web Service URL. To delete, use the DELETE method against the associated URL.

  • To view the Response from the Web Service, click View > Response. The Response section will be displayed below the Request section.

" "

Retrieving an Element's Schema

SPM provides the ability to query and retrieve the schema for any of the elements in the following list. Using the GET command, you can retrieve the properties for any given element and find what is required for a payload, which is especially useful for developers who interface with the API.

To retrieve an element schema, send the following information in a GET request:

http://<ipaddress>:38050/web_services/[type]?account=[Account name]&schema=true

For [type], use one of the following values for the schema type you want to retrieve.


Schema Type Required Value
Attribute attribute
Attribute History attribute_history_query
Blueprint bp_sync_job
CI ci
Event Definition eventdef
Visual Control (Graph) graphs
Logical Group logicalgroup
Notification notifications
Service Group servicegroup
Users users


Query Parameter Description


Parameter Description Type Required
account Name of the SPM Account. String Yes

Applying a Blueprint to Configuration Items

The REST API allows you to apply a Blueprint to Configuration Items (CIs) in FireScope SPM.To apply a Blueprint to one or more CIs, POST a JSON document with the appropriate information to the following URL:

http://[IP address]:38050/web_services/bp_sync_job

Note: Don't forget to change the IP address

Note: Un-linking Blueprint will have a cascading delete effect. All elements that are based on this linkage will be affected (for e.g.  Attributes, Event Definition, Policies, AEDs, Dashboards etc. Re-linking the Blueprint will not retrieve the data.)

Use the following example as a guide.

{

  "account_id" : "firescope",

  "blueprint_id" : "Availability_t",

  "sync_type" : 0,

  "instance_id" : [

    {"edge_device" : "Edge 1", "ci" : "REST Configuration Item 1"},

    {"edge_device" : "Edge 1", "ci" : "REST Configuration Item 2"}

  ]

}

Property Descriptions


Property Description Type Default Value Required
account_id The name of the target SPM Account. String   Yes
blueprint_id The name of the Blueprint. String   Yes
sync_type 0 - Links the Blueprint to CIs, creating or updating attributes, etc. as necessary.1 - Unlinks the Blueprint from the CIs. Number 0 Yes
instance_id Array of CI elements to link to the Blueprint. Leave empty to re-sync all currently linked CIs. Object[] [] No

Aggregate Event Definitions

The REST API allows you to work with Aggregate Event Definitions (AEDs) in FireScope SPM using a REST client in lieu of the SPM user interface. Specifically, you can:* Retrieve AED Details


Retrieve AED Details

To retrieve the current information about an AED in SPM, send unique query parameters in a GET request to the following URL:

http://[SPM IP address]:38050/web_services/aed?account=[Account name]&logicalgroup=[Logical Group name]&fname=[AED name]

Example:

http://localhost:38050/web_services/aed?account=firescope&logicalgroup=web_servers_logicalgroup&name=web_servers_unavailable

A JSON response will be returned similar in structure to the payload for creating an AED.

Query Parameter Descriptions


Property  Description Type Required
account Name of the SPM Account. String Yes
logicalgroup Name of the Logical Group String Yes
name Name of the AED. String Yes


Retrieve the AED Schema

To retrieve the full SPM schema for AEDs, send the Account name in a GET request to the following URL:http://[SPM IP address]:38050/web_services/aed?account=[Account name]&schema=true

Create or Update an AED

To create an AED, send a POST operation with a JSON document to the following URL:http://[SPM IP address]:38050/web_services/aed

Note: Don't forget to change the domain name (localhost) to match your environment and data.

You can use the following example as a guide, but note that it may not include all optional properties.

{

  "account_id" : "firescope",

  "adbuilder" : "@A&@B",

  "description" : "web_servers_unavailable",

  "eventdefmembers" : [{

      "builder_symbol" : "@A",

      "memberid" : {"edge_device" : "edge1", "ci" : "ci1", "eventdef" : "ed1"}

    },{

      "builder_symbol" : "@B",

      "memberid" : {"edge_device" : "edge1", "ci" : "ci1", "eventdef" : "ed2"}

    }

  ],

  "fs_eventdef_concat" : "&",

  "fs_eventdef_type" : {

    "perf" : 1

  },

  "fs_groupid" : "web_servers_logicalgroup",

  "modetype" : 0,

  "priority" : 3,

  "status" : 0

}

Property Descriptions


Property Description Type Default Value Required
account_id Name of the SPM account. String   Yes
adbuilder The list of member variables (@A, @B, etc.) and the logic needed to perform this evaluation.Examples:@A|@B    ((@A|@B)&@C)    ((@A&@B)|(@C&@D)) String   Yes
comments Comments or other notes for the AED. String   No
custom_1 Use these custom fields to store and assign additional information that will be associated with any generated events. The custom fields are accessible for notifications as macros {EVENT.CUSTOM_1} ... {EVENT.CUSTOM_5}. String   No
custom_2 String   No
custom_3 String   No
custom_4 String   No
custom_5 String   No
description Unique name of the AED. String   Yes
eventdefmembers Nested array of member EDs that make up this AED.


Property Description Type Default Value Required
builder_symbol Corresponding symbol (e.g., @A) from the adbuilder. String   Yes
memberid A complex foreign key to an ED. Object[]   Yes
Object[]   Yes
fs_eventdef_concat For simple mode, the AND (&) or OR (|) operator for evaluation. String & Yes, when modetype=0
fs_eventdef_type Classify how identified events will impact IT operations. At least one of the following flags must be enabled: avail, bus, perf, sec.


Property Description Type Default Value Required
avail Availability: Indicates that either this asset is offline or users will not be able to perform tasks. Boolean FALSE Yes
bus Business flag: Indicates this event directly impacts key business processes or the business will lose money if the event occurs. Boolean FALSE Yes
perf Performance flag: Indicates end users will experience slowness or degraded service as a result of this event. Boolean FALSE Yes
sec Security flag: Indicates sensitive data may be compromised or unauthorized actions have been identified. Boolean FALSE Yes
Object   Yes
fs_groupid Name of the associated Logical Group. String   Yes
modetype 0 = Simple1 = Advanced Number 0 No
priority The severity for events generated by this definition. Severity is used in dashboards, reports and notifications. The severity level of events can determine if a notification is create and/or sent to users or not.0 = Not Classified1 = Information2 = Average3 = Warning4 = High5 = Major Number 0 Yes
resetinterval The interval in seconds after which a failed AED should be automatically reset. Number   No
status 0 = Enabled1 = Disabled Number 0 Yes
url Link to a useful KB article or process document that should be followed if this event occurs. String   No
value The read only result of the last calculation of the aggregate event definition.

0 = OK1 = Failed

Number 0 No


 Delete an AED

To delete an AED, send an HTTP DELETE request with the same query parameters as the GET request.See the Retrieve for the URL format and query parameter descriptions.

Attributes

The REST API allows you to work with Attributes in FireScope SPM.* Retrieve


Retrieve

To retrieve the current information about an Attribute as a JSON document, send a GET request with the following URL format:

http://localhost:38050/web_services/attribute?account=firescope&edge_device=edge1&ci=10.0.2.15&name=ping

Note: Don't forget to change the (localhost) and query parameter values (account, edge_device, ci, and name) to match your environment and data.

Query Parameter Descriptions


Property  Description Type Required
account Name of the SPM Account. String Yes
edge_device Name of the Edge Device. String Yes
ci Name of the CI. String Yes
name Name of the Attribute. String Yes


Search

Searching provides for the ability to return multiple results in a single call using various filter criteria. To accomplish this, a GET request is sent with a parameter search=true. Every other field besides account is optional and is used to further filter the results. Pagination is mandatory and accomplished using the page and size parameters. The JSON response will wrap the result list and also display the page and the size. The size in the response represents the number of results actually returned, not the size in the request. The response does not contain a count of the total number of pages or the total number of records for performance reasons. The client is expected to keep querying, increasing the page each time, until the result size is less than the requested size, indicating no more results.

http://localhost:38050/web_services/attribute?search=true&account=firescope&edge_device=edge1&ci=10.0.2.15&name=substring&page=0&size=100

Note: Don't forget to change the (localhost) and query parameter values (account, edge_device, ci, and name) to match your environment and data.

Search Parameter Descriptions


Parameter Description Type Default Required
account Name of the SPM Account. String   Yes
search Enable searching by setting to true. Setting to false will revert functionality to retrieving a single result. Boolean FALSE Yes
page Indicates which result set is being returned starting at zero and increasing until there are no more results Number 0 Yes
size Indicates how many results are returned in a single page. A max of 250 results is supported. Number 100 Yes
name Filter the results by a case-insensitive substring search of the name field. String   No
edge_device Filter the results by an Edge Device's exact name. String   No
ci Filter the results by a Configuration Item's exact name. String   No

 

Example Search Results Response

{

   "account_id": "firescope",

   "entity": "attribute",

   "page": 0,

   "size": 2,

   "results": [

      {

         "account_id": "firescope",

         "edge_device_id": "edge2",

         "description": "Host ping",

         "ciid": "10.0.6.11",

         "operation": "ping"

      },

      {

         "account_id": "firescope",

         "edge_device_id": "edge1",

         "description": "Host ping",

         "ciid": "10.0.2.15",

         "operation": "ping"

      }

   ]

}

Create or Update

To create an Attribute, send a POST operation with a JSON document to the following URL:

           http://[SPM IP address]:38050/web_services/attribute

Note: Don't forget to change the (SPM IP address

Use the following example as a guide.

{

   "account_id":"firescope",

   "edge_device_id":"Edge 1",

   "asset_name":null,

   "ciid":"REST Created 1",

   "delay":60,

   "delta":0,

   "description":"test PING 1",

   "formula":"1",

   "logtimefmt":"",

   "metadata":"STATUS,,,PING,53177150e4b011a3f27f25d2,test PING 1",

   "multiplier":0,

   "operation":"ping",

   "snmp_oid":"interfaces.ifTable.ifEntry.ifInOctets.1",

   "snmp_port":161,

   "status":0,

   "translationid":null,

   "trapper_hosts":"",

   "type":3,

   "units":"",

   "value_type":3,

   "fs_attribute_type":{

      "attribute_major":"80",

      "attribute_max":"1",

      "attribute_warning":"60",

      "avail":0,

      "kpi":0,

      "def_graph":"none",

      "perf":1,

      "sec":0

   },

   "attributeset":["Ping attributes"]

}

 

 Property Descriptions

 


Property Description Type DefaultValue Required
account_id Name of the SPM Account. String   Yes
edge_device_id Name of the Edge Device. String   Yes
asset_name A name used to group related attributes together that belong to the same asset. String   No
ciid Name of the associated CI. String   Yes
delay How often (in seconds) SPM should check values. Number 60 Yes
delta Option to either collect the raw value or its rate of change over time.Possible values:0 = As Is

1 = Speed per Second

2 = Simple Change

Number 0 Yes
description Attribute description, which will be listed on the Attributes page. String   Yes
formula The actual multiplier value you want to use. E.g. 1024 to convert bytes to kilobytes. String 1 No
lastvalue The attribute's last reported value. Read-only. String   No
logtimefmt   String   No
metadata Options for using metadata, in the following format: [Type],[SubType],[Vendor],[Detail],[Index],[Label] String   No
multiplier Controls whether to use a multiplier or not. See the formula field for the actual multiplier value.Possible values:0 = Do Not Use1 = Use Number 0 No
operation Operation used for gathering data. You must enter an Operation corresponds to the Type.If you are using FireScope Agent, make sure the Operation you use is defined in the FireScope Agent's configuration. For SNMP, you must enter the credentials required to access the SNMP connection (port 161) of the device. String   Yes
prevvalue The attribute's previous value that occurred before the value in the 'lastvalue' field. Read-only. String   No
snmp_oid Object Identifier (OID) required to access the SNMP connection and gather data for this Attribute. String   No
snmp_port Port for the SNMP connection. Number 161 No
status Whether the attribute is active or not.Possible values:0 = Active1 = Disabled Number 0 Yes
translationid Name of the translation being used String   No
trapper_hosts   String   No
type The type of the attribute, which help denotes the source of the attribute.

Possible Values:0 = FireScope1 = SNMP V12 = Trapper3 = Simple4 = SNMP V25 = Internal6 = SNMP V37 = FireScope Active8 = Grouped Attribute10 = External11 = FireScope WMI12 = Syslog13 = ESB JDBC14 = ESB FTP15 = ESB HTTP16 = ESB HTTPS17 = ESB WSDL18 = ESB File19 = ESB SOAP20 = ESB Multicast21 = ESB POP322 = ESB SMTP23 = ESB TCP24 = ESB UDP25 = VM Host26 = VM Guest27 = VM VC28 = LDAP Check29 = Calculated Attribute31 = Percentile Attribute32 = Delegate Syslog33 = Delegate SNMP V134 = Delegate SNMP Trap35 = Delegate SNMP V236 = Delegate SNMP V337 = Service Availability38 = NetApp39 = Cisco UCS40 = App Server Stat41 = SMongo Server Stat42 = SWeb Server Stat43 = NetApp DFM44 = Attribute Incoming45 = Attribute Incoming JSON46 = Infoblox47 = Days to target48 = Amazon AWS49 = Edge Server stat50 = SMIS

Number 0 Yes
units Unit type appended to the end of all values for this Attribute whenever they are displayed. For example, % for processor utilization, B (bytes) for file system size, and Bps (bytes per second) for network performance. String   No
value_type


Value Type Description
0 Float Double e.g. 3.14
1 String Character (max size 1024) e.g. "Hello world"
2 Log Actual lines from a log attribute / Windows Event log attribute (Max size 65535)
3 Long Integer e.g. 2147483647
4 Text Very large "String" equivalent of a CLOB (Max size 65535)
9 JSON  (Max size 4096)e.g. {"first_name":"Bryan","company_name":"FireScope"}
Number 0 Yes
fs_attribute_type Attribute type information:


Property Description Type DefaultValue Required
attribute_major   String 80 No
attribute_max   String 1 No
attribute_warning   String 60 No
avail Classifies whether this attribute impacts the availability of this CI. Number 0 Yes
kpi Enable some summary views of CIs to display the attributes labeled as a Key Performance Indicator Number 0 Yes
def_graph  Show/hide possible values String none Yes
perf Classifies whether this attribute impacts the performance of this CI. Number 1 Yes
sec Classifies whether this attribute impacts the security of this CI. Number 0 Yes
Object   Yes
attributeset Names of the Attribute Set(s) this Attribute is associated with. String[]   No


Delete

To delete an Attribute, send an HTTP DELETE request with the same query parameters as the GET request.See the Retrieve for the URL format and query parameter descriptions.

Note: Deleting an Attribute will have a cascading delete effect. All elements that are based on this Attribute will be effected (for e.g.  Dashboards, AEDs, ED, Policies etc. Data collected by this Attribute will be lost for good.)

CI Relationships

The REST API allows you to work with Configuration Items (CI) Relationships in FireScope SPM using a REST client in lieu of the SPM user interface.* Retrieve


Retrieve

Not implemented.

 Search

Searching provides for the ability to return multiple results in a single call using various filter criteria. To accomplish this, a GET request is sent with a parameter search=true. Every other field besides account is optional and is used to further filter the results. Pagination is mandatory and accomplished using the page and size parameters. The JSON response will wrap the result list and also display the page and the size. The size in the response represents the number of results actually returned, not the size in the request. The response does not contain a count of the total number of pages or the total number of records for performance reasons. The client is expected to keep querying, increasing the page each time, until the result size is less than the requested size, indicating no more results.

http://localhost:38050/web_services/ci_relationship?search=true&account=firescope&servicegroup=Ordering&page=0&size=10

Note: Don't forget to change the domain name (localhost) and query parameter (search, account, servicegroup, page and size ) values to match your environment and data.

Search Parameter Descriptions


Parameter Description Type Default Required
account Name of the SPM Account. String   Yes
search Enable searching by setting to true. Setting to false will revert functionality to retrieving a single result. Boolean FALSE Yes
page Indicates which result set is being returned starting at zero and increasing until there are no more results Number 0 Yes
size Indicates how many results are returned in a single page. A max of 250 results is supported. Number 100 Yes
servicegroup Filter the results by a Service Group's exact name. String   No

 

Example Search Response

{

   "account_id": "firescope",

   "entity": "ci_relationship",

   "page": 0,

   "size": 2,

   "results": [

      {

         "account_id": "firescope",

          "ci_relationship_category_id": "Network",

          "ci_relationship_type_id": "contains",

         "pending_delete": True,

          "port": 19234,

          "protocol_name": "",

          "protocol_type": "TCP",

          "servicegroupid": "Ordering",

         "source_ci": "esx1",

          "status": 1,

         "target_ci": "firescope.com"

      }, {

         "account_id": "firescope",

          "ci_relationship_category_id": "Application",

          "ci_relationship_type_id": "related",

         "pending_delete": False,

          "port": 80,

          "protocol_name": "http",

          "protocol_type": "TCP",

          "servicegroupid": "Ordering",

         "source_ci": "10.0.22.10",

          "status": 0,

         "target_ci": "firescope.com"

      }

   ]

}

Create or Update

Not implemented

Property Descriptions

The following table provides information about all required and optional properties available for a CI Relationship.


Property Description Type Default Value Required
account_id Name of the SPM Account. String   Yes
ci_relationship_category_id Name of the category this relationship falls into:* Application
  • Network
  • Storage
  • Virtual


String   Yes
ci_relationship_type_id The type of relationship indicates whether it is a parent/child relation or just a normal relationship.* contains
  • related


String   Yes
pending_delete Whether the relationship has been marked for deletion and awaiting user approval. Boolean False Yes
port The port associated with this relationship. Usually this indicates the target server's listening port. Number   Yes
protocol_name The application protocol name associated with this traffic. For example, http, ldap, etc. String   No
protocol_type The transport layer protocol. Either UDP or TCP. String   Yes
servicegroupid Name of the Service Group associated with the CI. String   Yes
source_ci The originating CI of the relationship. Example:

{"edge_device_id" : "Datacenter East", "ci" : "10.0.0.10"}

Object   Yes
status Status of the relationship:

0 = Pending

1 = Approved

2 = Rejected

Number  0 Yes
target_ci The destination CI of the relationship. Example:

{"edge_device_id" : "Datacenter East", "ci" : "10.0.0.20"}

Object   Yes


 Delete

Not implemented

Configuration Items

 The REST API allows you to work with Configuration Items (CIs) in FireScope SPM using a REST client in lieu of the SPM user interface.* Retrieve


Retrieve

To retrieve the current information about a CI as a JSON document, send a GET request with the following URL format:

http://localhost:38050/web_services/ci?account=firescope&edge_device=edge1&name=VMware

Note: Don't forget to change the domain name (localhost) and query parameter (account, edge_device and  name) values to match your environment and data.

Query Parameter Descriptions


Parameter Description Type Required
account Name of the SPM Account. String Yes
edge_device Name of the CI's Edge Device. String Yes
name Name of the CI. String Yes


 Search

Searching provides for the ability to return multiple results in a single call using various filter criteria. To accomplish this, a GET request is sent with a parameter search=true. Every other field besides account is optional and is used to further filter the results. Pagination is mandatory and accomplished using the page and size parameters. The JSON response will wrap the result list and also display the page and the size. The size in the response represents the number of results actually returned, not the size in the request. The response does not contain a count of the total number of pages or the total number of records for performance reasons. The client is expected to keep querying, increasing the page each time, until the result size is less than the requested size, indicating no more results.

http://localhost:38050/web_services/ci?search=true&account=firescope&edge_device=edge1&name=substring&page=0&size=10

Note: Don't forget to change the domain name (localhost) and query parameter (search, account, edge_device, name, page and size ) values to match your environment and data.

Search Parameter Descriptions


Parameter Description Type Default Required
account Name of the SPM Account. String   Yes
search Enable searching by setting to true. Setting to false will revert functionality to retrieving a single result. Boolean FALSE Yes
page Indicates which result set is being returned starting at zero and increasing until there are no more results Number 0 Yes
size Indicates how many results are returned in a single page. A max of 250 results is supported. Number 100 Yes
name Filter the results by a case-insensitive substring search of the name field. String   No
edge_device Filter the results by an Edge Device's exact name. String   No
logicalgroup Filter the results by a Logical Group's exact name. String   No
servicegroup Filter the results by a Service Group's exact name. String   No

 

Example Search Response

{

   "account_id": "firescope",

   "entity": "ci",

   "page": 0,

   "size": 2,

   "results": [

      {

         "account_id": "firescope",

         "edge_device_id": "edge1",

         "ciname": "VMWare",

         "ip": "10.0.6.1"

      }, {

         "account_id": "firescope",

         "edge_device_id": "edge2",

         "ciname": "FireScope Website",

         "dns": "firescope.com",

         "useip": 0

      }

   ]

}

Create or Update

To create or update a CI, POST a JSON document with the specific CI information to the following URL:

http://localhost:38050/web_services/ci

You can use the following example as a guide, but note that it does not include all optional properties.

{

  "account_id" : "firescope",

  "edge_device_id" : "edge1",

  "ciname" : "VMWare",

  "ip" : "10.0.6.1",

  "port" : 8042,

  "status" : 0,

  "useip" : 1,

  "ci_profile" : {

    "contact" : "John Wayne",

    "devicetype" : "Server",

    "location" : "Dallas Data Center",

    "name" : "REST Configuration Item 1",

    "notes" : "This is the notes section",

    "os" : "Linux Mint 14",

    "serialno" : "0U812"

  }

}

Property Descriptions

The following table provides information about all required and optional properties available for a CI.


Property Description Type Default Value Required
account_id Name of the SPM Account. String   Yes
edge_device_id Name of the Edge Device that will collect data for this CI. String   Yes
ciname Name of the Configuration Item. String   Yes
cisco_ucs_conn_info_id Cisco UCS access credentials, which allow Attributes to connect to the Cisco device and determine data relationship. String   No
dns Fully qualified DNS name of CI. String   Yes, if useip = 0
fs_ba_eventdefid The name of the Event Definition used to indicate business availability for this CI. String   No
fs_domain Active Directory domain name. Only required if you are using WMI to collect Attribute values. String   No
fs_proxy_ciname Name of CI acting as a proxy for data collection. Only required if you are using FireScope Sentinel. String   No
infoblox_conn_info_id Name of the credentials being used to connect to Infoblox. String   No
ip IP address of the CI. String 127.0.0.1 Yes, if useip = 1
ldap_conn_info_id Name of LDAP access credentials, which allows Attributes to connect to the LDAP service. String   No
netapp_credential_id Name of NetApp ONTAP access credentials, which allows Attributes to connect to the NetApp device and determine data relationships. String   No
netapp_dfm_conn_info_id Name of NetApp DFM access credentials, which allows Attributes to connect to the NetApp device and determine data relationships. String   No
port Default port for agent communications. Number 8042 Yes
snmp_credential_id Name of SNMP access credentials, which allows Attributes to connect to the SNMP device. String   No
status Status of the CI:0 = Monitored1 = Disabled Number 0 Yes
useip Indicates if it uses an IP address:0 = DNS supplied1 = IP address supplied Number 1 Yes
vm_conn_info_id Name of existing Virtual Center Connection to allow VC Attribute collection. String   No
vm_name Virtual Center Infrastructure Client Name - used as the unique lookup to locate the associated virtual center host or guest. String   No
ci_profile CI profile information:


Property Description Type Default Value Required
contact Person of contact for CI. String   No
custom_fields A list of custom field


Property Description
Name String
Value String
Object[]   No
devicetype


Types of Assets-Possible Values
Application Server
Collection Service
Data Store Software Product
Device Storage
FireScope Template
Generic Unknown
Location VM Guest
Network VM Host
Printer VMware vCenter
Security  
String   Yes
fs_port_alias_id Name of a known port alias. String   No
hardware Description of hardware CI resides on. String   No
location Location of CI (e.g., data center, rack, row, city, etc). String   No
macaddress MAC address of CI. String   No
name Name of the CI Profile. String   No
notes Misc notes about this CI. String   No
os OS information on this device. String   No
primary stack layer
Primary type of function the CI supports in your defined service. For example, your network fileserver CIs for your CRM system should have the stack layer of STORAGE. This identifier is used throughout the application to indicate your issues.


Possible Values
0 = None 5 = Virtualization
1 = User Experience 6 = Hardware
2 = Application 7 = Network
3 = Database 8 = Storage
4 = OS 9 = Environmental
Number 4 Yes
secondary stack layer


Possible Values
0 = None 5 = Virtualization
1 = User Experience 6 = Hardware
2 = Application 7 = Network
3 = Database 8 = Storage
4 = OS 9 = Environmental
Number 0 Yes
serialno Serial number of this device. String   No
software Information on any software installed on this CI. String   No
tag Does this CI have a tag associated with it? String   No
url The URL where the CI resides, if necessary. String   No
Object   Yes
ci_storage


Property Description Type Default Value Required
filesystem The filesystem path for this storage item. Related macro [CI_STORAGE.FILESYSTEM] String   Yes
mount The mount point associated with the filesystem. String   No
multiplier This multiplier will be used as the created attribute's custom multiplier. Related macro [CI_STORAGE.MULTIPLIER] String 1 Yes
 Object[] [ ] No
ci_memory


Property Description Type Default Value Required
asset_name   String   No
description   String   No
name   String   Yes
storage_alloc_units   Number 0 No
type


Possible Values
0 = Other 5 = Floppy Disk
1 = RAM 6 = Compact Disk
2 = Virtual Memory 7 = RAM Disk
3 = Fixed Disk 8 = Flash Memory
4 = Removable Disk 9 = Network Disk
Number 1 Yes
Object[] [ ] No
ci_interface


Property Description Type Default Value Required
admin_status Possible values:1 = Up2 = Down3 = Testing Number 1 Yes
attribute_status Possible values:0 = Active1 = Disabled3 = Not Supported Number 0 Yes
description Related macro [CI_INTERFACE.DESCRIPTION] String   Yes
type   String   No
name Related macro [CI_INTERFACE.NAME] String   Yes
operational_status Possible values:1 = Up2 = Down3 = Testing4 = Unknown5 = Dormant6 = Not Present7 = Lower Layer Down Number 1 Yes
Object[] [ ] No
ci_cpu


Property Description Type Default Value Required
asset_name   String   No
description   String   No
index Related macro[CI_CPU.INDEX] Number 0 Yes
name Related macro [CI_CPU.NAME] String   Yes
speed   String   No
Object[] [ ] No
ci_bp Blueprint associated with the CI. Read only. Use the Blueprint Web Service to link an existing blueprint to this CI. String[] [ ] No
ci_snmp_table See schema API call for payload structure. Object   No
ci_vm_discovery See schema API call for payload structure Object   No
logicalgroup Name of the Logical Group associated with the CI. String[] [ ] No
servicegroup Name of the Service Group associated with the CI. String[] [ ] No


 Delete

To delete a CI, send an HTTP DELETE request with the same query parameters as the GET request.See the Retrieve for the URL format and query parameter descriptions.

Clusters

The REST API allows you to work with Clusters in FireScope SPM using a REST client in lieu of the SPM user interface.
Retrieve
Schema
Create or Update
Delete

Retrieve

To retrieve the current information about a Cluster in SPM, send unique query parameters in a GET request to the following URL:
http://localhost:38050/web_services/cluster?account=firescope&name=WebServers
Note: Don't forget to change the domain name (localhost) and query parameter values (account and name) to match your environment and data.
A JSON response will be returned similar in structure to the payload for creation.
Query Parameter Descriptions


Parameter Description Type Required
account Name of the SPM Account. String Yes
name Name of the Cluster. String Yes


Schema

To retrieve the full SPM schema for a Cluster, send the Account name with the schema parameter set to true in a GET request to the following URL:
http://[SPM IP address]:38050/web_services/cluster?account=[Account name]&schema=true

Create or Update

To create or update an Cluster, POST a JSON document with the specific Cluster information to the following URL:
http://[SPM IP address]:38050/web_services/cluster
You can use the following example as a guide, but note that it does not include all optional properties.
{"account_id": "firescope","ciid": null,"cluster_type": 3,"cluster_member": [{"ciid": null,"dns": "web1.company.com","ip": "10.0.22.158","port": 80},{"ciid": null,"dns": "web2.company.com","ip": "10.0.22.159","port": 80}, {"ciid": null,"dns": "web3.company.com","ip": "10.0.22.160","port": 80}],"dns": "web.company.com","ip": "10.0.22.157","load_balancer_ciid": null,"logicalgroupid": null,"name": "WEB VIP","port": 80,"status": 0}
Property Descriptions
The following table provides information about all required and optional properties available for a Cluster


Property Description Type Default Value Required
account_id Name of the SPM Account. String Yes
name Name of the Cluster. String Yes
ciid The CI associated with the Cluster.

Example: {"edge_device" : "Edge 1", "ci" : "WEB VIP"}

Object No
cluster_type A description for the purpose of this Cluster.

Possible values: 0=NONE, 1=GENERIC, 2=HIGH_AVAILABILITY, 3=LOAD_BALANCER

Number 3 Yes
dns The DNS of the Cluster. String No
ip The IP of the Cluster. String Yes
load_balancer_ciid The CI representing the load balancer for which the Cluster belongs. Specifying this field will cause all CIs that are created as the result of approving the Cluster to be created in the same Edge as the Load Balancer.

Example: {"edge_device" : "Edge 1", "ci" : "MyLB"}

Object No
logicalgroupid The LG representing this Cluster. Typically, leave this null when creating the cluster with status = 0 and then when the status is changed to 1, the LG is automatically created and assigned to this field. String No
port The port of the Cluster. Number No
status The status of the Cluster. Create the cluster using status = 0 and do not specify any of the ciid or logicalgroupid fields. Then when the cluster is updated with status = 1, all CIs and LGs will be created automatically and these fields will be populated. These CIs will be created in the same Edge as the load_balancer_ciid if specified. It load_balancer_ciid was not specified, an Edge will be chosen for you.

Possible values: 0=PENDING, 1=APPROVED

Number 0 Yes
cluster_member These fields specify the members of the Cluster: Object[] Yes
Property Description Type Default Value Required
ciid The CI associated with this cluster member.

Example: {"edge_device" : "Edge 1", "ci" : "WEB1"}

Object No
dns The DNS of the cluster member. String No
ip The IP of the cluster member. String Yes
port The port of the cluster member. Number No

Delete

To delete a Cluster send an HTTP DELETE request with the same query parameters as the GET request.
See the Retrieve for the URL format and query parameter descriptions.

Edge Devices

The REST API allows you to retrieve Edge Devices in FireScope SPM.* Retrieve


Retrieve

To retrieve the current information about an Edge Device as a JSON document, send a GET request with the following URL format:http://localhost:38050/web_services/edge_device?account=firescope&name=10.0.0.3

Note: Don't forget to change the domain name (localhost) and query parameter values (account, and name) to match your environment and data.

 Query Parameter Descriptions


Parameter Description Type Required
account Name of account. String Yes
name Name of the Edge Device String Yes


Search

Searching provides for the ability to return multiple results in a single call using various filter criteria. To accomplish this, a GET request is sent with a parameter search=true. Every other field besides account is optional and is used to further filter the results. Pagination is mandatory and accomplished using the page and size parameters. The JSON response will wrap the result list and also display the page and the size. The size in the response represents the number of results actually returned, not the size in the request. The response does not contain a count of the total number of pages or the total number of records for performance reasons. The client is expected to keep querying, increasing the page each time, until the result size is less than the requested size, indicating no more results.

http://localhost:38050/web_services/edge_device?search=true&account=firescope&name=substring&page=0&size=100

Note: Don't forget to change the domain name (localhost) and query parameter values (account, name, page and size) to match your environment and data.

Search Parameter Descriptions


Parameter Description Type Default Required
account Name of the SPM Account. String   Yes
search Enable searching by setting to true. Setting to false will revert functionality to retrieving a single result. Boolean FALSE Yes
page Indicates which result set is being returned starting at zero and increasing until there are no more results Number 0 Yes
size Indicates how many results are returned in a single page. A max of 250 results is supported. Number 100 Yes
name Filter the results by a case-insensitive substring search of the name field. String   No

 

Example Search Response

 

{

   "account_id": "firescope",

   "entity": "edge_device",

   "page": 0,

   "size": 1,

   "results": [{      "account_id" : "firescope",      "description" : "Dallas Datacenter",      "global_properties" : {         "cloud_ip" : "10.0.0.4",         "edge_services_http_ports" : "18050,18051",         "edge_services_https_ports" : "18060,18061",         "edge_services_jmx_ports" : "18040,18041",         "ui_services_http_ports" : "28050,28051",         "ui_services_https_ports" : "28060,28061",         "ui_services_jmx_ports" : "28040,28041"      },      "ip" : "10.0.0.3",      "name" : "Dallas",      "protocol" : "http",      "status" : 1,      "timezone" : "America/Chicago"   }]

}

 

Property Descriptions


Property Description Type Default Value Required
account_id Name of the SPM Account. String   Yes
description A description of the Edge device. String   Yes
ip The IP address where the Edge Device resides String   Yes
name Name of the SPM Edge Device String   Yes
global_properties List of properties that the Edge Device uses.


Property Description Type Default Value Required
cloud_ip   String   No
edge_services_https_ports   String   No
edge_services_http_ports   String   No
edge_services_jmx_ports   String   No
ui_services_https_ports   String   No
ui_services_http_ports   String   No
ui_services_jmx_ports   String   No
Object   No
protocol The protocol the Edge Device uses to communicate with the SPM application server. Only http and https currently supported. String   Yes
status Indicates whether the Edge Device is enabled or not.0 = Disabled1 = Enabled Number 1 Yes
timezone The configured timezone that the Edge Device is running in. String    


Create or Update

Creating and updating an Edge Device is not supported.

Delete

Deletion of an Edge Device is not supported.

ESB Transports

 The REST API allows you to work with  Enterprise Service Bus (ESB) Transports in FireScope SPM using a REST client in lieu of the SPM user interface.* Retrieve


Retrieve

To retrieve the current information about a ESB Transport in SPM, send unique query parameters in a GET request to the following URL:

http://localhost:38050/web_services/esb_transport?account=firescope&edge_device=edge1&name=ESB1

Note: Don't forget to change the domain name (localhost) and query parameter values (account, edge_device, and name) to match your environment and data.

A JSON response will be returned similar in structure to the payload for creation.

Query Parameter Descriptions


Parameter Description Type Required
account Name of the SPM Account. String Yes
edge_device Name of the ESB Transport's Edge Device. String Yes
name Name of the ESB Transport. String Yes

 

Schema

To retrieve the full SPM schema for ESB Transport, send the Account name with the schema parameter set to true in a GET request to the following URL:

http://[SPM IP address]:38050/web_services/esb_transport?account=[Account name]&schema=true

Create or Update

To create or update an ESB Transport, POST a JSON document with the specific ESB Transport information to the following URL:

http://[SPM IP address]:38050/web_services/esb_transport

You can use the following example as a guide, but note that it does not include all optional properties.

{

  "account_id" : "firescope",

  "edge_device_id" : "edge1",

  "name" : "esb1",

  "esb_transport_group" : [ "group1" ],

  "esb_transport_attribute" : [{

    "name" : "quantity",

    "multiplier" : "1",

    "value_type" : 3

 }],

  "esb_transport_client_ci" : [{

    "ciid" : {"ci" : "ci1"},

    "client_ci_uid" : "10.0.0.10"

  }],

  "esb_transport_type" : {

    "dbname" : "cmdb",

    "dbtype" : 1,

    "ip" : "10.0.0.1",

    "password" : "secret",

    "port" : 3306,

    "query" : "select ip, quantity from orders limit 5;",

    "username" : "dbuser",

    "unique_col" : "ip",

    "use_ciname" : false

  }

}

Property DescriptionsThe following table provides information about all required and optional properties available for an ESB Transport.


Property Description Type Default Value Required
account_id Name of the SPM Account. String   Yes
edge_device_id Name of the Edge Device that will process this ESB Transport. String   Yes
name Name of the ESB Transport. String   Yes
ciid The CI blueprint internally created by and managed by this ESB Transport. Read only. String   No
delay Defines how often in seconds FireScope should poll this data source for new data. Number 60 Yes
description An optional description of this ESB. String   No
errormsg Read only field populated with any error that may occur in trying to collect the ESB data. String   No
esb_transport_attribute A List of attributes that need to be created.


Property Description Type Default Value Required
delta Option to either collect the raw value or its rate of change over time.0 = As Is1 = Speed per Second2 = Simple Change Number 0 Yes
multiplier Used to multiply the collected value to convert it into a more useful form (e.g. 1024 to convert bytes into kilobytes). String "1" Yes
name The attribute name. This should match a column name from the query. String   Yes
units Unit type appended to the end of all values for this Attribute whenever they are displayed. String   No
value_type The underlying data type of the value being collected.0 = Float1 = String2 = Log3 = Long4 = Text9 = JSON      
Object[]   Yes
esb_transport_client_ci Contains a list of mappings of external IDs to Configuration Items. Required if use_ciname is false.


Property Description Type Default Value Required
ciid The CI to map to. Object   Yes
client_ci_uid The expected value from the unique_col field returned from the query that can be used to map it to the CI. String   Yes
Object[]   Conditional
esb_transport_group Associate this ESB Transport with existing ESB Transport Groups. Transport Groups are logical containers for your ESB transports, which make them easier to find and manage. String[]   No
esb_transport_type Describes the particular transport type being used by this ESB. Since only JDBC transport is supported via REST, this provides the database connection information.


Property Description Type Default Value Required
dbname The database name to query. String   Yes
dbschema The database schema String   No
dbtype The type of database to connect to:1 = MYSQL2 = ORACLE3 = MSSQL4 = SYBASE5 = DB2 Number 1 Yes
ip The IP or hostname the database is running on. String   Yes
ntm_domain   String   No
password The password of the user connecting to the database. This will be encrypted before being saved. String   Yes
port The database port to use. Number   Yes
query The database query to run on the remote database. String   Yes
unique_col The unique column from the query that can be used to identify rows and map them to CIs. String   Yes
username The database user String   Yes
use_ciname If set to false, automatically links the blueprint created by the ESB to all the CIs identified in the esb_transport_client_ci mappings. Additionally, the unique_col will be used to lookup which CI the collected attribute belongs to.If set to true, the client will have to manually apply the ESB created blueprint to the CI's it wants to generate attributes for. It is assumed that the unique_col will already contain the correct CI name to map to. Boolean FALSE Yes
Object   Yes
rows_processed Read only field with the results of the query processed. Number 0 No
rows_retrieved Read only field with the number of rows retrieved by the query. Number 0 No
status Whether the ESB Transport is enabled or not.0 = DISABLED1 = ENABLED Number 1 Yes


 Delete

To delete an ESB Transport, send an HTTP DELETE request with the same query parameters as the GET request. See the Retrieve for the URL format and query parameter descriptions.

Event Definitions

The REST API allows you to work with Event Definitions (EDs) in FireScope SPM using a REST client in lieu of the SPM user interface.* Retrieve


Retrieve

To retrieve the current information about an ED as a JSON document, send a GET request with the following URL format:

http://localhost:38050/web_services/eventdef?account=firescope&edge_device=edge1&ci=VMware&name=Verify_Ping

Note: Don't forget to change the domain name (localhost) and query parameter values (account, edge_device, ci, and name) to match your environment and data.

Query Parameter Descriptions


Property  Description Type Required
account Name of the SPM Account. String Yes
edge_device Name of the Edge Device. String Yes
ci Name of the CI. String Yes
name Name of the ED. String Yes


Search

Searching provides for the ability to return multiple results in a single call using various filter criteria. To accomplish this, a GET request is sent with a parameter search=true. Every other field besides account is optional and is used to further filter the results. Pagination is mandatory and accomplished using the page and size parameters. The JSON response will wrap the result list and also display the page and the size. The size in the response represents the number of results actually returned, not the size in the request. The response does not contain a count of the total number of pages or the total number of records for performance reasons. The client is expected to keep querying, increasing the page each time, until the result size is less than the requested size, indicating no more results.

 http://localhost:38050/web_services/eventdef?search=true&account=firescope&edge_device=edge1&ci=VMWare&name=substring&page=0&size=100

Note: Don't forget to change the domain name (localhost) and query parameter values (account, edge_device, ci, name, page and size) to match your environment and data.

Search Parameter Descriptions


Parameter Description Type Default Required
account Name of the SPM Account. String   Yes
search Enable searching by setting to true. Setting to false will revert functionality to retrieving a single result. Boolean FALSE Yes
page Indicates which result set is being returned starting at zero and increasing until there are no more results Number 0 Yes
size Indicates how many results are returned in a single page. A max of 250 results is supported. Number 100 Yes
name Filter the results by a case-insensitive substring search of the name field. String   No
edge_device Filter the results by an Edge Device's exact name. String   No
ci Filter the results by a ConfigurationItem's exact name. String   No

{

   "account_id": "firescope",

   "entity": "eventdef",

   "page": 0,

   "size": 2,

   "results": [

      {

         "account_id": "firescope",

         "criteria": "(@A > 3)",

         "description": "Verify Ping",

         "evaluations": [{

            "builder_symbol": "@A",

            "attributeid": "ping",

            "evaluation": "count_of",

            "parameter": "120,0"

         }],

         "eventdefs_cis": [{ "edge_device": "edge2", "ci": "10.0.0.5" }]

      }, {

         "account_id": "firescope",

         "criteria": "(@A > 3)",

         "description": "Verify Ping",

         "evaluations": [{

            "builder_symbol": "@A",

            "attributeid": "ping",

            "evaluation": "count_of",

            "parameter": "120,0"

         }],

         "eventdefs_cis": [{ "edge_device": "edge1", "ci": "VMware" }]

      }

   ]

}

 Create or Update

To create or update an ED, POST a JSON document with the specific information for that ED to the following URL::

http://localhost:38050/web_services/eventdef

Note: Don't forget to change the domain name (localhost

Use the following example as a guide, but note that it may not include all optional properties.

{

  "account_id" : "firescope",

  "criteria" : "(@A > 3)",

  "description" : "Verify Ping",

  "evaluations" : [{

    "builder_symbol" : "@A",

    "attributeid" : "ping",

    "evaluation" : "count_of",

    "parameter" : "120,0"}],

  "eventdefs_cis" : [{"edge_device" : "edge1", "ci" : "VMware"}],

  "fs_eventdef_type" : {

    "perf" : 1

  },

  "modetype" : 0,

  "priority" : 3,

  "status" : 0

}

 

Property Descriptions


Property Description Type Default Value Required
account_id Name of the SPM account. String   Yes
comments   String   No
createdate Timestamp the ED was created. Read only. Number 0 No
criteria Expression used to evaluate this event definition. Examples:@A>5or(@A+@B-@C)=0 String   No
custom_1 Use these custom fields to store and assign additional information that willbe associated with any generated events. The custom fields are accessible for notifications as macros {EVENT.CUSTOM_1} ... {EVENT.CUSTOM_5}. String   No
custom_2 String   No
custom_3 String   No
custom_4 String   No
custom_5 String   No
description Unique name of the ED. String   Yes
evaluations One or more attributes and the function applied to it that make up this event definition.


Property Description Type Default Value Required
attributeid Name of the attribute. String   Yes
builder_symbol Replacement variable use inside the criteria. Must start with an ampersand followed by a character. Example: @A String   Yes
evaluation Function to apply to the attribute. The following is a list of function names along with its description and a numbered list of parameters to supply in the parameters field. Expand for list of possible values String   Yes
parameter A comma-separated list of parameter values for the specific evaluation. See the evaluation field above to determine the appropriate parameters (if any) to supply. String 0 Yes

 

Object[]   Yes
eventdefs_cis  The parent CI that this event definition is a part of. Example:[{"edge_device" : "Edge1", "ci" : "VMware"}] Object[]   Yes
eventdef_depends  Dependent event definitions Object[] [ ] No
fs_eventdef_type Classify how identified events will impact IT operations. At least one of the following flags mustbe enabled: avail, bus, perf, or sec.


Property Description Type Default Value Required
avail Availability: Indicates that either this asset is offline or users will not be able to perform tasks. Boolean FALSE Yes
bus Business flag: Indicates this event directly impacts key business processes or the business will lose money if the event occurs. Boolean FALSE Yes
perf Performance flag: Indicates end users will experience slowness or degraded service as a result of this event. Boolean FALSE Yes
sec Security flag: Indicates sensitive data may be compromised or unauthorized actions have been identified. Boolean FALSE Yes
Object   Yes
modetype 0 = Simple1 = Advanced Number 0 No
priority The severity for events generated by this definition. Severity is used in dashboards, reports and notifications.The severity level of events can determine if a notification is create and/or sent to users or not.0 = Not Classified1 = Information2 = Average3 = Warning4 = High5 = Major Number 0 Yes
resetinterval Time in seconds until the eventdef should be automatically reset to passed. Number   No
status 0 = Enabled1 = Disabled Number 0 Yes
url Link to a useful KB article or process document that should be followed if this event occurs. String   No
value The read only result of the last calculation of the event definition0 = OK1 = Failed Number   No


Delete

To delete an ED, send an HTTP DELETE request with the same query parameters as the GET request.See the Retrieve for the URL format and query parameter descriptions.

Logical Groups

The REST API allows you to work with Logical Groups in FireScope SPM using a REST client in lieu of the SPM user interface.* Retrieve


Retrieve

To retrieve the current information about a Logical Group as a JSON document, send a GET request with the following URL format:

http://localhost:38050/web_services/logicalgroup?account=firescope&name=Databases

Note: Don't forget to change the domain name (localhost) and query parameter values (account and name) to match your environment and data.

 Query Parameter Descriptions


Parameter Description Type Required
account Name of the SPM Account. String Yes
name Name of the SPM Logical Group. String Yes


Search

Searching provides for the ability to return multiple results in a single call using various filter criteria. To accomplish this, a GET request is sent with a parameter search=true. Every other field besides account is optional and is used to further filter the results. Pagination is mandatory and accomplished using the page and size parameters. The JSON response will wrap the result list and also display the page and the size. The size in the response represents the number of results actually returned, not the size in the request. The response does not contain a count of the total number of pages or the total number of records for performance reasons. The client is expected to keep querying, increasing the page each time, until the result size is less than the requested size, indicating no more results.

http://localhost:38050/web_services/logicalgroup?search=true&account=firescope&servicegroup=Orders&name=substring&page=0&size=100

Note: Don't forget to change the domain name (localhost) and query parameter values (search, account, servicegroup, name, page and size) to match your environment and data.

Search Parameter Descriptions


Parameter Description Type Default Required
account Name of the SPM Account. String   Yes
search Enable searching by setting to true. Setting to false will revert functionality to retrieving a single result. Boolean FALSE Yes
page Indicates which result set is being returned starting at zero and increasing until there are no more results Number 0 Yes
size Indicates how many results are returned in a single page. A max of 250 results is supported. Number 100 Yes
name Filter the results by a case-insensitive substring search of the name field. String   No
servicegroup Filter the results by a Service Group's exact name. String   No

 Example Search Results Response

{

   "account_id": "firescope",

   "entity": "logicalgroup",

   "page": 0,

   "size": 2,

   "results": [

      {

         "account_id": "firescope",

         "name": "Databases",

         "ci": [{"edge_device" : "edge1", "ci" : "10.0.2.1"}]

      }, {

         "account_id": "firescope",

         "name": "Web Servers",

         "ci" : []

      }

   ]

}

 

Create or Update

To create or update a Logical Group, POST a JSON document with the specific information for that Logical Group to the following URL:

http://[SPM IP address]:38050/web_services/logicalgroup

Use the following example as a guide, but note that it may not include all optional properties.

{

  "account_id" : "firescope",

  "name" : "LG1",

  "ci": [{

    "edge_device" : "edge1",

    "ci" : "10.0.2.1"

  }]

}

Property Descriptions


Property Description Type Default Value Required
account_id Name of the SPM Account. String   Yes
name Name of the SPM Logical Group. String   Yes
ci Array of CI instances.Example: [{"edge_device" : "Edge 1", "ci" : "SWEB2 OpSource"}]


Property Description Type Default Value Required
edge_device Name of existing Edge Device for this CI. String   Yes
ci Name of existing CI to relate. String   Yes
Object[] [] No


Delete

To delete a Logical Group, send an HTTP DELETE request with the same query parameters as the GET request.See the Retrieve for the URL format and query parameter descriptions.

Maintenance Windows

 The REST API allows you to work with Maintenance Windows in FireScope SPM using a REST client in lieu of the SPM user interface.

Retrieve

Schema

Create or Update

Delete

Retrieve

To retrieve the current information about a Maintenance Window in SPM, send unique query parameters in a GET request to the following URL:

http://localhost:38050/web_services/maintenance_window?account=firescope&name=Weekly upgrade

Note: Don't forget to change the domain name (localhost) and query parameter values (account, edge_device, ci, and name) to match your environment and data.

A JSON response will be returned similar in structure to the payload for creation.

Query Parameter Descriptions


Parameter Description Type Required
account Name of the SPM Account. String Yes
name Name of the Maintenance Window. String Yes


Schema

To retrieve the full SPM schema for a Maintenance Window, send the Account name with the schema parameter set to true in a GET request to the following URL:

http://[SPM IP address]:38050/web_services/maintenance_window?account=[Account name]&schema=true

Create or Update

To create or update an Maintenance Window, POST a JSON document with the specific Maintenance Window information to the following URL:

http://[SPM IP address]:38050/web_services/maintenance_window

You can use the following example as a guide, but note that it does not include all optional properties.

{

  "account_id": "firescope",

  "name": "Weekly Upgrade",

  "description": "Maintenance Window for weekly upgrade of application servers",

  "first_end_date": 1434399000,

  "first_start_date": 1434398300,

  "ci": [{ "edge_device": "Edge 1", "ci": "10.0.12.134" }],

  "logicalgroup": [ "Application Servers" ],

  "eventdef": [{ "edge_device": "Edge 1", "eventdef": "Response time < 50ms" }],

  "ical": {

    "frequency": "WEEKLY",

    "interval": 1,

    "occurrences": 3

  }

}

Property Descriptions

The following table provides information about all required and optional properties available for a Maintenance Window.


Property Description Type Default Value Required
account_id Name of the SPM Account. String   Yes
name Name of the Maintenance Window. String   Yes
ci A list of CI's that need to be a part of this maintenance window. Any eventdefs associated to these CI's are disregarded until the maintenance time ends. At least one of ci, eventdef, or logicalgroup fields has to be populated. Object[]   No
description A description for the purpose of this Maintenance Window String   Yes
eventdef A list of eventdefs that need to be a part of this maintenance window. At least one of ci, eventdef, or logicalgroup fields has to be populated. Object[]   No
final_end_date The timestamp in seconds from the epoch when this maintenance window should run for the last time. Leave null to have it run indefinitely. The value must be on or after the first end date. This corresponds to the UNTIL in the iCalendar specification. Number 2147385600 No
first_end_date The timestamp in seconds from the epoch when this maintenance window should end its initial run. The end date must be at least 10 minutes greater than the start date. The end date must be set to a date in the past for retroactive maintenance windows. This corresponds to the DTEND in the iCalendar specifiction. Number   Yes
first_start_date The timestamp in seconds from the epoch when this maintenance window should start its initial run. The start date must be at least 5 minutes greater than the current time. This in conjunction with the first_end_date are used to define the ongoing period when the maintenance window should run. This corresponds to the DTSTART in the iCalendar specifiction. Number   Yes
ical These fields determine how often the period defined by the first and end dates are repeated:


Property Description Type Default Value Required
days A list of days of the month (1-31) that this maintenance window should run. Used to limit the days to run for DAILY or to expand the days to run for MONTHLY. Number[]   No
days_of_week A list of days of the week that this maintenance window should run. Used to limit when it should run for DAILY or to expand the days to run for WEEKLY and MONTHLY.Sun Mon Tue Wed Thu Fri Sat String[]   No
frequency Indicates how frequent this maintenance window should repeat.DAILY - Repeats every day.WEEKLY - Repeats every week.MONTHLY - Repeats every month.onetime - Does not repeatretro - Retroactive maintenance window to adjust past events. Start and end times must be in the past. String onetime Yes
interval How often this maintenance should repeat relative to its frequency. For example, an interval of 2 with a frequency of DAILY would repeat every other day, but with a frequency of WEEKLY it would be every other week. Number 0 Yes
occurrences How many times this maintenance window should repeat until it should end. Leave empty or set to 0 to repeat indefinitely. This can be superseded using the final_end_date, however. Number 0 Yes
Object   Yes
logicalgroup A list of logical groups that need to be a part of this maintenance window. At least one of ci, eventdef, or logicalgroup fields has to be populated. String[]   No
maintenance_window_instance A read-only list of instances that represent previous runs of this maintenance windows.


Property Description Type Default Value Required
ci A list of CIs this maintenance window was applied to. Object[]   No
eventdef A list of eventdefs this maintenance window was applied to. Object[]   No
end_date When this maintenance window instance finished. Number   Yes
ical See ical section above for previous definition. Object   Yes
logicalgroup A list of logical groups this maintenance window instance was applied to. String[]   No
name The name of this instance at the time of execution. String   Yes
start_date When this maintenance window instance started. Number   Yes
Object[]   No
next_end_date The read-only timestamp of the next time the maintenance window should end. Number   No
next_start_date The read-only timestamp of the next time the maintenance window should start. Number   No


Delete

To delete an Maintenance Window send an HTTP DELETE request with the same query parameters as the GET request.

See the Retrieve for the URL format and query parameter descriptions.

Notifications

The REST API allows you to work with Notifications in FireScope SPM. Specifically, you can:* Retrieve


Retrieve

To retrieve the current information about a Notification in SPM, send unique query parameters in a GET request to the following URL:

http://[IP address]:38050/web_services/notifications?account=[Account name]&name=[Notification name]

Example:

http://localhost:38050/web_services/notifications?account=fsnewyork&name=notification1

Note: Don't forget to change the domain name (localhost) and query parameter values (account, and name) to match your environment and data.

A JSON response will be returned similar in structure to the payload for the Create or Update.

Query Parameter Descriptions


Parameter Description Type Required
account The SPM account String Yes
name Name of the Notification String Yes

 

Create or Update

To create or update a Notification, POST a JSON document with the appropriate information to the following URL:

http://[IP address]:38050/web_services/notifications

Note: Don't forget to change the domain name (localhost) to match your environment and data.

Use the following example as a guide.

{

  "account_id" : "firescope",

  "name" : "Event Def Severity Notification",

  "created_by" : "Admin",

  "status" : 0,

  "type" : 1,

  "filters" : [{

      "filtertype" : 4,

      "operator" : 5,

      "value" : {"edge_device" : "edge1", "ci" : "VMWare", "eventdef" : "Ping"}

    },{

      "filtertype" : 2,

      "operator" : 0,

      "value" : "5"

    }],

  "procedures" : [{

      "content_type" : 0,

      "longdata" : "{CI}:{IPADDRESS}:{EVENT.NAME}:{STATUS}",

      "object" : 0,

      "objectid" : {"users" : "bryancan"},

      "proceduretype" : 0,

      "shortdata" : "{CI}:{EVENT.NAME}:{STATUS}"

    }, {

      "content_type" : 0,

      "longdata" : "{CI}:{IPADDRESS}:{EVENT.NAME}:{STATUS}",

      "object" : 1,

      "objectid" : {"usrgrp" : "FireScope administrators"},

      "proceduretype" : 0,

      "shortdata" : "{CI}:{EVENT.NAME}:{STATUS}"

    }],

  "usrgrp" : ["Database administrators", "FireScope administrators", "Guests"]

}

 

Property Descriptions


Property Description Type Default Required
account_id The name of the SPM account. String   Yes
created_by The user name of the person who created this notification. String   Yes
name The unique name of the notification. String   Yes
status Status of the Notification:0 = Enabled1 = Disabled Number 0 Yes
type The type of boolean logic to apply to the filters:1 - AND2 - OR Number 1 Yes
usrgrp The list of associated user groups. String[]   No
procedures  


Property Description Type Default Required
  0 = text/plain1 = text/html Number 0 Yes, if Message type
longdata A macro-filled text field whose values depends upon the type.For messages, this field represents the message body.For remote commands, this field represents the actual command to executeFor ServiceNow, this field represents the ticket comment to add. String   Yes
object 0 = Single User1 = User Group Number 0 Yes, if Message type