cla/ci - Resource Classes

Programmatically speaking, each Configuration Item (CI) can have both data and behaviour encapsulated into each Resource Class and Resource instance.

Instantiating an Resource from the DB¶

Instantiate a Resource means to load an existing Resource from the Clarive Resource database.

This is accomplished using the ci.load(mid) function.

var ci = require("cla/ci");
var server = ci.load("123");

Instanciating CIs¶

To create a CI, first we need to load the desired Resource class as a class variable:

var ci = require("cla/ci");
var GenericServer = ci.getClass('GenericServer');

Now we can generate an in-memory instance of the CI. This instance is generaly usable, except that it's not yet permanent in the database.

To save a Resource to the database, we just have to invoke the save() method.

var ci = require("cla/ci");
var GenericServer = ci.getClass('GenericServer');
var server = new GenericServer({ name: 'myhost', hostname:'myhost.intranet' });
server.save();

The save() method returns an mid, which identifies the Resource in the database.

Creating your own CIs¶

You can create your own Resource classes, with its corresponding storage and methods.

var ci = require("cla/ci");
ci.createClass("MyClass",{
    has_bl: 0,
    has:{
        ipAddress: { is:"rw", isa:"Str", required: true }
    },
    superclasses: ['GenericServer']
});

var obj = ci.build("MyClass",{ ipAddress: 22, hostname:'myhost.intranet' });
obj.ipAddress();

//alternatively
var MyClass = ci.getClass("MyClass");
var obj  = new MyClass({ ipAddress: '123.0.0.1', hostname: 'myhost.intranet' });

// now all Resource methods will be available
var mid = obj.save();
var again = ci.load(mid);

Once you create your own Resource class, you cannot add new methods or attributes.

Methods¶

You can add your own methods to a resource class using the methods clause of createClass:

var ci = require("cla/ci");
ci.createClass("MyClass",{
    has_bl: 0,
    has:{
        ipAddress: { is:"rw", isa:"Str", required: true }
    },
    methods: {
        getIP: function() {
             return this.ipAddress();
        }
    },
    superclasses: ['GenericServer']
});

//... create obj here ...

obj.getIP();

Method modifiers¶

This powerful feature, allows you to modify class method behavior by hooking to methods with after, before and around.

var ci = require("cla/ci");
ci.createClass("MyClass",{
    has_bl: 0,
    before: {
        save: function(data) {
             console.log('This runs before the resource data is saved', data);
        }
    },
    around: {
        save: function(orig, self, data) {
             console.log('This replaces the resource save method...', data);
             //... so you need to call the original method yourself:
             orig.call(this, data);
        }
    },
    after: {
        save: function(data) {
             console.log('This runs after resource data is saved', data);
        }
    },
    superclasses: ['GenericServer']
});

//... create obj here ...

obj.save();  // this will trigger the save method on the Resource

The method must exist before being modified. Typically it will be a method defined in a parent class or class role.

Getting data from the CI¶

For each data member of the CI there are 2 ways to get its value:

obj.{member}() - method to call a {member}
obj.jsData()[ {member} ] - the jsData() method returns the full resource as a simple JS Object.

    var obj = ci.load(mid);
    var data = obj.jsData();
    console.log(data.mid, data.hostname)

Creating services for CIs¶

To create a service for a CI, we need to do it like this:

var reg = require("cla/reg");

reg.registerCIService('testservice', {
    class: 'CiClass',
    name: 'Service test',
    icon: '/plugin/plugin/icon/plugin.svg',
    form: '/plugin/cla-plugin-plugin/form/plugin-service.js',
    handler: function(ctx, config) {

        print("Your code will be here");
 }
});

Where:

CiClass is the Resource where you want to enable the service. In config variable you will have your form parameters in case you have one.

To access to the Resource parameters where you are launching the service, you need to do it through the variable this. Example: this.param(). Where param() is the parameter param of the Resource where you are launching the service.

Searching CIs¶

Searching for CIs can be done in 2 different ways, by returning instantiated Resource objects or database documents.

The main difference resides in that database documents are faster to retrieve, but can be only used read-only. CI objects have methods that and can be manipulated and persisted.

ci.find([class], query)¶

Returns a cursor for a result set of Resource database documents. The cursor has the same methods as a database cursor.

var ci = require("cla/ci");
var rs = ci.find({ hostname: cla.regex("^127.0") });
rs.forEach(function(doc) {
    print( doc.mid );
});

Optionally, a class can be sent as a parameter to limit the search to documents that belong only to that class.

var ci = require("cla/ci");
var rs = ci.find('Status', { name: cla.regex('QA') });
print( rs.next() );

ci.findOne([class], query,options)¶

Returns the first document that matches the query.

var ci = require("cla/ci");
var doc = ci.findOne({ mid:"123" });
print( doc.mid );

Optionally, a class can be sent as a parameter to limit the search to documents that belong only to that class.

// find a document within the Status class only
var ci = require("cla/ci");
var doc = ci.findOne('Status', { name: cla.regex('^QA') });

ci.load(mid)¶

Instantiate a previously persisted Resource from the database.

ci.delete(mid)¶

Deletes a Resource with the given mid.

General availability of a class¶

To be able to fully use a Resource class outside of a rule code, the Resource class must be loaded as part of Clarive's startup process.

Put the JS file for the class in the corresponding $CLARIVE_BASE/plugin/[plugin-name]/cis folder so that it's picked up by the cla command during system startup.

Meta Programming¶

The following instrospection of the Resource class system is available:

ci.listClasses([role])¶

Returns an Array of loaded Resource classes in Clarive.

With the optional parameter role, filters the list that do a given role.

javascript var ci = require("cla/ci"); var all = ci.listClasses(); var appservers = ci.listClasses('ApplicationServer');

This is useful to check if a certain dependent module is loaded before attempting a given operation.