developerworks > My developerWorks > Dashboard > Tivoli Identity Manager > ... > Related Resources > IBM Tivoli Identity Manager API Scripting Tool Examples

IBM Tivoli Identity Manager API Scripting Tool Examples

Browse Space

Added by tcaswell, last edited by sblinn on Sep 28, 2009 (view change)

Identity Manager

The following attachments provide examples on how to use the IBM Tivoli Identity Manager API Scripting Tool (aka: apiscript) tool. A dynamic role, AIX adapter TDI service, and provisioning policy can be created with the examples, as well as some examples of role membership add and remove:

Create a dynamic role - create_dynamic_role.py
Create a service - create_service_and_reconciliation.py
Create a provisioning policy - create_provisioning_policy.py
Add or remove people to a static organizational role - test_add_person_to_role.py test_remove_person_from_role.py
Create services using a loop - create_service_and_reconciliation_loop.py services.txt
- The loop concept can be applied to any script - roles, services, provisioning policies, etc.
Change the owner for a Service - test_update_svc_owner.py
- Script also contains example of passing command line parameters.
Update the description for a specific service passing parameters as commmand line arguments - test_update_svc_desc_cmdline.py
Update the service description taking input from a file. - test_update_svc_desc.py svc-descriptions.txt
Print provisioning policy entitlement information - printProvisioningPolicyEntitlements.py
Update an existing dynamic role - modify_dynamic_roles.py
Update an existing provisioning policy - modify_provisioning_policy.py
Create an Account using command line args for eruid, owner & service - test_create_account.py

The commands are invoked by using "apiscript(.sh)/(.bat) -f (filename)" so if you wanted to create a dynamic role on an AIX platform you would use "apiscript.sh -f create_dynamic_role.py".

Notes:

5.0.0.4

apiscript.ksh handles "multiple word" command-line arguments incorrectly: replace $* with "$@" (quotes necessary) to preserve "multiple word" command-line arguments on UNIX. This will be fixed in the next OPAL refresh.
apiscript.ksh|bat do not include itim_server.jar in the classpath, which prevents use of com.ibm.itim.workflow.provisioning.ProvisioningQueryStatement
in WorkflowSearchMO statements: add the jar to the classpath or to your custom classpath setup in env_master or env_hostname.
there is a bug in orgchart.py which makes "do_create_ad_from_args" and "do_create_ad_from_dict" fail; change "return do_create_ad" to "return do_create_ou" in the implementation to fix. This will be fixed in the next OPAL refresh.
support is missing in the ease-of-use functions in the person utility module for subtree search. You can search subtrees by using "get_default_person_mgr()" and calling the appropriate API directly.

Comments (Hide)

Hi
On my test server the command find /usr/IBM -name apiscript.sh -print does not find apiscript.sh.
Can you provide a link to download this file / package. Rgds Andy

Posted by Andyp at Feb 11, 2009 12:15 | Permalink

The apiscript tool is a separate download. I've updated this page to add a link from here as well as from the Related Resources page.

Posted by cpeel at Feb 11, 2009 12:27 | Permalink

I am successfully running apiscript from one of my WAS cluster nodes which are running ITIM.

Is it possible also run apiscript from a remote systems such as a laptop of desktop PC ?
If so what client code and setup is required ?

Posted by Andyp at Feb 24, 2009 11:06 | Permalink

It is certainly possible to run from remote systems such as laptops. While many setups are possible, the easiest would be:

1. on the client, install WAS of the same fixpack level as your ITIM WAS server
2. on the client, copy the TIM/lib/*.jar files which are referenced in the apiscript classpath from your ITIM WAS server (jlog.jar, api_ejb.jar, itim_api.jar, itim_common.jar)
3. on the client, copy the TIM/data/* files from your ITIM server (only a few properties are actually used)
4. on the client, copy the TIM/extensions/examples/apps/bin/jaas_login_was.conf file from your ITIM server

Instead of steps 2-4 you could also on the client install TIM, cancel DBConfig, LDAPConfig, and runConfig, and copy the TIM/data/* files from your ITIM server.

Posted by sblinn at Mar 25, 2009 21:40 | Permalink

Could somebody post a sample on account creation?
When trying create an account with the provided libraries I get an orchistrationException, opperationNotImplemented: add
Seems rather strange.

Posted by sic at Jul 01, 2009 13:16 | Permalink

I have uploaded my basic command line account create for a single account. I have just tested it and it works fine. To use for a bulkload to say set up a test or education environment you could wrap in shell script, but it pretty slow. I am working on a script that will run inside apiscript taking input from a csv file. However this is currently work in progress.

Posted by Andyp at Jul 02, 2009 06:28 | Permalink

Thanks andy, I'll give it a try. I've done the CSV parsing and looping in the jython script already. What sucks is that the version of jython in WAS is so old it does not include the default CSV python library. I had to get one and add it manually to the apiscript lib. It looks like this:

data=csv.ReadFile(sys.argv[0])
for row in data:
datamap=csv.ToMap(row,header)
mainloop(datamap)

def mainloop(data):
environment=data["environment"]
adapterserver=data["adapterserver"]

Posted by sic at Jul 02, 2009 12:16 | Permalink

Hi
I´m looking for a guide that shows me the objects and methods i can use when i´m scripting in TIM 5.1 but IBM support told me there is not so i´m wondering if you guys can tell me how can i perform the search.

Posted by juan.soler at Aug 25, 2009 15:43 | Permalink

Jython simply exposes Java API's in a different programming grammar. Look at the ITIM API and use the calls verbatim. The only trick is to remember object conversions to and from python.
Moreover, since the whole thing is not supported you could use even unsupported calls from itim's private api. Just dont tell anybody

Posted by sic at Aug 25, 2009 15:51 | Permalink

Hey

Thanks for your quick answer but I´d like some more detail because i´ve never used the API so i don´t know where it is so i can take a look.

Posted by juan.soler at Aug 25, 2009 16:09 | Permalink

Hello Juan and welcome to apiscript! There is no short answer to learning the TIM API, but hopefully I can help get you started.

1. the public TIM API is installed along with the product, for a TIM 5.1 installation it is at TIM_HOME/extensions/5.1/api/index.html – if you are familiar with Javadoc in general this should be a good resource
2. some examples of using this API from Java are at a similar directory: TIM_HOME/extensions/5.1/examples/apps
3. this is admittedly not enough to truly get started working with the TIM APIs "raw" from apiscript's Python environment, but it should be a kick in the right direction. I have some examples of using the "raw" TIM APIs (instead of the apiscript utility modules) that might be helpful, particularly when working with things like pending approvals, etc. If you think that would be helpful, let me know and I'll post them.
4. each apiscript module (after installation, under apiscript/Lib/apiscript/util/*.py) has some minimal documentation; for example open "orgchart.py" and look for some comments, which are provided primarily as Python docstrings (triple-quotes, like """some documentation""")
5. in general there is so much you can do once you are in the Python world that it is hard to know where to start documenting; for example I do not think the users have yet started exploiting just running apiscript as an interactive shell just yet... (apiscript.ksh without any arguments... then start typing: "from apiscript.util.orgchart import get_default_container_mgr" "container_mgr = get_default_container_mgr()" "container_mgr.createContainer(...)" so happy hacking)

Posted by sblinn at Aug 25, 2009 17:35 | Permalink

Also helpful:

http://jython.org/

Particularly:

http://wiki.python.org/jython/UserGuide

And:

http://python.org/

Particularly, since the Jython shipped with WAS 7 is a Python 2.1:

http://python.org/doc/2.1/

And:

http://www.brunningonline.net/simon/python/PQR2.1.html

Posted by sblinn at Aug 25, 2009 17:39 | Permalink

Hi sblinn,

I was recently given the task of making a call to ITIM API. I have no prior experience of working with ITIM API. Basically what we are trying to do is based a number find the user id in the system and then reset the password of that user id.

We are not supposed to use the Web service wrapper as it is not supported by IBM. I was trying a lot to get the documentation on this matter but it is very scarce. I went to the ITIM home directory and looked for the documentation there but that was not really helpful. What I need is some basic idea of how to start the project. So we are trying a write a custom Java Based Web Service for making calls to the ITIM API.

I just need a proven example that establishes a connection and performs some password based functions. We have already requested our company's web team to talk to the reps from IBM but that's taking long as everybody in the web team is quite busy.

I just need some examples on how this cab be done.

Any help in this matter is greatly appreciated.

Thanks in Advance

kvk34

Posted by kvk34 at Sep 11, 2009 15:53 | Permalink

Hi kvk34,

An example shell script:

/opt/IBM/itim/extensions/5.1/examples/apps/bin/unix/changePassword.sh (uses setEnv.sh)

A batch file:

/opt/IBM/itim/extensions/5.1/examples/apps/bin/win/changePassword.bat (uses setEnv.bat)

The source file:

/opt/IBM/itim/extensions/5.1/examples/apps/src/examples/api/ChangePassword.java

From your Java Based Web Service:

1. ensure your web service is running with appropriate environment and classpath to make remote ITIM calls
2. create a platform context
3. create a platform callback handler
4. set the callback handler's context to your context
5. create a login context using your callback handler
6. invoke your context.login() method to log in
7. create an instance of AccountManager using your platform context and subject (retrieved from the login context)
8. use the AccountManager to search for the Account in question -> returns AccountMO (may require using other managers to find the appropriate service)
9. invoke the changePassword method on the AccountMO object
10. wait for the request to complete (optional)

This may or may not be the right set of steps for your application; if for example you are trying to reset all the password for a given user, you might use PersonManager to find the Person whose passwords you want to change, and then PasswordManager's synchPasswords method for that PersonMO and the new password.

Posted by sblinn at Sep 11, 2009 16:37 | Permalink

Hi sblinn,

Thanks for your quick reply. This will be of great help to me as I am completely new to ITIM API.

kvk34

Posted by kvk34 at Sep 11, 2009 16:56 | Permalink

Hi sblinn,

I have been trying to run the ITIM examples for the last couple of days. But I am running into a lot of problems. If its possible can you please send your email-id to kadiyala34@gmail.com so that i can discuss the issues in detail.

Thanks in Advance

Vamsi

Posted by kvk34 at Sep 16, 2009 10:30 | Permalink

Hi sblinn,

Thanks for your examples. I am trying to write a script which will modify an existing provisioning policy that I have created previously. The modify script is not working, can you please advise if I am doing some hting wrong, i have spent hours trying to figure it out but I am relatively new to jyton scripting. Any help will be greatly appreciated!

I wrote this to add the policy. ( this works)

import apiscript.util
import jarray

from java.util import ArrayList
from java.util import Collections
from com.ibm.itim.apps.policy import ServiceAttributeParameter, Entitlement, ProvisioningParameters, Membership, ProvisioningPolicy, ServiceTarget

role_mgr = apiscript.util.orgrole.get_default_role_mgr()
org_mo = apiscript.util.orgchart.get_default_org_mo()

# general tab
pp = ProvisioningPolicy()
pp.name = "Example Provisioning Policy"
pp.priority = 10000
pp.enabled = java.lang.Boolean(java.lang.Boolean.TRUE)
pp.scope = ProvisioningPolicy.SUBTREE_SCOPE

# membership tab
memberships = ArrayList()
roleDN = role_mgr.getRoles(org_mo, "*").toArray()[0].distinguishedName
memberships.add(Membership(Membership.TYPE_ALL_PERSONS, roleDN.toString()))
pp.setMemberships(memberships)

# entitlements tab
parameterList = ArrayList()
#parameterList.add(ServiceAttributeParameter("cn",Collections.singletonList("Common Name"),[ServiceAttributeParameter.MANDATORY],[ServiceAttributeParameter.EXPRESSION_TYPE_SCRIPT]))
#parameterList.add(ServiceAttributeParameter("sn",Collections.singletonList("Surname"),[ServiceAttributeParameter.MANDATORY],[ServiceAttributeParameter.EXPRESSION_TYPE_SCRIPT]))
provisioningParameters = ProvisioningParameters(parameterList)
entitlements = ArrayList()
serviceDN = apiscript.util.service.get_services_by_name("ITIM Service").toArray()[0].distinguishedName
entitlements.add(Entitlement(Entitlement.ENTITLEMENT_TYPE_REQUIRED, ServiceTarget(ServiceTarget.TYPE_SERVICE_NAME, serviceDN.toString()), provisioningParameters, None))
pp.setEntitlements(entitlements)

# create the provisioning policy
apiscript.util.provpolicy.get_default_provpolicy_mgr().createPolicy(org_mo, pp, None)

________________________
Then I am trying to modify by doing this. ( This is not working and throwing a null pointer.)

import apiscript.util
import jarray
import apiscript.util.provpolicy as provpolicy
from apiscript.util.orgchart import get_default_org_mo
#from apiscript.util.provpolicy import submit_modify_provpolicy
from java.util import ArrayList
from java.util import Collections
from com.ibm.itim.apps.policy import ServiceAttributeParameter,Entitlement,ProvisioningParameters,Membership,ProvisioningPolicy,ServiceTarget

# GENERAL TAB
role_mgr = apiscript.util.orgrole.get_default_role_mgr()
org_mo = apiscript.util.orgchart.get_default_org_mo()
print "found default org %s" % org_mo.data.name

pp=apiscript.util.provpolicy.do_get_provpolicies("Example Provisioning Policy").toArray()[0]
pp.name = "Example Provisioning Policy"
pp.priority = 10000
pp.enabled = java.lang.Boolean(java.lang.Boolean.TRUE)
pp.scope = ProvisioningPolicy.SUBTREE_SCOPE

# entitlements tab
parameterList = ArrayList()
provisioningParameters = ProvisioningParameters(parameterList)
entitlements = ArrayList()
serviceDN = apiscript.util.service.get_services_by_name("ITIM Service").toArray()[0].distinguishedName
entitlements.add(Entitlement(Entitlement.ENTITLEMENT_TYPE_AUTHORIZED, ServiceTarget(ServiceTarget.TYPE_SERVICE_NAME, serviceDN.toString()), provisioningParameters, None))
pp.setEntitlements(entitlements)

# modify
# NOTE: this will overwrite existing attributes so be sure to add all desired attributes in the previous stanza
pp.getEntitlements().toArray()[0].setProvisioningParameters(provisioningParameters)

# modiy the provisioning policy
apiscript.util.provpolicy.get_default_provpolicy_mgr().modifyPolicy(org_mo, pp, None)
__________________

Error:

Caused by: java.rmi.ServerException: RemoteException occurred in server thread; nested exception is:
java.rmi.RemoteException:
>> SERVER (id=4773e3aa, host=osprey.pirean.com) TRACE START:
>> java.rmi.RemoteException: ; nested exception is:
java.lang.NullPointerException
>> at com.ibm.itim.dataservices.model.DirectoryObject.setAttribute(DirectoryObject.java:439)
>> at com.ibm.itim.apps.ejb.policy.ProvisioningPolicyManagerBean.modifyPolicy(ProvisioningPolicyManagerBean.java:545)
>> at com.ibm.itim.apps.ejb.policy.EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7.modifyPolicy(Unknown Source)
>> at com.ibm.itim.apps.ejb.policy.EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie.modifyPolicycom_ibm_itim_apps_ejb_home_AuthenticationObjectcom_ibm_itim_dataservices_model_DistinguishedNamecom_ibm_itim_apps_policy_ProvisioningPolicy_java_util_Date(_EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie.java:398)
>> at com.ibm.itim.apps.ejb.policy._EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie._invoke(_EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie.java:211)
>> at com.ibm.CORBA.iiop.ServerDelegate.dispatchInvokeHandler(ServerDelegate.java:613)
>> at com.ibm.CORBA.iiop.ServerDelegate.dispatch(ServerDelegate.java:466)
>> at com.ibm.rmi.iiop.ORB.process(ORB.java:503)
>> at com.ibm.CORBA.iiop.ORB.process(ORB.java:1552)
>> at com.ibm.rmi.iiop.Connection.respondTo(Connection.java:2673)
>> at com.ibm.rmi.iiop.Connection.doWork(Connection.java:2551)
>> at com.ibm.rmi.iiop.WorkUnitImpl.doWork(WorkUnitImpl.java:62)
>> at com.ibm.ejs.oa.pool.PooledThread.run(ThreadPool.java:118)
>> at com.ibm.ws.util.ThreadPool$Worker.run(ThreadPool.java:1469)
>> SERVER (id=4773e3aa, host=osprey.pirean.com) TRACE END.
; nested exception is:
java.lang.NullPointerException
at com.ibm.CORBA.iiop.UtilDelegateImpl.mapSystemException(UtilDelegateImpl.java:214)
at javax.rmi.CORBA.Util.mapSystemException(Util.java:84)
at com.ibm.itim.apps.ejb.policy._ProvisioningPolicyManager_Stub.modifyPolicy(_ProvisioningPolicyManager_Stub.java:515)
at com.ibm.itim.apps.policy.ProvisioningPolicyManager$2.run(ProvisioningPolicyManager.java:188)
at com.ibm.itim.apps.impl.websphere.WebSpherePlatformContextImpl.doAs(WebSpherePlatformContextImpl.java:114)
at com.ibm.itim.apps.policy.ProvisioningPolicyManager.modifyPolicy(ProvisioningPolicyManager.java:182)
... 44 more
Caused by: java.rmi.RemoteException:
>> SERVER (id=4773e3aa, host=osprey.pirean.com) TRACE START:
>> java.rmi.RemoteException: ; nested exception is:
java.lang.NullPointerException
>> at com.ibm.itim.dataservices.model.DirectoryObject.setAttribute(DirectoryObject.java:439)
>> at com.ibm.itim.apps.ejb.policy.ProvisioningPolicyManagerBean.modifyPolicy(ProvisioningPolicyManagerBean.java:545)
>> at com.ibm.itim.apps.ejb.policy.EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7.modifyPolicy(Unknown Source)
>> at com.ibm.itim.apps.ejb.policy.EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie.modifyPolicycom_ibm_itim_apps_ejb_home_AuthenticationObjectcom_ibm_itim_dataservices_model_DistinguishedNamecom_ibm_itim_apps_policy_ProvisioningPolicy_java_util_Date(_EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie.java:398)
>> at com.ibm.itim.apps.ejb.policy._EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie._invoke(_EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie.java:211)
>> at com.ibm.CORBA.iiop.ServerDelegate.dispatchInvokeHandler(ServerDelegate.java:613)
>> at com.ibm.CORBA.iiop.ServerDelegate.dispatch(ServerDelegate.java:466)
>> at com.ibm.rmi.iiop.ORB.process(ORB.java:503)
>> at com.ibm.CORBA.iiop.ORB.process(ORB.java:1552)
>> at com.ibm.rmi.iiop.Connection.respondTo(Connection.java:2673)
>> at com.ibm.rmi.iiop.Connection.doWork(Connection.java:2551)
>> at com.ibm.rmi.iiop.WorkUnitImpl.doWork(WorkUnitImpl.java:62)
>> at com.ibm.ejs.oa.pool.PooledThread.run(ThreadPool.java:118)
>> at com.ibm.ws.util.ThreadPool$Worker.run(ThreadPool.java:1469)
>> SERVER (id=4773e3aa, host=osprey.pirean.com) TRACE END.
; nested exception is:
java.lang.NullPointerException
at com.ibm.itim.dataservices.model.DirectoryObject.setAttribute(DirectoryObject.java:439)
at com.ibm.itim.apps.ejb.policy.ProvisioningPolicyManagerBean.modifyPolicy(ProvisioningPolicyManagerBean.java:545)
at com.ibm.itim.apps.ejb.policy.EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7.modifyPolicy(Unknown Source)
at com.ibm.itim.apps.ejb.policy.EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie.modifyPolicycom_ibm_itim_apps_ejb_home_AuthenticationObjectcom_ibm_itim_dataservices_model_DistinguishedNamecom_ibm_itim_apps_policy_ProvisioningPolicy_java_util_Date(_EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie.java:398)
at com.ibm.itim.apps.ejb.policy._EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie._invoke(_EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie.java:211)
at com.ibm.CORBA.iiop.ServerDelegate.dispatchInvokeHandler(ServerDelegate.java:613)
at com.ibm.CORBA.iiop.ServerDelegate.dispatch(ServerDelegate.java:466)
at com.ibm.rmi.iiop.ORB.process(ORB.java:503)
at com.ibm.CORBA.iiop.ORB.process(ORB.java:1552)
at com.ibm.rmi.iiop.Connection.respondTo(Connection.java:2673)
at com.ibm.rmi.iiop.Connection.doWork(Connection.java:2551)
at com.ibm.rmi.iiop.WorkUnitImpl.doWork(WorkUnitImpl.java:62)
at com.ibm.ejs.oa.pool.PooledThread.run(ThreadPool.java:118)
at com.ibm.ws.util.ThreadPool$Worker.run(ThreadPool.java:1469)
Caused by: java.lang.NullPointerException

com.ibm.CORBA.iiop.ClientDelegate@ffc0ffc invoke:849 P=541468:O=0:CT ORBRas[default] Throwable from UnknownExceptionInfo java.rmi.RemoteException: ; nested exception is:
java.lang.NullPointerException
at com.ibm.itim.dataservices.model.DirectoryObject.setAttribute(DirectoryObject.java:439)
at com.ibm.itim.apps.ejb.policy.ProvisioningPolicyManagerBean.modifyPolicy(ProvisioningPolicyManagerBean.java:545)
at com.ibm.itim.apps.ejb.policy.EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7.modifyPolicy(Unknown Source)
at com.ibm.itim.apps.ejb.policy.EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie.modifyPolicycom_ibm_itim_apps_ejb_home_AuthenticationObjectcom_ibm_itim_dataservices_model_DistinguishedNamecom_ibm_itim_apps_policy_ProvisioningPolicy_java_util_Date(_EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie.java:398)
at com.ibm.itim.apps.ejb.policy._EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie._invoke(_EJSRemoteStatelessenroleejb_ProvisioningPolicyMana_999418d7_Tie.java:211)
at com.ibm.CORBA.iiop.ServerDelegate.dispatchInvokeHandler(ServerDelegate.java:613)

Posted by mkhan05 at Oct 05, 2009 09:10 | Permalink