10. 01. 2018 Benjamin Gröber Development, NetEye, Uncategorized

Using the NetEye3 Perl API – An Intoduction

https://upload.wikimedia.org/wikipedia/commons/1/15/Logo_De_Perl.png

In an earlier post we saw how to extend the NetEye Perl API (http://www.neteye-blog.com/2017/06/how-to-extend-or-modify-the-apis/).  By popular request, today we will stay at a higher level and walk through some simple use cases:

* Searching for Objects
* Adding new Objects
* Removing Objects

Most of our scripts will have the following skeleton:
```
#!/usr/bin/perl
use strict;
use warnings;

use NetEye::Config;

# AutoPersist => 0 avoids writing to DB immediately.
# Calling ->save() on changes is necessary.
my $ConfigObject = NetEye::Config->new( AutoPersist => 0, );

# Our Code goes here

1;
```

The NetEye::Config Class is a monolithic singleton, possibly instantiated only once per script.  It is used for loading global configurations, allowing local overrides and establishing and pooling connections to databases and services.

Getting Information

If we want to see if a specific Host is in the database, we can use the searchForObject() subroutine.  (If you would like more information about the usage of a package/subroutine, please consult the related perldoc.)

```
#!/usr/bin/perl
use strict;
use warnings;

use NetEye::Config;
use NetEye::Monitoring::Host;

use Data::Dumper; # only used for development/printing


my $ConfigObject = NetEye::Config->new( AutoPersist => 0, );
my $HostName = 'neteye';

# Instantiating a new Object of the Class Host
# This is needed as Helper Object holding the details for the general implementation
# of ->searchForObject() in the parent Class NetEye::Object
my $Host = NetEye::Monitoring::Host->new( ConfigObject => $ConfigObject, )
 ->searchForObject(
 Properties => {
 name => $HostName,
 }
 );

if ($Host) {
 print Dumper($Host->getProperties());
} else {
 print "Host '$HostName' not found."
}

1;
```

An example that’s a little bit more complex would be finding all hosts with a specific host template.

```
#!/usr/bin/perl
use strict;
use warnings;

use NetEye::Config;
use NetEye::Monitoring::Host;
use NetEye::Monitoring::Template::Host;

use Data::Dumper; # only used for development/printing


my $ConfigObject = NetEye::Config->new( AutoPersist => 0, );
my $HostTemplateName = 'generic-host';

# Our Code goes here
my $HostTemplate = NetEye::Monitoring::Template::Host->new( ConfigObject => $ConfigObject, )
 ->searchForObject(
 Properties => {
 name => $HostTemplateName,
 }
 );

if (!$HostTemplate){
 print "HostTemplate with Name '$HostTemplateName' not found!\n";
 exit 1;
}

# Here we use the seachFor() subroutine instead of searchForObject() which expects to return a single Object.
# searchForObject() returns an error if there is more than one result
my @Hosts = NetEye::Monitoring::Host->new( ConfigObject => $ConfigObject, )
 ->searchFor(
 Properties => {
 hosttemplate_id => $HostTemplate->getId(),
 }
 );

if (! scalar(@Hosts)) {
 print "HostTemplate '$HostTemplateName' is not assigned to any hosts.";
 exit 2;
}

for my $Host (@Hosts){
 print Dumper($Host->getProperties());
}

1;
```

Adding / Removing Objects from the DB
————————————-

We can easily add Objects to the Database by creating a new Object of the desired Class, setting the desired Properties and calling ‘->save()’.

```
#!/usr/bin/perl
use strict;
use warnings;

use NetEye::Config;
use NetEye::Monitoring::Host;
use NetEye::Monitoring::Template::Host;

use Data::Dumper;


my $ConfigObject = NetEye::Config->new( AutoPersist => 0, );
my $HostTemplateName = 'generic-host';
my $HostName = 'MyNewHost';
my $HostAddress = '127.0.0.1';

# A Host needs to have a HostTemplate assigned.
my $HostTemplate = NetEye::Monitoring::Template::Host->new( ConfigObject => $ConfigObject, )
 ->searchForObject(
 Properties => {
 name => $HostTemplateName,
 }
 );

if (!$HostTemplate){
 die "HostTemplate with Name '$HostTemplateName' not found!";
}

# Here we create a new NetEye::Host Object and set the Properties we want it to have.
# hosttemplate_id is a mandatory property so we must pass a valid ID.
# You can understand which properties are mandatory and which are optional
# by simply looking at the PropertiesMap of the desired Class.
my $Host = NetEye::Monitoring::Host->new(
 ConfigObject => $ConfigObject,
 Properties => {
 name => $HostName,
 alias => $HostName . " Alias",
 address => $HostAddress,
 hosttemplate_id => $HostTemplate->getId(),
 },
);

if ( !$Host->save() ){
 die "Saving Host '$HostName' to DB failed!";
}

my $ID = $Host->getId();
print "ID: " . $ID . "\n" . Dumper($Host->getProperties());

# The Host can now be found in the DB, either by ID or by name.
$Host = NetEye::Monitoring::Host->new( ConfigObject => $ConfigObject, )
 ->searchForObject(
 Properties => {
 #host_id => $ID,
 name => $HostName,
 }
 );

print "ID: " . $Host->getId() . "\n" . Dumper($Host->getProperties());

# By calling ->remove() the object is immediately removed from the Database.
if ( !$Host->remove() ){
 die "Removing Host '$HostName' to DB failed!";
}

# Now we will get no result from any search query
$Host = NetEye::Monitoring::Host->new( ConfigObject => $ConfigObject, )
 ->searchForObject(
 Properties => {
 name => $HostName,
 }
 );
print "Gone: " . Dumper($Host);

1;
```

From here on out you can mix and match these concepts as necessary.  Remember to lways refer to the documentation contained in the single Perl classes!

Benjamin Gröber

Benjamin Gröber

R&D Software Architect at Wuerth Phoenix
Hi, my name is Benjamin and I'm Software Architect in the System Integration Research & Development Team at Wuerth Phoenix. I discovered my passion for Computers and Technology when I got my first PC shortly after my 7th birthday in 1999. Using computers and playing with them soon got boring and so, just a few years later, I taught myself Visual Basic and entered the world of Software Development. Since then I loved trying to keep up with the short lived, fast evolving IT world and exploring new technologies, eventually putting them to good use. Lately I'm investing my free time in the relatively new languages Go and Rust.

Author

Benjamin Gröber

Hi, my name is Benjamin and I'm Software Architect in the System Integration Research & Development Team at Wuerth Phoenix. I discovered my passion for Computers and Technology when I got my first PC shortly after my 7th birthday in 1999. Using computers and playing with them soon got boring and so, just a few years later, I taught myself Visual Basic and entered the world of Software Development. Since then I loved trying to keep up with the short lived, fast evolving IT world and exploring new technologies, eventually putting them to good use. Lately I'm investing my free time in the relatively new languages Go and Rust.

Leave a Reply

Your email address will not be published. Required fields are marked *

Archive