Keys

Keys are used to uniquely identify an object in the Netcool Configuration Manager - Base data store, and can be used to retrieve that object or in some cases to retrieve specific data about the object.

In actual practice, ResourceDescriptors (described in detail later in the document), are used more frequently in the API to search for and fetch Netcool Configuration Manager - Base resources. Keys are still frequently used to fetch ResourceDescriptors. Examples of keys are: NetworkResourceKey, ConfigurationKey, CommandSetKey, RealmKey or ResourceContainerKey.

From a practical viewpoint, keys fall into the following general categories:

  • ResourceContentKeys that represent any type of resource except a realm or a UOW.
  • ResourceContainerKeys that represent realms.
  • WorkKeys that represent UOWs.

Keys of types that represent actual Netcool Configuration Manager - Base data typically have two methods used to return information that can be used to identify the resource, and that have potentially misleading names for reasons related to backward compatibility with earlier versions of the Netcool Configuration Manager - Base API, where the Netcool Configuration Manager - Base used an LDAP directory as a data store. These two methods are:

  • getDistinguishedName — This typically returns the unique key for the resource in some table in the underlying database.
  • getFriendlyname — This typically returns the name by which the resource is known to GUI users. Or it can also return the ID for a UOW, the name of a NetworkResource or the name of a generic resource such as an authentication.

Typically, a key can be stored as a string and the appropriate data factory can then be used to create a Key from that string that can be used as a parameter in API methods. The toString method for a key typically returns the same string as the getDistinguishedName method. As an example, when tracking the state of a UOW, a WorkKey can be created by calling the new WorkKey(String dn) constructor on WorkflowDataFactory and passing in the String that was returned from the toString or getDistinguishedName method on the original WorkKey. The new WorkKey can then be used to fetch the UOW (Work) object by calling getWork(WorkKey key).

Note: It is also possible in this case to fetch the UOW by its UOW ID, obtained by calling the getFriendlyname method on the original WorkKey. In current Netcool Configuration Manager versions, the API typically provides methods to fetch UOWs based on their UOW ID instead of their Key, so it may be simpler to persist the UOW ID than the toString value of the WorkKey for the UOW.