ChangeSynergy::apiObjectData
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.
The following methods are available:
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
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.
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.
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.
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.
Gets the attribute is inherited property, 0 is false, 1 is true.
my $inherited = $apiObject->getInherited()
Returns: scalar the attribute is inherited property.
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
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.
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.
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.
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.
Gets the attribute label property
my $value = $apiObject->getLabel()
Returns: scalar the attribute label property.
Gets the attribute name property.
my $name = $apiObject->getName()
Returns: scalar the attribute name property.
Gets attribute read only property, 0 is false, 1 is true.
my $readOnly = $apiObject->getReadOnly()
Returns: scalar the attribute read only property.
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
Gets attribute required property, 0 is false, 1 is true
my $required = $apiObject->getRequired()
Returns: scalar the attribute required property.
Gets the attribute required property as a string, true or false
my $requiredStr = $apiObject->getRequiredStr()
Returns: scalar the attribute required property as a string
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: " . $@; }
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
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.
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.
Sets the "isModified" property for the class instance.
$apiObject->setIsModified($value)
Parameters: value - the new value for isModified (true or false)
Sets the "label" property for the class instance.
$apiObject->setLabel($value)
Parameters: value - the new value for label
Sets the "name" property for the class instance.
$apiObject->setName($value)
Parameters: value - the new value for name
Sets the "type" property for the class instance.
$apiObject->setType($value)
Parameters: value - the new value for type
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
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
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.
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.
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.