JavaScript function: addToGroup

This function adds one or more configuration items (CIs) to a Configuration Management list group and updates the list group record if successful. It is part of a system JavaScript and should not be directly modified.

Syntax

lib.ciGrouping.addToGroup( ci, groupName );

Arguments

The following arguments are valid for this function:

Name	Data type	Required	Description
ci	Datum object or string	Yes	This argument contains the CI records you want to add. To add an array of CIs, the ci argument must be an SCFile or SCDatum object. To add a single CI, you can specify it as a string.
groupName	String	Yes	This argument contains the name of the configuration group to which you want to add CIs.

Return values

A numerical value: 0 or 1.

The function returns 0 if it is unable to add CIs to the list group or if the groupName argument specifies a query group. The function returns 1 if the function successfully adds the CIs to the list group.

Example

This example attempts to add CIs to a list group from the following sources:

• The logical.name value from a hard-coded string
• The logical.name value from a configuration group record
• The logical.name values from an array of CI records
• The logical.name values from a record list of one or more CIs

This example requires the following sample data:

• Create a list group containing a single configuration item (for example, a list group called "test01" containing the configuration item "DEFAULT Phone 0001")
• Create a list group containing one or more configuration items (for example, a list group called "test02" containing the configuration item "DEFAULT Phone 0003")
• Create a list group containing one or more configuration items (for example, a list group called "test03" containing the configuration items "HH-000001" and "HH-000002")

/* Create variables to store CI group names, strings, and datum objects.
*  Use targetCIGroup to store the name of CI group you want to add records to.
*  Use sourceCIGroup to store the name of CI group you want to create an array from.
*  Use oneLogicalName to store a string containing a logical.name you want to add.
*  Use deviceType to store a device type you want to query for.
*  Use startsWith to store a alphabetical value you want to query for.
*  The variable recordTest stores the output of the findCIGroup function.
*  The variable arrayTest stores the output of the createArray function.
*  The variable recordListTest stores the output of the findRecordList function. */
var targetCIGroup;
var sourceCIGroup;
var oneLogicalName;
var deviceType;
var startsWith;
var recordTest;
var arrayTest;
var recordListTest;

/* Create a function to store a particular CI group in memory. */
function findCIGroup( ciGroup )
{
 print( "Looking for CI Group " + ciGroup + "..." );
 var members = lib.ciGrouping.returnGroupMembers( ciGroup )
 var ciGroupRecord = new SCFile( "cigroup" );
 var queryTest = ciGroupRecord.doSelect( "logical.name=\"" + ciGroup + "\"" )
 if ( queryTest == RC_SUCCESS )
 {
  system.vars.$L_file = ciGroupRecord
  print( "Found CI group record for " + ciGroup + "\nThe record is:\n" + ciGroupRecord );
  print( "The current members of " + ciGroup + " are:\n" + members );
  return ciGroupRecord
 }
 else
 {
  print( "Cannot find record for " + ciGroup + ". " +  RCtoString( queryTest ) + "." );
  return null;
 }
}

/* Create function to find a record list based on a device type and starting query */
function findRecordList( deviceType, query )
{
 var ciRecordList = new SCFile( "device" );
 if ( query != null )
 {
  print( "Looking for CIs matching type=\"" + deviceType + "\"\&" + "logical.name#\"" + query + "\"" );
  var queryTest = ciRecordList.doSelect( "type=\"" + deviceType + "\"\&" + "logical.name#\"" + query + "\"" )
 }
 else
 {
  print( "Looking for CIs matching type=\"" + deviceType + "\"" );
  var queryTest = ciRecordList.doSelect( "type=\"" + deviceType + "\"" )
 }
 if ( queryTest == RC_SUCCESS )
 {
  print( "Found the following CIs:\n" + ciRecordList );
  system.vars.$L_file = ciRecordList
  return ciRecordList;
 }
 else
 {
  if ( query != null )
  {
   print( "Cannot find records matching query: device=\""+ deviceType + "\"&logical.name#\"" + query + "\""
          +  RCtoString( queryTest ) + "." );
   return null;
  }
  else
  {
   print( "Cannot find records matching query: device=\""+ deviceType + "\"" +  RCtoString( queryTest ) + "." );
   return null;
  }
 }
}

/* Create a function to store the logical.names of the record. */
function createArray( record )
{
 var arrayOfLogicalNames = record.group_members;
 if (arrayOfLogicalNames == null )
 {
  print( "Cannot create array from " + record + ". Group not in the cigroup table." );
  return null
 }
 else
 {
  print( "Created array from " + record + ".\nThe array is:\n" + arrayOfLogicalNames );
  return arrayOfLogicalNames
 }
}

/* Create a function to call the addToGroup function and print results. */
function testAdd( ci, group )
{
 var groupMembers = lib.ciGrouping.returnGroupMembers( group )
 var AddCI = lib.ciGrouping.addToGroup( ci, group );
 var afterAdd = lib.ciGrouping.returnGroupMembers( group );
 print( "Now trying to add configuration item(s) to " + group + "..." );
 print( "The current members of " + group + " are:\n" + groupMembers );

 if ( AddCI == 1 )
 {
  print( "Successfully added configuration item(s) to " + group );
  print( "The members of " + group + " are now: \n" + afterAdd );
 }
 else
 {
  print( "Could not add configuration item(s) to " + group );
  print( "The members of " + group + "are : \n" + groupMembers );
 }
}

/* Test adding a CI to a group from a string */
print( "Now testing adding a single CI from a string...\n" );
targetCIGroup = "test01";
oneLogicalName = "DEFAULT Phone 0002";
members = lib.ciGrouping.returnGroupMembers( targetCIGroup )
testAdd( oneLogicalName, targetCIGroup );

/* Test adding a CI to a group from an existing CI record */
print( "Now testing adding a CI member from a CI group record...\n" );
targetCIGroup = "test01";
sourceCIGroup = "test02";
recordTest = findCIGroup( sourceCIGroup );
if ( recordTest != null )
{
 testAdd( system.vars.$L_file, targetCIGroup );
}

/* Test adding one or more CIs from an array of logical,names */
print( "Now testing adding one or more CIs from an array of logical names...\n" );
targetCIGroup = "test01";
sourceCIGroup = "test03";
recordTest = findCIGroup( sourceCIGroup );
if ( recordTest != null )
{
 arrayTest = createArray( recordTest );
 testAdd( arrayTest, targetCIGroup );
}

/* Test adding one or more CIs to a group from a CI record list */
print( "Now testing adding one or more CIs from a CI record list...\n" );
targetCIGroup = "test01";
deviceType = "furnishings"
startsWith = null;
recordListTest = findRecordList( deviceType, startsWith );
if ( recordListTest != null )
{
 testAdd( system.vars.$L_file, targetCIGroup );
}