Assure1 Event Generic Ticket Connector¶

Overview¶

The Assure1 Event Generic Ticket Connector allows for bi-directional integration with an external ticketing system, creating and synchronizing tickets in the ticketing system using information from Assure1 Events. For each event retrieved by the SQL query, a new ticket is opened using customizable rules. The application also synchronizes currently open tickets using a separate set of customizable rules.

Generic Ticket Connector Setup¶

The default query will process events that that have the "TicketFlag" field set to "1" and have a blank "TicketID" field. These values can be set manually in the event, using an event list tool, or by another application (for example, Assure1 Event Custom Action Policy Engine (CAPE)). The default rules were written to connect to a Wendia ticketing system and create an ticket with information from the event, then periodically check the ticket status to see if the issue has been resolved. This will need to be changed to connect to other ticketing systems.

Review the query in the "SelectSQLFile" file to see what events will be selected for processing. Make changes to the events that are selected as needed.
Review the processing that is done in the "OpenTicketRules" file to see the processing that is done to open a ticket. Make changes to the processing of new tickets as needed.
Review the processing that is done in the "SyncTicketRules" file to see the processing that is done to keep the ticket status synchronized. Make changes to the synchronization of existing tickets as needed.
Enable the default Service, unless a specific configuration option is needed.

Configuration -> Broker Control -> Services

Default Service¶

Field	Value
Package Name	coreProcessing-app
Service Name	Event Ticket Connector
Service Program	bin/core/processing/GenericTicketConnectord
Service Arguments
Service Description	Generic ticket connector
Failover Type	Standalone (Supported: Standalone, Primary/Backup)
Status	Disabled
Privileged	(Checked)

Default Configuration¶

Name	Value	Possible Values	Notes
BranchDir	core/default	Text, 255 characters	Relative path to Rules directory.
IncludeRules	processing/event/ticket/ticket.includes	Text, 255 characters	Relative path to Include Rules.
LoadRules	processing/event/ticket/ticket.load	Text, 255 characters	Relative path to Load Rules
LogFile	logs/EventTicketConnector.log	Text, 255 characters	Relative path to Log File.
LogLevel	ERROR	OFF, FATAL, ERROR, WARN, INFO, DEBUG	Logging level used by application.
OpenTicketRules	processing/event/ticket/open_ticket.rules	Text, 255 characters	Rules run upon finding any new events ready to be ticketed.
PollTime	60	Integer	Interval in seconds where events in the TicketHash are processed by SyncTicketRules, and new events are queried using OpenTicketRules and processed by OpenTicketRules.
SelectSQLFile	processing/event/ticket/events.sql	Text, 255 characters	Relative path to SQL file containing database query. (Ensure processed events are excluded after processing.)
ShardID	1	Integer	Database shard to be used. - NO RELOAD CONFIG SUPPORT
SyncTicketRules	processing/event/ticket/sync_ticket.rules	Text, 255 characters	Rules run at PollTime interval on Tickets saved in the $TicketHash for scheduled synchronization.
Threads	3	Integer	Number of processing threads created.

Rules¶

This connector uses the Assure1 standard rules architecture. The rules are written in Perl syntax. Refer to the following guides for details on rules creation:

Tokens¶

The connector exposes the following tokens for rules processing.

Token	Description
$AppConfig	Hash reference to the application configuration name-value pairs that were configured. (i.e. use $AppConfig->{'Host'} to retrieve the set value for 'Host'.)
$EventRow	Resulting data from query. Use $EventRow->{'FieldName'} to access the "FieldName" data.
$CustomHash	Custom key, value cache available across all rules. Contents commonly defined in Load Rules then used in Base or other rules. NOTE: This variable is a shared object and any additional sub hashes or arrays must be shared before use or it will cause the error: "Invalid value for shared scalar". Instantiate the sub hash/array using '&share({})' e.g. $CustomHash->{SubObject} = &share({});
$StorageHash	Internal cache used as the StorageHash option when calling rules functions such as FindDeviceID(). NOTE: The structure of this cache is subject to change! Not recommended for custom global storage or manual manipulation; use $CustomHash.

Integration Example¶

SugarCRM¶

One of the many use cases for Assure1 is to create and/or update tickets in various ticketing systems. This example will demonstrate an integration with a SugarCRM system utilizing the Assure1 Generic Ticketing Connector and the SOAP API.

One possible use case is the monitoring of VPN tunnels between one or more sites. When a tunnel down event is received, Assure1 verifies the tunnel is down and then updates the "TicketFlag" field for the event. This is then caught by the ticketing connector, which opens a case in SugarCRM. After the case is opened in SugarCRM, the case ID is stored in memory, which is then used to check the SugarCRM case. If the SugarCRM case is closed, the event severity is changed to "0".

Dependencies¶

Events that need tickets should have been processed and are already stored in the database. This example will assume that the to-be processed events have the "TicketFlag" field set to "1" prior to using the ticketing connector.
Being familiar with the inputs and outputs of the SugarCRM implementation is highly recommended as the examples below will most likely need to be changed, depending on the specific environment.

Steps¶

Create new rules files.
1. Via the UI, open the Rules UI:
  
  Configuration -> Rules
2. Expand the following folder path:
  
  Core Rules (core) -> Default read-write branch (default) -> processing -> event
3. Select on the "event" folder, then select "Add -> New Folder". In the form, enter "ticket-SugarCRM" , then "Submit" the new folder name. Enter a custom commit message, or click "Ok" to accept the default.
4. Under the "ticket-SugarCRM" folder, create five new rules files that will be used by the connector. The default path for the default connector configuration is in the following folder:
  1. "sugar_events.sql" - This file contains the SQL query used by the connector to find events that will have a ticket opened.
  2. "sugar.load" - This file will contain any functions needed to pre-load the data when the connector starts. For this example, the file will be left blank, but still needs to be created.
  3. "sugar.includes" - This file will contain the path to any additional rules files that can be used by the connector when processing data. For this example, the file will be left blank, but still needs to be created.
  4. "sugar_open_ticket.rules" - This file contains the Perl logic used by the connector to create a new ticket when an event is detected.
  5. "sugar_sync_ticket.rules" - This file contains the Perl logic used by the connector to sync an existing ticket after an event is detected and a ticket is created.
5. Copy the code from the "CODE EXAMPLE" below and paste it into the appropriate rules file, changing the following fields. Save each file after pasting and updating the code:
  - sugar_open_ticket.rules
    - (ASSURE1-SERVER-URL) - This should be the URL to a Assure1 presentation server.
    - (SUGAR-URL) - This should be the URL to a SugarCRM server.
    - (SUGAR-USERNAME)/(SUGAR-PASSWORD) - This should be the login credentials to the SugarCRM server with permissions to access the API.
    - (SUGAR-USER-ID) - This should be the SugarCRM User ID that will have the case associated to it.
  - sugar_sync_ticket.rules
    - (SUGAR-URL) - This should be the URL to a SugarCRM server.
    - (SUGAR-USERNAME)/(SUGAR-PASSWORD) - This should be the login credentials to the SugarCRM server with permissions to access the API.
Create a new service using the following settings.

Configuration -> Broker Control -> Services
- Package Name => coreProcessing-app
- Service Name => Event SugarCRM Ticket Connector
- Service Program => bin/core/processing/GenericTicketConnectord
- Failover Type => Standalone
- Status => Enabled
- Privileged => (Checked)
- Configuration
  - BranchDir => core/default
  - IncludeRules => processing/event/ticket-SugarCRM/sugar.includes
  - LoadRules => processing/event/ticket-SugarCRM/sugar.load
  - LogFile => logs/EventSugarTicketConnector.log
  - LogLevel => DEBUG
  - OpenTicketRules => processing/event/ticket-SugarCRM/sugar_open_ticket.rules
  - PollTime => 60
  - SelectSQLFile => processing/event/ticket-SugarCRM/sugar_events.sql
  - ShardID => 1
  - SyncTicketRules => processing/event/ticket-SugarCRM/sugar_sync_ticket.rules
  - Threads => 3
The broker will start the service the next time the self-check is done.
Verify functionality.

Code Examples¶

sugar_events.sql¶

Note: Additional fields can be selected if they would be useful within the rules.

  SELECT EventID,   
         Node,
         Summary
    FROM Events
   WHERE TicketID = '' 
     AND TicketFlag = 1
ORDER BY LastReported desc

sugar_open_ticket.rules¶

######################### 
# $EventRow = Hash for record found
#########################
my $EventsDBH = DBConnect($Config, 'Event', {AutoCommit => 1}) || die 'Cannot open connection to database: ' . $DBI::errstr . "\n";
my $EventID = $EventRow->{EventID};
$Log->Message("INFO", " --> Open Ticket Rules --> Running Rules Starting [$EventID]");
$Log->Message("DEBUG", " --> Open Ticket Rules --> Event Dump\n--------------------------\n" . Dumper($EventRow) . "\n--------------------------\n");

# prepare a few variables for use
my $CaseNum        = 0;
my $CaseIdentifier = 0;

my ($ErrorFlag, $Message) = UpdateEvent({
    DBH     => \$EventsDBH,
    EventID => $EventID,
    ShardID => $AppConfig->{'ShardID'},
    Values  => {
        TicketFlag => 2,
        TicketID   => 'Pending'
    }
});

# set which tunnel was down based on the data within the event
if ( $EventRow->{Summary} =~ m/Neighbor 192.0.2.1/ ) {
    $VPNTunnel = "Datacenter <---> Destination 2";
}
elsif ( $EventRow->{Summary} =~ m/Neighbor 192.0.2.2/ ) {
    $VPNTunnel = "Datacenter <---> Destination 3";
}
else {
    $VPNTunnel = "Datacenter <---> Unknown";
}

$CaseSubject = 'A Tunnel has been down for more than 1 minute - ' . $VPNTunnel;

#############
# NOTE: UNKNOWN IF A URL TO A1 CAN BE DONE AT THIS TIME.
#############
$CaseBody    = "A Tunnel is down.

Node = $EventRow->{Node}

VPN Tunnel = $VPNTunnel

Down Alert Information:
    Raw Message = $EventRow->{Summary}
    Event = https://(Assure1-SERVER-URL)/events/tools/GenericBaseTools.php?Tool=AlarmInfo;EventID=$EventID
";

# needed if sugar server https cert is self-signed
BEGIN { $ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = 0; }

use SOAP::Lite;
use Data::Dumper;

# establish the connection to the soap server
my $SugarConnection = SOAP::Lite->new(
    'readable' => 1,
    'uri'      => 'http://www.sugarcrm.com/sugarcrm',
    'proxy'    => 'https://(SUGAR-URL)/soap.php'
);

# prepare some variables that will be used for logging into sugar
my $SugarUsername = SOAP::Data->name('user_name' => '(SUGAR-USERNAME)');
my $SugarPassword = SOAP::Data->name('password'  => '(SUGAR-PASSWORD)');

# prepare the login request data
my $LoginRequest = SOAP::Data
    ->prefix('tns')
    ->type('user_auth')
    ->name('user_auth' => \SOAP::Data->value(
        $SugarUsername,
        $SugarPassword
    ))
;

my $Result;
my $SessionID;

eval {
    # execute the login request
    $Result = $SugarConnection->login($LoginRequest);
    $Log->Message("DEBUG", "Login Returned:" . Dumper($Result->result));

    # if logged in successfully...
    if (defined $Result) {

        # get the session id
        $Session   = SOAP::Data->name('session' => $Result->result->{'id'});
        $SessionID = $Result->result->{'id'};
        $Log->Message("DEBUG", "Session ID = " . $SessionID);

        # get the user id
        $Result = $SugarConnection->get_user_id($Session);
        $UserID = $Result->result;
        $Log->Message("DEBUG", "User ID = " . $UserID);

        # create the case in Sugar
        $Result = $SugarConnection->set_entry( 
            $SessionID, 
            "Cases", 
            [ 
                { name => 'contact_id',              value => $UserID }, 
                { name => 'status',                  value => "New" }, 
                { name => 'priority',                value => 5 }, 
                { name => 'account_id',              value => "(SUGAR-USER-ID)" }, 
                { name => 'name',                    value => $CaseSubject }, 
                { name => 'description',             value => $CaseBody }, 
                { name => 'case_request_type_dom_c', value => "issue" }, 
                { name => 'type',                    value => "support_desk" }
            ] 
        );
        $Log->Message("DEBUG", "Case create returned = " . Dumper($Result->result));

        # get the case ID
        $CaseID = $Result->result->{'id'};
        $Log->Message("DEBUG", "Case ID = " . $CaseID);

        my $get_entry_listRequest = SOAP::Data->value(
            SOAP::Data->name('session'       => $SessionID),
            SOAP::Data->name('module_name'   => 'Cases'),
            SOAP::Data->name('query'         => 'cases.id = \'' . $CaseID . '\''),
            SOAP::Data->name('order_by'      => ''),
            SOAP::Data->name('offset'        => ''),
            SOAP::Data->name('select_fields' => ''),
            SOAP::Data->name('max_results'   => ''),
            SOAP::Data->name('deleted'       => '')
        );

        # get the data from sugar
        $Result = $SugarConnection->get_entry_list($get_entry_listRequest);
        $Log->Message("DEBUG", "Get case data returned = " . Dumper($Result->result));

        # get the case number
        $CaseNumber = $Result->result->{'entry_list'}[0]->{'name_value_list'}[12]->{'value'};
        $Log->Message("DEBUG", "Case Number = " . $CaseNumber);

        # logout
        $Result = $SugarConnection->logout($Session);
        $Log->Message("DEBUG", "Logout returned = " . Dumper($Result->result));
    }
};

if ($@) {
    $Log->Message("ERROR", "An error occurred: " . $@);
}

# if the ticket was opened...
if ( $CaseNumber > 0 ) {
    # ... update event with ticket number
    my ($ErrorFlag, $Message) = UpdateEvent({
        DBH     => \$EventsDBH,
        EventID => $EventID,
        ShardID => $AppConfig->{'ShardID'},
        Values  => {
            TicketFlag => 2,
            TicketID   => $CaseNumber
        }
    });
}
else {
    # ... or update event with errors
    my ($ErrorFlag, $Message) = UpdateEvent({
        DBH     => \$EventsDBH,
        EventID => $EventID,
        ShardID => $AppConfig->{'ShardID'},
        Values  => {
            TicketFlag => 'ERROR',
            TicketID   => 'ERROR'
        }
    });
}

############################### 
# Setup Ticket Sync
############################### 
if ( ( ! exists $TicketHash->{$EventID} ) && ( int($CaseID) > 0 ) ) {
    $TicketHash->{$EventID} = &share({});
    $TicketHash->{$EventID}->{CaseNumber} = $CaseNumber;
    $TicketHash->{$EventID}->{CaseID}     = $CaseID;
}

$Log->Message("INFO", " --> Open Ticket Rules --> Rules Running Complete [$EventID]");
$EventsDBH->disconnect;

sugar_sync_ticket.rules¶

######################### 
# $EventID = Event Found
#########################

$Log->Message("INFO", " --> Sync Ticket Rules --> Running Rules Starting [$EventID]");

# grab data from hash and log it...
my $CaseNumber = $TicketHash->{$EventID}->{CaseNumber};
my $CaseID     = $TicketHash->{$EventID}->{CaseID};
$Log->Message('INFO', [
    '#===============================================',
    '# Sync Assure1 Event with Sugar',
    '# EventID = '    . $EventID,
    '# CaseNumber = ' . $CaseNumber,
    '# CaseID = '     . $CaseID,
    '#===============================================',
]);

# connect to the events databases
my $EventsDBH = DBConnect($Config, 'Event', {AutoCommit => 1}) || die 'Cannot open connection to database: ' . $DBI::errstr . "\n";

# needed if sugar server https cert is self-signed
BEGIN { $ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = 0; }

use SOAP::Lite;
use Data::Dumper;

# establish the connection to the soap server
my $SugarConnection = SOAP::Lite->new(
    'readable' => 1,
    'uri'      => 'http://www.sugarcrm.com/sugarcrm',
    'proxy'    => 'https://(SUGAR-URL)/soap.php'
);

# prepare some variables that will be used for logging into sugar
my $SugarUsername = SOAP::Data->name('user_name' => '(SUGAR-USERNAME)');
my $SugarPassword = SOAP::Data->name('password'  => '(SUGAR-PASSWORD)');

# prepare the login request data
my $LoginRequest = SOAP::Data
    ->prefix('tns')
    ->type('user_auth')
    ->name('user_auth' => \SOAP::Data->value(
        $SugarUsername,
        $SugarPassword
    ))
;

my $Result;
my $SessionID;

eval {
    # execute the login request
    $Result = $SugarConnection->login($LoginRequest);
    $Log->Message("DEBUG", "Login Returned:" . Dumper($Result->result));

    # if logged in successfully...
    if (defined $Result) {

        # get the session id
        $Session   = SOAP::Data->name('session' => $Result->result->{'id'});
        $SessionID = $Result->result->{'id'};
        $Log->Message("DEBUG", "Session ID = " . $SessionID);

        # get the case data from sugar
        my $get_entry_listRequest = SOAP::Data->value(
            SOAP::Data->name('session'       => $SessionID),
            SOAP::Data->name('module_name'   => 'Cases'),
            SOAP::Data->name('query'         => 'cases.id = \'' . $CaseID . '\''),
            SOAP::Data->name('order_by'      => ''),
            SOAP::Data->name('offset'        => ''),
            SOAP::Data->name('select_fields' => ''),
            SOAP::Data->name('max_results'   => ''),
            SOAP::Data->name('deleted'       => '')
        );
        $Result = $SugarConnection->get_entry_list($get_entry_listRequest);
        $Log->Message("DEBUG", "Get case data returned = " . Dumper($Result->result));

        # get the case status
        $CaseStatus = $Result->result->{'entry_list'}[0]->{'name_value_list'}[14]->{'value'};
        $Log->Message("DEBUG", "Case Status = " . $CaseStatus);

        # if the case is closed in sugar, update the event severity to "clear" and remove the data from the sync'ed ticket hash
        if ( $CaseStatus eq 'Closed' ) {
            my ($ErrorFlag, $Message) = UpdateEvent({
                DBH     => \$EventsDBH,
                EventID => $EventID,
                ShardID => $AppConfig->{'ShardID'},
                Values  => {
                    Severity => 0
                }
            });
            delete $TicketHash->{$EventID};
        }

        # logout
        $Result = $SugarConnection->logout($Session);
        $Log->Message("DEBUG", "Logout returned = " . Dumper($Result->result));
    }
};

if ($@) {
    $Log->Message("ERROR", "An error occurred: " . $@);
}

# disconnect to the events databases
$EventsDBH->disconnect;

$Log->Message("INFO", " --> Sync Ticket Rules --> Rules Running Complete [$EventID]");

Administration Details¶

The following list shows the technical details needed for advanced administration of the application:

Package - coreProcessing-app
Synopsis - ./GenericTicketConnectord [OPTIONS]

Options:

 -c, --AppConfigID N   Application Config ID (Service, Job, or Request ID)
 -?, -h, --Help        Print usage and exit

Threaded - Multi-Threaded