LREL Methods

This article contains the following topics:
casm172
This article contains the following topics:
LREL methods supply information about object relationships. Objects with relationships have a left-hand side (lhs) and right-hand side (rhs) definition to describe many-to-many relationships. Some examples of many-to-many relationships include the following:
  • Issues and configuration items
  • Contacts and configuration items
  • Task types and status codes
When working with LREL methods, the BREL or LREL attribute describe many-to-many relationships. The BREL attribute replaces the LREL attribute to define many-to-many relationships. However, the LREL attribute remains backward compatible with previous releases. You declare each relationship in a .maj file and then your code uses the LREL methods, such as
CreateLrelRelationship()
, with the existing web service client code.
When working with group object management, you can use the special web methods to define a member that belongs to a group.
You declare the relationship using the BREL attribute to define relationships in majic files. For example, the following statement declares a many-to-many relationship for the Change Order (chg) object in change.maj:
asset BREL lrel_asset_chgnr chg {LREL nr;};
The
BREL
attribute for the change order named, "asset" is a list of all associated configuration items. The optional, LREL flag is an attribute that describes a set of owned resources. The corresponding majic definition of the Configuration Item (nr) includes the following:
chgnr BREL lrel_asset_chgnr nr {LREL chg;};
The
chgnr
attribute is a list of all change orders for a configuration item.
In your code, you can discover how many configuration items are associated with a change order, call
getLrelLength()
with the following parameters:
getLrelLength(sid, ChangeHandle, "asset")
You use the
sid
parameter for the Service ID from a login method. The
ChangeHandle
parameter is a string handle to a particular change order. Similarly, the following statement describes how to get the names of all configuration items that are related to a change order:
String attrs[] = {"name"}; getLrelValues(sid, ChangeHandle, "asset", 0, -1, attrs);
The
getLrelValues()
method provides the relationships in the
attrs
array.
For more information about LREL tables and objects, see the Data Element Dictionary and Objects and Attributes.
getLrelLength
The following parameters apply to the getLrelLength method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
contextObject
String
Identifies the object on one side of the LREL.
LrelName
String
Identifies the LrelName. Use the name.
Description
Returns the number of objects on one side of a many-to-many relationship:
  • contextObject
    Specifies it as a handle to an object on one side of the LREL relationship.
  • LrelName
    Specifies it as the name of the side of the relationship identified by
    ObjHandle
    .
Returns
The following:
XML Element
Type
Description
<Length>
Integer
Specifies the number of objects.
 
getLrelValues
The following parameters apply to the getLrelValues method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
contextObject
String
Identifies the object on one side of the LREL.
LrelName
String
Identifies the Lrel Name. Use the name.
startIndex
Integer
Identifies the position in the “list” from which to begin fetching.
endIndex
Integer
Identifies the Last “list” position from which to fetch. Specify -1 to fetch all rows from startIndex.
attributes
String[]
Identifies an array of one or more attribute names for which to fetch values.
Description
Returns attribute values for a range of objects in an LREL relationship. Remember that items involved in an LREL relationship have no specific ordering. In fact, it is not really a “list”, as defined in this document.
The start and end index parameters are there to help throttle a large number of items. The format is as follows:
< UDSObjectList > <UDSObject> <Handle> <AttributeName0> <AttributeName1>
Returns
This method has the following returns:
XML Element
Type
Description
<UDSObjectList>
Array
Specifies the outer element, which contains a sequence of <UDSObject> elements.
Sequence
Contains a <Handle> element and zero or more
<AttributeNameX
> elements.
 
createLrelRelationships
The following parameters apply to the createLrelRelationships method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
contextObject
String
Identifies the object on one side of the LREL.
LrelName
String
Identifies the Lrel Name as seen by
contextObject
.
addObectHandles
String[]
Identifies the handles of objects for the other side of the LREL relationships.
Description
Adds one or more many-to-many relationships.
contextObject
is one side of the LREL relation. The caller passes one or more object handles for the other side.
If a relationship already exists between the two objects, no change is made and the system continues to process the
addObjectHandles
array. If an invalid object handle is passed, the entire operation is canceled.
The following example shows how to add several assets to a contact’s environment:
createLrelRelationships(sid, ContactHandle, "cenv", ["nr:655A043EDDB36D4F97524F2496B35E75", "nr:755A043EDDB36D4F97524F2496B35E75"]) ContactHandle is a string handle to a contact, and "nr:655A043EDDB36D4F97524F2496B35E75" and "nr:755A043EDDB36D4F97524F2496B35E75" are Asset handles.
Returns
Nothing.
removeLrelRelationships
The following parameters apply to the removeLrelRelationships method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
contextObject
String
Identifies the object on one side of the LREL.
LrelName
String
Identifies the Lrel Name (as seen by
contextObject).
removeObjectHandles
String[]
Identifies the handles of objects to remove from the other side of the LREL relationships.
Description
Removes one or more many-to-many relationships.
contextObject
is one side of the LREL relationship. The caller passes one or more object handles for the other side.
It is not an error if no relationship existed between the two objects. If an invalid object handle is passed, the entire operation is canceled.
For a usage example, see createLrelRelationships() in this chapter.
Returns
Nothing.