Class Record

The Record class represents the next record (or partial record) in the inbound data stream from some event source. There are a number of attributes and methods defined for this class, but for the most part it is used as a general storage container for the data in the input record plus all strings parsed out of that data.

This constructor only sets pre-defined default attributes; in most cases you will use the Connector.read() method to fetch an actual populated record. In fact, the template will usually do this for you at the beginning of each loop.

The Connector will set various attributes in the Record object according to the input. Note that if there are multiple Connectors sending data to the Collector, they will all feed the same queue; you can determine which Connector sent you the data by the UUID or the connection mode.

Connectors in general operate in one of two modes which will affect what the received record looks like:

Buffer string mode: In this mode, the input from the event source is presented as a single string, which will be in rec.s_RXBufferString. If the event source produces complex data output, it may be pre-processed into NVP format.
Map mode: The input from the event source is placed into several variables, with names determined by the Connector. The DB Connector, for example, will return a variable for each column returned by the query.

In addition to the s_RXBufferString and data map variables, there are also a number of additional defaults that most Connectors will set in the input map:

rec.CONNECTION_METHOD: The type of Connector that delivered the data
rec.CONNECTION_MODE: The connection mode in use by that Connector - this may affect the format of the data.
rec.i_RXBufferLength: If s_RXBufferString is set, this is the length of that string. Can be used to determine if an empty record was retrieved.
rec.s_raw_message: A copy of the raw message recieved. This is used by the signing feature.
rec.o: Used as a status variable to indicate the state of the Connector.
rec.s_RV21: The UUID of the Collector Manager that this Collector is running on.
rec.s_RV22: The UUID of this Collector instance.
rec.s_RV23: The UUID of the Connector delivering this data.
rec.s_RV24: The UUID of the Event Source from which this data was captured.
rec.s_RV25: A UUID assigned to this data record.

For most of these variables, the template will handle processing them. You can use rec.CONNECTION_METHOD and rec.CONNECTION_MODE to select the appropriate parsing methods, and rec.i_RXBufferLength to check for error conditions.

Defined in: record.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	Record() Constructs a new instance of a Record object.

Field Summary
Field Attributes	Field Name and Description
	connectorData Dummy connector data object to pass to fireEvent(); will be replaced when data is read in most cases
	RXMap Empty object to hold field-based structured input

Method Summary
Method Attributes	Method Name and Description
	convert(output, map) Converts a Record object into another object.
	customParse(e) This method is used to provide locally-defined custom parsing of the input record.
	customPreparse(e) This method is used to provide locally-defined custom pre-parsing of the input record.
	normalize(e) The normalize() method is used to convert data elements from the input record into Sentinel-friendly data, typically by using external translation files to look up the data or by performing simple data manipulation.
	parse(e) The parse() method is used to perform the main parsing on the input record.
	postParse(e) The postParse() method performs any necessary post-processing steps after the input record is converted into the output event, but before the event is actually sent.
	preParse(e) The preParse() method should be used to perform preliminary data cleaning prior to the main parsing step.
	reply(e) The reply method should be used to perform any final acknowledgement to the Connector that might be necessary.
	sendUnsupported(e) This method sends a generic unparsed event where minimal processing is performed.

Class Detail

Record()

Constructs a new instance of a Record object.
Author: Novell Engineering.

Field Detail

{ConnectorData} connectorData

Dummy connector data object to pass to fireEvent(); will be replaced when data is read in most cases

RXMap

Empty object to hold field-based structured input

Method Detail

{Boolean} convert(output, map)

Converts a Record object into another object. This method defaults to converting to an output Event, but can be used to convert input into other objects like Identities, Assets, Vulnerabilities, etc.

Example:

// Usually the template will take care of conversion of your completely parsed record into
// the output event. But in case you need to convert to some other type of object:
rec.convert(outputID, instance.MAPS.Rec2ID);

Parameters:
{Object} output: The object that the Record will be converted into.
{DataMap} map: The map to be used for the conversion.

Returns:: {Boolean} Result of conversion attempt

See:: DataMap

customParse(e)

This method is used to provide locally-defined custom parsing of the input record. NOTE: There are two types of modifications that are typically peformed:

Modifications to the output of existing event fields: in this case, you may need to debug the Collector to determine which Record attribute is used to hold the data, and then perform your custom transformation on that data. For example:

// Main code sets rec.evt to raw event name from device, but these overlap with
// event names from other devices in our environment so are hard to distinguish.
// We will add a prefix to help identify the events
this.evt = "FW: " + this.evt;

Additional custom parsing that pulls more specific pieces of information out of the event, for example if a free-text field contains some info that you want to use to categorize events in your environment. In this scenario, you should:
- Only use CustomerVars to hold the parsed-out data
- You will need to manipulate the Event object directly, as new additions to the Record object will be lost. The 'e' variable is used to access the Event object.
Use the 'CustomerVar1' through 'CustomerVar300' to hold your data. Refer to the documentation for the datatypes of those variables.
```
// Want to extract the Department name that is injected into the "message" field
e.CustomerVar21 = rec.message.substr(12,34);
```
Defined in: collector.js.

Parameters:
{Object} e: The output event

customPreparse(e)

This method is used to provide locally-defined custom pre-parsing of the input record. You might use this method if something in your environment modifies the normal input format, for example if the event is tunneled through some other protocol, you might strip off any additional headers that were added.
Defined in: collector.js.

Parameters:
{Object} e: The output event

{Boolean} normalize(e)

The normalize() method is used to convert data elements from the input record into Sentinel-friendly data, typically by using external translation files to look up the data or by performing simple data manipulation. Most of your normalization can be done in the Record object, but the output event 'e' is provided for your convenience if you wish to place your translated data in it directly. In general, however, it is safer and more convenient to do your work in the Record object, then just let convert() do the conversion to the output event.

Example: // Note: not an example of usage, but of implementation: Record.prototype.normalize = function(e) { this.inpArray = []; this.inpArray = this.safesplit(","); return true; }
Defined in: release.js.

Parameters:
{Event} e: The current instance of the output event; this is in general not used directly but is provided for reference or for presetting fields.

Returns:: {Boolean} Whether the parse() method completed without errors.

{Boolean} parse(e)

The parse() method is used to perform the main parsing on the input record. The focus here should be to break the input up into small data units that can be easily mapped to the Sentinel event structure in the convert() method.

Example: // Note: not an example of usage, but of implementation: Record.prototype.parse = function(e) { this.inpArray = []; this.inpArray = this.safesplit(","); return true; }
Defined in: release.js.

Parameters:
{Event} e: The current instance of the output event; this is in general not used directly but is provided for reference or for presetting fields.

Returns:: {Boolean} Whether the parse() method completed without errors.

{Boolean} postParse(e)

The postParse() method performs any necessary post-processing steps after the input record is converted into the output event, but before the event is actually sent. In general this function will not be necessary, but is provided for special cases.

Example: // Note: not an example of usage, but of implementation: Record.prototype.postParse = function(e) { var d = new Date(); e.EndTime = Date.getTime(); return true; }
Defined in: release.js.

Parameters:
{Event} e: The current instance of the output event, which should have a complete set of data in it already.

Returns:: {Boolean} Whether the postParse() method completed without errors.

{Boolean} preParse(e)

The preParse() method should be used to perform preliminary data cleaning prior to the main parsing step. For example, you might need to strip end-of-record characters, replace unsafe characters, check to make sure you have a full record, filter out certain events, etc. You should also check for error conditions coming back from the Connector, which are typically recorded in rec.connErr.

Example: // Note: not an example of usage, but of implementation: Record.prototype.preParse = function(e) { if( rec.connErr != "" ) { return false; } this.replace(/\n/, "")); return true; }
Defined in: release.js.

Parameters:
{Event} e: The current instance of the output event, this is in general not used directly but is provided for reference or for presetting fields.

Returns:: {Boolean} Whether the preParse() method completed without errors.

{Boolean} reply(e)

The reply method should be used to perform any final acknowledgement to the Connector that might be necessary. In general this method is not used, but is provided for special cases.

Example: // Note: not an example of usage, but of implementation: Record.prototype.reply = function(e) { conn.send("Event sent successfully\n"); return true; }
Defined in: release.js.

Parameters:
{Event} e: The current instance of the output event that was just sent.

Returns:: {Boolean} Whether the reply method completed without errors.

{Boolean} sendUnsupported(e)

This method sends a generic unparsed event where minimal processing is performed. In general this method is used to report unrecognized or unsupported records received from the event source. Collectors are typically written to support the most common events received from a particular source; in many cases infrequent events or events caused by add-on modules are not parsed by the default Collector code.

Note that there are two template parameters which control unparsed events:

Report Unparsed Events: This turns on/off the reporting of unparsed (unsupported) events.
Unparsed Events Severity: The reported severity of unparsed events.

When developing a Collector, you will usually want to attempt to parse the input records, and then call this method of the attempt is unsuccessful. In fact, the original template code has an example of this: see the parse() method which calls this method and then returns false to halt processing of this record.

Parameters:
{Event} e: An Event object (optional) to use as the basis for the unparsed event. Will default to the global 'curEvt' object.

Returns:: {Boolean} Whether an event was set or not.

Classes

Class Record