Name

ChangeSynergy::apiObjectData


Description

The ChangeSynergy::apiObjectData object is used to represent the details of one attribute for any given object. The XML format used to construct a instance of this class is as follows:

 <csapi_cobject_data>
	<csapi_cobject_data_name>attribute name</csapi_cobject_data_name>
	<csapi_cobject_data_value>attribute value</csapi_cobject_data_value>
	<csapi_cobject_data_type>web type</csapi_cobject_data_type>
	<csapi_cobject_data_readonly>true|false</csapi_cobject_data_readonly>
	<csapi_cobject_data_required>true|false</csapi_cobject_data_required>
	<csapi_cobject_data_inherited>true|false</csapi_cobject_data_inherited>
	<csapi_cobject_data_default>default value for this attribute</csapi_cobject_data_default>
	<csapi_cobject_data_date>formatted date</csapi_cobject_data_date>
 </csapi_cobject_data>

This object is used generically in both reporting and data show api operations. Some data elements will not have values depending on the usage. Data elements will always be undef if not set.


Methods

The following methods are available:

new
 sub new(xmlData)

Initializes a newly created ChangeSynergy::apiObjectData class so that it represents the xml data passed in.

 my $apiObject = new ChangeSynergy::objectData($xmlData);
 
 Parameters:
	xmlData  - the XML data that needs to be parsed into a usable form.
 Throws:
	die - if unable to parse the xml data
getDate

Gets the attribute date value property. Returns the time in the human readable Show date format by default MM/dd/yyyy H:mm:ss.

my $date = $apiObject->getDate();

print $date . "\n"; #ex. 02/08/2006 13:27:49

 Returns: scalar
	the attribute date property.
getDefault

Gets the default value for this attribute.

my $default = $apiObject->getDefault()

 Returns: scalar
	the default value for this attribute. The value is set in the Lifecycle editor.
getESignatures

Get the Electronic Signatures associated with this object. Will be undefined if none are set. The return result is an instance of the apiESignatures class.

my $eSigs = $apiObject->getESignatures()

 Returns: apiESignatures
	the Electronic Signatures for this object.
getFormattedUserName

Gets the formatted user name property. This will return the users display name or if not a CCM_USER attribute an empty string. This value will be the same as the getValue method unless the Username Display feature has been set to something besides just user id.

my $date = $apiObject->getFormattedUserName();

 Returns: scalar
	the formatted display user name.
getInherited

Gets the attribute is inherited property, 0 is false, 1 is true.

my $inherited = $apiObject->getInherited()

 Returns: scalar
	the attribute is inherited property.
getInheritedStr

Gets the attribute is inherited property as a string, true or false.

my $inheritedStr = $apiObject->getInheritedStr()

 Returns: scalar
	the attribute inherited property as a string
getIsModified

Gets the attribute is modified property, 0 is false, 1 is true.

my $isModified = $apiObject->getIsModified()

 Returns: scalar
	if the attribute has been modified or not.
getIsModifiedStr

Gets the attribute is modified property as a string, true or false.

my $isModifiedStr = $apiObject->getIsModifiedStr()

 Returns: scalar
	if the attribute has been modified or not property as a string.
getIsShowModified

Gets the attribute is modified property, 0 is false, 1 is true.

my $isShowModified = $apiObject->getIsShowModified()

 Returns: scalar
	if the attribute has been modified or not.
getIsSubmitModified

Gets the attribute is modified property, 0 is false, 1 is true.

my $isSubmitModified = $apiObject->getIsSubmitModified()

 Returns: scalar
	if the attribute has been modified or not.
getLabel

Gets the attribute label property

my $value = $apiObject->getLabel()

 Returns: scalar
	the attribute label property.
getName

Gets the attribute name property.

my $name = $apiObject->getName()

 Returns: scalar
	the attribute name property.
getReadOnly

Gets attribute read only property, 0 is false, 1 is true.

my $readOnly = $apiObject->getReadOnly()

 Returns: scalar
	the attribute read only property.
getReadOnlyStr

Gets the attribute read only property as a string, true or false.

my $readOnlyStr = $apiObject->getReadOnlyStr()

 Returns: scalar
	the attribute read only property as a string
getRequired

Gets attribute required property, 0 is false, 1 is true

my $required = $apiObject->getRequired()

 Returns: scalar
	the attribute required property.
getRequiredStr

Gets the attribute required property as a string, true or false

my $requiredStr = $apiObject->getRequiredStr()

 Returns: scalar
	the attribute required property as a string
getSubscription

Get the subscription information associated with this object. Will be empty object if none are set. The return result is an instance of the apiSubscription class.

my $subscription = $apiObject->getSubscription()

 Returns: apiSubscription
	the subscription information for this object.
 Example:
 
	use ChangeSynergy::csapi;
	my $csapi = new ChangeSynergy::csapi();
	eval
	{	
		$csapi->setUpConnection("http", "your_hostname", 8600);
		my $aUser     = $csapi->Login("u00001", "u00001", "Admin", "\\\\your_hostname\\ccmdb\\cm_database");
		#Show problem 22
		my $problem   = $csapi->AttributeModifyCRData ($aUser, "22"); 
		
		#Get the CCM_SUBSCRIPTION attribute called subscription1.
		my $attribute = $problem->getDataObjectByName("subscription1");
		#Get the actual subscription data.  The real value is XML.
		my $subscription = $attribute->getSubscription();
		
		eval
		{
			#Modify the user jsmith to change his real name.
			my $subscriber = $subscription->getSubscriberByUserName("jsmith");
			$subscriber->setRealName("John Smith");
		};
		
		if($@)
		{
			#Print the error message if there is one.
			print $@;
		}
		
		#Add a new user.
		$subscription->addSubscriber("cscott", "Chris Scott", "chris.scott\@company.com");
		
		#set the new XML value for subscription1.
		$problem->getDataObjectByName("subscription1")->setValue($subscription->toSubmitXml());
		
		#Modify the CR with the changes to the subscription list.
		my $ret_val = $csapi->ModifyCR($aUser, $problem);
		#Print the response from calling ModifyCR.
		print "\n" . $ret_val->getResponseData();	
	};
	
	if($@)
	{
		die "Failed to modify subscription list: " . $@;
	}
getType

Get the attribute web type property.

my $type = $apiObject->getType()

 Returns: scalar
	the attribute web type property.
	
	Can be one of the following:
      CCM_STRING
	  CCM_TEXT
	  CCM_DATE
	  CCM_USER
	  CCM_NUMBER
	  CCM_READONLY
	  CCM_LISTBOX
	  CCM_VALUELISTBOX
	  CCM_TOGGLE
	  CCM_RELATION
	  CCM_HIDDEN
	  CCM_E_SIGNATURE
	  CCM_SUBSCRIPTION
getValue

Gets the attribute value property. If the attribute is a CCM_DATE the returned value is the time in seconds since 1970 or an empty string if the attribute does not have a date currently defined.

my $value = $apiObject->getValue();

print $value . "\n"; #ex. 1139434069 for a CCM_DATE

 Returns: scalar
	the attribute value property.
getXmlData

Gets the XML data used to constuct this object.

Note: This is intended for debugging only.

my $xmlData = $apiObject->getXmlData()

 Returns: scalar
	the XML data used to constuct this object, useful for debugging purposes. 
setIsModified

Sets the "isModified" property for the class instance.

$apiObject->setIsModified($value)

 Parameters:
	value - the new value for isModified (true or false)
setLabel

Sets the "label" property for the class instance.

$apiObject->setLabel($value)

 Parameters:
	value - the new value for label
setName

Sets the "name" property for the class instance.

$apiObject->setName($value)

 Parameters:
	value - the new value for name
setType

Sets the "type" property for the class instance.

$apiObject->setType($value)

 Parameters:
	value - the new value for type
setValue

Sets the "value" property for the class instance.

Values are set exactly as given, which is most often the expected behavior. For example, if a CCM_STRING attribute is set to the value "<b>Example</b>", then that exact string, "<b>Example</b>", will be seen through the web interface since this type of attribute works with plain text.

If the attribute being set is a CCM_EXTENDED_TEXT attribute (which presents HTML text values) then setting and getting the value would still be symmetric (i.e., the value "<b>Example</b>" would still be saved and retrieved as-is), but when viewed through the web interface would be rendered simply as the word "Example" in a bold font. If you truly wanted the text "<b>Example</b>" to be displayed in the web interface, you would need to escape the special HTML characters by first calling ChangeSynergy::util::xmlEncode on data value before calling setValue.

$apiObject->setValue($value)

Also must be used when setting date values to be submitted to the server. The date values must be set in seconds since 1970. PERL dates are in seconds since 1970.

Apart from setting the value, api encodes the value if needed.

Example for setting the current time:

  #Get the current time.
  my $time = time;
  $apiObject->setValue($time);

Example for setting a time in the future or past:

  use Time::Local;
  # 5/10/2004 (mm/dd/yyyy)
  #timelocal($seconds, $minutes, $hours, $day of month, $month, $year);
  $seconds = timelocal(0, 0, 0, 10, 5, 2004);
  
  $apiObject->setValue($seconds);
  
Converting the above time back to a human readable format:  
  
  #Must add 1900 to the year to get the correct year.
  ($seconds, $minutes, $hours, $day_of_month, $month, $year, $wday, $yday, $isdst) = localtime($seconds);
  print "Reconverted Date: " . $month  . "/" . $day_of_month  . "/" . ($year + 1900);
  #Should print 5/10/2004
 Parameters:
	value - the new value for value
setXMLEncodedValue

Deprecated. Use setValue instead. Sets the "value" property for the class instance. XML encodes the value for the user, so that it does not need to be externally done.

$apiObject->setXMLEncodedValue($value)

 Parameters:
	value - the new value for value
toAttributeXml

Get XML data used to send to the IBM Rational Change server.

Used by api functions to construct the XML strings that will be submitted to the IBM Rational Change server.

my $xmlData = $apiObject->toAttributeXml()

 Returns: scalar
	the XML data to be submitted to the IBM Rational Change server.  This function
	will take all the current information in the object and translate it into XML.
toObjectXml

Get XML data used to send to the IBM Rational Change server.

Used by api functions to construct the XML strings that will be submitted to the IBM Rational Change server.

my $xmlData = $apiObject->toObjectXml()

 Returns: scalar
	the XML data to be submitted to the IBM Rational Change server.  This function
	will take all the current information in the object and translate it into XML.
toXml

Get XML data used to send to the IBM Rational Change server.

Used by api functions to construct the XML strings that will be submitted to the IBM Rational Change server.

my $xmlData = $apiObject->toXml()

 Returns: scalar
	the XML data to be submitted to the IBM Rational Change server.  This function
	will take all the current information in the object and translate it into XML.