Leveraging the custom object in IdentityIQ

[#1]

• Overview
• What is a custom object?
• How do I interact with these in the API?

Overview

Often times it is necessary to create a mapping of keys to values in IdentityIQ. While most of IdentityIQ's data models are fairly flexible and allow attributes to be placed on them; other needs can arise to have these data structures exist independently of other objects. Fortunately, in IdentityIQ this is possible through usage of the Custom object.

What is a custom object?

Simply put, it is a simple object that has an attribute map, which can be serialized / deserialized into IdentityIQ.  This is an example of what one looks like:

<?xml version='1.0' encoding='UTF-8'?>

<!DOCTYPE Custom PUBLIC "sailpoint.dtd" "sailpoint.dtd">

<Custom name="Some Custom Object">

  <Attributes>

    <Map>

      <entry key="someKey1" value="someValue"/>

      <entry key="someKey2">

        <value>

          <List>

            <String>listValue1</String>

            <String>listValue2</String>

            <String>listValue3</String>

          </List>

        </value>

      </entry>

      <entry key="someKey3">

        <value>

          <Boolean>true</Boolean>

        </value>

      </entry>

    </Map>

  </Attributes>

</Custom>

You can create these structures in XML outside of IdentityIQ and import them into the system.  Once they are there they can be used by rules, workflows, or even custom code.

How do I interact with these in the API?

Example 1: Getting a Custom object.

Custom custom = context.getObject( Custom.class, "Some Custom Object" );

System.out.println( custom.toXml() );

Example 2: Updating a Custom object.

// See if there is already a custom object, and lock it if there is.

Custom custom = (Custom) ObjectUtil.lockObject(

     context, // SailPointContext              

     Custom.class, // Object Class - Custom.class in our case

     null, // The object ID in String form

     "Some Custom Object", // The object Name in String form

     PersistenceManager.LOCK_TYPE_TRANSACTION  // The type of lock we want - either persistent or transaction. 

     );

// There was not a Custom object already in the database, let's create a new one.

if ( custom == null ) {

  custom = new Custom();

  custom.setName( "Some Custom Object" );

}

// Now add some attributes:

custom.put( "someKey1", "someValue" );

custom.put( "someKey2", Arrays.asList( new String[] {"listValue1", "listValue2", "listValue3"} ) );

custom.put( "someKey3", true );

// Do more stuff...

// Save it and commit it.

context.saveObject( custom );

context.commitTransaction();

System.out.println( custom.toXml() );

Thats it! Enjoy your new found flexibility with the custom object!

Note: Keep in mind that these are objects stored in the database. Most times when you look up or edit these objects will result in additional call(s) to the database. Use your best judgement when to utilize these API calls to avoid any potential self-inflicted performance issues.

[menno_pieters]

Hi steve.nuffer​,

This question would be better asked in the forums, but nevertheless.... These are all just nested Java objects. So from the custom object, you use the get functions to retrieve keys (or first retrieve the Attributes and retrieve items from that), then get the sub-entries from the nested Map or Attributes objects. Theoretically, you could nest a Custom object in another one, and so on.

- Menno

[#3]

Good article Neil. Thanks for sharing.

[menno_pieters]

The best place to ask these questions is in the forums, referring to this article. Otherwise only the people watching this article will get notified. The forums attract a much wider audience. That said, as I understand your question, you just need to update (clean out) the Custom object after processing. See example 2 in Neil's article.

- Menno

[james_craver]

If I create the Custom object, would I need to save it and lock it before continuing if there's a chance another thread could come along and call this rule?

[james_craver]

I will ask this in the forums

[deep]

How do we save comments in a custom object?

[menno_pieters]

If you mean XML comments, these will be stripped as soon as the object is saved, or uploaded to IdentityIQ.

If you do need to add some comments for the object as a whole, you could use the "Decription" tag, as you can see in the JavaDocs and DTD (DTD Information​), e.g.

<Custom name="myCustom">

  <Description>This is my Custom object and here is my comment: test</Description>

  <Attributes>...</Attributes>

</Custom>

- Menno

[deep]

Thanks Menno!

Yes, description tag  can be used but it will be for the entire custom object, and not for the individual entries. I was looking for something specific to entries

Thanks,

Deepa

[menno_pieters]

No, sorry. The Custom object is basically a wrapper around an Attributes object, which itself is an extension of a standard Java Map with a lot of convenience routines added. Keeping that in mind, and looking at the DTD tree for the Custom object, there is nothing other than the Description of the Custom object, that you can use:

In your source code repository, of course, you have the freedom to add any XML comments in <!-- comment tags --> like that, but once you upload that to IdentityIQ, the comments will be gone.

[deep]

Okay, Thanks!