9.3 Common SailPoint API Objects and Methods

Common SailPoint API Objects and Methods

Objective 4.7 asks you to know the common SailPoint API objects and methods and how to leverage them. The full API is in the javadocs that ship with every installation, under identityiq_home/doc/javadoc. Exam items focus on a small, high-use set.

SailPointContext: The Gateway

Every rule receives context, a sailpoint.api.SailPointContext:

Querying With Filter and QueryOptions

import sailpoint.object.*;
import java.util.*;

QueryOptions qo = new QueryOptions();
qo.addFilter(Filter.and(
    Filter.eq("department", "Finance"),
    Filter.eq("inactive", false)));
qo.addOrdering("lastname", true);
qo.setResultLimit(500);

List props = Arrays.asList(new String[] {"name", "email", "manager.name"});
Iterator it = context.search(Identity.class, qo, props);
while (it.hasNext()) {
    Object[] row = (Object[]) it.next();
    String name = (String) row[0];
    // ... row[1] is the email, row[2] the manager's name
}

• Filter static methods include eq, ne, like (with a match mode), in, and, or, not, isnull, notnull, and ignoreCase. Filter.compile("department == \"Finance\"") parses a filter string, the same syntax the Advanced Search "view/edit filter source" link shows.
• QueryOptions carries filters plus addOrdering, setDistinct, setResultLimit, and setFirstRow. The documentation's own form examples build a distinct, ordered projection query to fill a drop-down.
• Dot notation reaches related objects: manager.name, application.name, identity.department.
• Only searchable attributes (extended columns, section 2.3) can be used in database filters. Non-searchable attributes are stored in XML and cannot be queried efficiently.

The Core Object Classes

Changing Access: ProvisioningPlan

Do not edit Link attributes directly to grant access. Describe the change as a ProvisioningPlan and let IdentityIQ provision it, audit it, and keep the identity cube consistent:

import sailpoint.object.ProvisioningPlan;
import sailpoint.object.ProvisioningPlan.AccountRequest;
import sailpoint.object.ProvisioningPlan.AttributeRequest;
import sailpoint.api.Provisioner;

ProvisioningPlan plan = new ProvisioningPlan();
plan.setIdentity(identity);
AccountRequest acct = new AccountRequest(AccountRequest.Operation.Modify,
        "Active Directory", null, link.getNativeIdentity());
acct.add(new AttributeRequest("memberOf", ProvisioningPlan.Operation.Add,
        "CN=Finance,OU=Groups,DC=acme,DC=com"));
plan.add(acct);
Provisioner p = new Provisioner(context);
p.execute(plan);

AccountRequest operations include Create, Modify, Delete, Enable, Disable, Unlock, and Lock. AttributeRequest operations are Add, Remove, and Set. In a workflow, pass the plan to LCM Provisioning or a provisioning subprocess instead, so that approvals and policy checks still apply.

Helper Classes

• sailpoint.api.IdentityService – for example, getLinks(identity, application) finds an identity's accounts on one application.
• sailpoint.api.ObjectUtil – utilities such as convertIdsToNames(context, Application.class, ids), used in the documentation's report examples, plus locking helpers for safely updating identities.
• sailpoint.tools.Util – null-safe helpers such as isNullOrEmpty, isNotNullOrEmpty, otos (object to string), otob (to boolean), and CSV/list conversions.

Two Everyday Recipes

Lookup tables in a Custom object. Instead of hard-coding a department-to-cost-center map in five rules, store it once:

import sailpoint.object.Custom;
Custom map = context.getObjectByName(Custom.class, "ACME Cost Centers");
String cc = (map != null) ? (String) map.get(department) : null;

Sending an email from code. The documentation's Test Email Sending rule shows the pattern: load an EmailTemplate by name, take a copy with deepCopy(context), put template arguments in a Map, wrap the recipient and arguments in EmailOptions, then call context.sendEmailNotification(template, options). With email redirection on (section 3.4), this is a safe way to test templates.

Patterns That Separate Good Code From Outages

1. Iterate, do not load everything. Use search (ideally a projection) instead of getObjects for large sets.
2. Commit, then decache, in loops. Call commitTransaction() after saves and decache() every few hundred objects, so the session does not grow until memory runs out.
3. Never commit inside certain rules unless required. Aggregation, correlation, and customization rules run inside IdentityIQ's own transaction. Return data and let the engine save it.
4. Handle nulls. Attributes and managers may be missing, so use Util helpers.
5. Log at debug, not println. The documentation suggests println only for temporary debugging, removed before production. Prefer a named logger (section 14.1).