JavaScript function: removeFromGroup

Removes one or more configuration items (CI) from a Configuration Management list group.

Syntax

lib.ciGrouping.removeFromGroup( 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 remove. To remove an array of CIs, the ci argument must be an SCFile or SCDatum object. To remove a single CI, you can specify it as a string.
groupName	String	Yes	This argument contains the name of the configuration group from which you want to remove CIs.

Return values

A numerical value: 0, 1, or -1.

The function returns 0 if it is unable to remove CIs from the list group or if the groupName argument specifies a query group. The function returns 1 if the function successfully removes CIs from the list group. The function returns -1 if it cannot remove CIs from the list group because the action would result in an empty configuration list group.

Description

This function is part of a system JavaScript and should not be directly modified.

This function removes one or more CIs from a configuration list group and updates the list group record if successful.

Example

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

• A string containing a single CI record
• A configuration group record containing one or more CIs
• A Datum object containing an array of CI records

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 remove records from.
*  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 remove.
*  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 testRemove( ci, group )
{
 var groupMembers = lib.ciGrouping.returnGroupMembers( group )
 var removeCI = lib.ciGrouping.removeFromGroup( ci, group );
 var afterRemove = lib.ciGrouping.returnGroupMembers( group );
 print( "Now trying to remove configuration item(s) from " + group + "..." );
 print( "The current members of " + group + " are:\n" + groupMembers );

 if ( removeCI == 1 )
 {
  print( "Successfully removed configuration item(s) to " + group );
  print( "The members of " + group + " are now: \n" + afterRemove );
 }
 else
 {
  if ( removeCI == "-1" )
  {
   print( "Could not remove configuration item from " + group + " as "
         + ci + " is the last member of the group." );
   print( "The members of " + group + "are : \n" + groupMembers );
  }
  else
  {
   print( "Could not remove configuration item from " + group + ".\n"
         + ci + " or " + group + " does not exist.");
  }
 }
}

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

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

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

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