CA SDM Objects

This article contains the following topics:
casm1401
This article contains the following topics:
CA SDM treats each entity, such as a contact or an issue, as an
object
. These high-level objects are defined in majic (.maj) and mod (.mod) files on the CA SDM server in the following directory:
/bopcfg/majic
Customized objects are defined in the following directory:
/site/mods/majic
Objects are essentially high-level wrappers around a database table.
An object’s type (sometimes referred to as
factory
) defines the object. For example, request objects belong to the ‘cr’ type. Each object’s type is defined by the “OBJECT” declaration in a majic file.
All objects shipped with CA SDM are enumerated in the CA Service Desk Manager Reference Commands section.
An object has
attributes
, which are essentially columns in a database table (do not confuse these with XML attributes). Web Services offers many methods to retrieve values for attributes. Many methods require you to name attributes for setting or retrieving values. You must use the attribute name assigned in the majic or mod file that defines the object, which can be different from the actual database name. Client sites can add additional attributes as a customization.
For a list of all the attributes for each object, see the CA Service Desk Manager Reference Commands section.
Web Services uniquely identifies an object by its
handle,
which is a string value of the form
objectType:ID
, where
objectType
is the object’s type (factory) name, and ID is a unique value. The ID value matches that of the ‘id’ attribute found in every CA SDM object. Because the ‘id’ attribute is almost always indexed in the DBMS, using the ID portion of the object handle is especially valuable for forming efficient queries. Each object, regardless of its type, stores this value in an object attribute named “persistent_id”.
In prior releases, the ID portion of the handle was always a string of integers. In CA Service Desk r11.0 and later, the ID portion may also be the string representation of a UUID, typically 32 characters.
The following information lists the object and factory names of the entities that use UUIDs:
Object Name
Factory Name
Contact
cnt
Asset
nr
Organization
org
Location
loc
Company/Vendor
ca_cmpny
Model
mfrmod
Handles are
persistent;
a handle representing a particular object is always unique for its lifetime, even across database migrations. Clients may want to take advantage of this persistence when working with fairly static objects, for example, Status or Contact Types.
Object handles are the key to using CA SDM Web Services. Many methods, especially those that update data, require handles. Most methods that return object data also include the object’s handle.
System Updates and Caching
Web Services caches information for object types. Type information is not cached until the type is referenced for the first time, and will cause a small delay.
To avoid any server or caching delays, you may want to run a primer client to activate the Web Services and cache the most popular object type information. The easiest way to cache the object type information is to perform repeated calls to GetObjectTypeInformation(). The object types to consider for this technique could be one of the following:
Object Type
Definition
cr
Request
chg
Change Order
iss
Issue
cnt
Contact
nr
Asset
prp
Property (for Change and Issue)
prptpl
Property Template (for Change and Issue)
cr_prp
Request Property
cr_prptpl
Request Property Template
cr_wf
Classic Workflow (Request/Incident/Problem)
Add any additional object types your client code references.
Categories and Properties
The request, change order and issue objects all have a category field, which is used to classify the nature of the ticket. A category may have property objects, which are attached to the ticket when the category is assigned. Some of these may be marked
required
, which means a value must be supplied before the ticket can be saved (applies to both insert and update operations).
CA SDM Web Services automatically supplies default values for any ticket created with the Web Services. The default value (currently, “-“) is obtained from the CA SDM localized message catalog.
If you need to set property values at creation time, there are three ticket creation methods: createChangeOrder, createIssue, and createRequest. Each has a parameter with which you can pass in values for any properties. To discover which properties will be attached, you must find out the properties associated with the category you intend to assign to the ticket. The easiest method to use is getPropertyInfoForCategory().
For more information about the getPropertyInfoForCategory(), see the CA Service Desk Manager Reference Commands section.
To identify the valid values for a property, first find the property validation rule for the appropriate property template. To do this, request the validation_rule attribute when calling the getPropertyInfoForCategory method. Then, retrieve the associated validation_type for that rule. If the type is dropdown, you can then use the getRelatedList method to retrieve the values associated with the rule, using the "values" BREL attribute in the prpval_rule object.
For more information, see the CA Service Desk Manager Reference Commands section.
To set property values after an update operation with updateObject(), you must query the property list after the update. getRelatedList() can help with this task.
Validation of property values through Web Service methods is not currently supported. For example, to assign property values to a validation rule with a validation type of drop-down option, you would have to write additional code to create property values while creating the drop-down option validation rule. Do not attach a property value to a check box validation rule.
For more information about property validation rules, see the Define a Category or Area. For information about creating property validation rules through the CA SDM interface, see Create Property Validation Rules in Setting Up Category or Area section.
XML Object Returns
Many of the Web Services methods return an XML representation of CA SDM objects. The Web Services uses a standard XML structure beginning with the following root element:
<UDSObject>
The format of the XML representation is described in the following table:
XML Element
Type
Description
<UDSObject>
N/A
Identifies the root node.
<Handle>
String
Identifies the object’s handle.
<Attributes>
Sequence
Identifies the attribute values. This holds zero or more elements for the object’s attribute values.
<
attrName0
DataType =
“typeEnum">
String
Identifies the
AttrName0,
which is an object attribute name as defined in the CA SDM majic (.maj) or mod (.mod) file.
This name may use dot-notation depending on the web method used.
The element’s value is the attribute’s value. An empty element indicates a null/empty value for this object’s attribute.
The DataType attribute is an integer indicating the attribute’s data type in the CA SDM environment.
For example, a call to getObjectValues() can return information illustrated by the following:
<UDSObject> <Handle>cnt:555A043EDDB36D4F97524F2496B35E75</Handle> <Attributes> <Attribute DataType="2003"> <AttrName>first_name</AttrName> <AttrValue>first name</AttrValue> <DisplayValue>Yaakov</DisplayValue> </Attribute> <Attribute DataType="2005"> <AttrName>organization</AttrName> <AttrValue>342</AttrValue> <DisplayValue>Accounting Crew</DisplayValue> </Attribute> </Attributes> <Lists> <List name="mylist1"> <UDSObject>...</UDSObject> <UDSObject>...</UDSObject> </List> </Lists> </UDSObject>
Some methods, such as doSelect(), return a sequence of <UDSObject> elements contained inside a <UDSObjectList> element.
The <Lists> section holds zero or more <List> nodes. A <List> node holds zero or more <UDSObject> nodes. <List> elements are generally returned only when a specific request for list values is made.
When you want to return a list of values related to a specific object, you should use the
getRelatedListValues
method.
If a request is made just for a list with no attribute name, such as actlog, then the entire <UDSObject> is returned in the <List> section.
Specialized methods, like getDocument(), can of course be different. When a request is made for an attribute, the database value is returned. For SREL attributes, this may not be so useful. Requesting the assignee attribute of a Request returns an integer because the Contact REL_ATTR (foreign key) is its ID. For CA Service Desk r11.0, the return data for attributes includes elements for the DBMS and common name value of SREL references.