IBM Maximo LDAPSYNC CRONTASK concepts overview.

The primary purpose of this article is to introduce you to the concepts you need to understand in order to set up, configure and maintain the LDAPSYNC CRON task in Maximo.

The first concept you need to understand is that the LDAPSYNC CRON task is designed to work only with Microsoft Active directory. If you need authorization to another product or environment, check out VMMSYNC. So all the connection and xml parameter values are specific to Microsoft Active Directory.

The purpose of the LDAPSYNC CRON task is to establish a list of Maximo users that are authorized to use Maximo. It does this by building any missing “MAXGROUP” records then the “GROUPUSER” record followed by the “MAXUSER” and “PERSON” records. The MAXGROUP record created will be the name of the active directory security group you reference. Unless you have multiple LDAPSYNC’s this security group should contain every person that you want to have as a Maximo Named user license for your organization. The GROUPUSER record is then the record that ties the user to the group. So you should have one group user record for each user after the LDAPSYNC runs. Then of course the person record is the information about the user. So you should have one person record for each Maximo user, again once the LDAPSYNC runs.

There are two fundamental ways to think about using LDAPSYNC. You can establish a bunch of active directory groups and give them different roles in Maximo, with a bunch of matching LDAPSYNC CRON tasks. Or you can have one active directory group and one LDAPSYNC for all your Maximo users and then create the roles in Maximo and assign the users to them. Most organizations prefer the latter setup as it minimizes the active directory work and shifts it to the Maximo security person where the role needs are better understood.

I use the term “authorization” for LDAPSYNC as initial security is “authentication” which will normally occur in WebSphere. Which is not discussed in this article.

Starting in Maximo 7 versions the LDAPSYCN CRON information is stored in the database as either parameters or xml. The xml and parameters are stored in the table “CRONTASKPARAM”. The only unusual characteristic to note is that the password for the LDAP account used to connect to active directory is stored in a column called “CRYPTOVALUE”. When you enter the password in the CRONTASK application it encrypts it and stores it in this field. The thing to know about this is that this value will be the same for any database or LDAPSYNC CRON that uses the same account. But the encryption value is different for a Maximo version 6.x environment, even if it uses the same active directory account.

All the LDAPSYNC CRON information and parameters are stored in the following three tables: CRONTASKINSTANCE, CRONTASKPARAM, and CRONTASKHISTORY. The relationships are pretty obvious using a database tool like TOAD or SQL Developer will allow you to view the information of interest. Selecting the information where the “CRONTASKNAME” like ‘LDAP%’ should show what is of interest. You won’t see any records in the history table unless you have enabled the keep history option on the CRON task in Maximo. Also while it is pretty safe to make changes to the CRON instance and parameters at the database level, they will not take effect until you go back into Maximo and “Reload” the LDAPSYNC CRON task. If you ever have to bring up a new Maximo installation from scratch in an environment that requires all security be up and operational at the start this ability will become important to you. As you will find yourself in a scenario where you can’t get into Maximo because security is enabled, but you don’t yet have a MAXUSER entry to log on with. But Maximo will come up, so establish the LDAPSYNC CRON via the database and let it run to get your initial users. Also be aware the CRON will not run if Maximo is in admin mode. The Maximo developers have a tendency to leave systems in admin mode and then spend hours wondering why their CRON’s won’t run.

There are four port numbers that you should be familiar with since you have to specify Microsoft Active directory ports to get the LDAPSYNC CRON task running.

If your environment allows it. You can communicate with active directory in the clear using port 389 to authenticate your active directory account that is being used to get the information, and then configure port 3268 for the active directory global catalog port to get the user information. Note if this is your first Maximo environment you may find port 3268 is not turned on in your active directory system, or they may decide to turn it off one day without telling anyone. If neither of these ports work for you then you may be in a secure environment where you have to encrypt all communication and use ports 636 and 3269 respective. There is more to securing this communication then just using these ports so be sure to research the need to use your active directory certificates to complete this security configuration. See my article titled “Converting LDAPSYNC from unencrypted to encrypted communication” for a complete discussion of this process.

LDAPSYNC crontask parameters example:

port = 636

SynchParameter = globalcatalogport=3269

SSLEnabled = TRUE

Don’t know the name of an active directory server in your domain? Try the following to get what you need. Logon a workstation in the domain of interest, enter the following command in a MS-DOS command window.

C:..> echo %LOGONSERVER%

Then do a ping to get the fully qualified name.

C:…> ping severname

This should help you get started.

It’s very hard to figure out the mapping between the LDAPSYNC CRONTASK elements and active directory without an account to view the data in active directory and a tool to see the data. A tool like Softerra’s LDAP Browser or Microsoft’s Active Directory Users and Computers should be used to figure out your initial parameters to get to the security group of interest in active directory. Softerra has a free version that is more than adequate for the job. Or you can download the Microsoft 2008 Admin pack and install the Users and Computers component. Become familiar with one of them and your active directory organization and it will make configuring your LDAPSYNC a lot simpler. I recommend you establish a separate system/non-user account to be used for LDAPSYNC, and if you can talk your security folks into it. Make sure the password does not expire. Otherwise you will have to go into the CRON task and update the password and reload the CRON each time it changes.

From time to time you will find a new user just does not make it down into the MAXUSER table in spite of the fact that the CRON appears to be running correctly. Seems there is a bug and sometimes doing a delta load of new users doesn’t happen. It’s easy to fix, the idea is to force the CRON job to try and reload everyone. Basically what you do is reset the pointer for active directory so the CRON thinks it’s a brand new run and has to load everyone. Below is an example of a sql command to reset the LDAPSYNC active directory parameters. Don’t confuse this with CRONTASKPARAM, it’s different. It should update three rows. Then wait for the next run of the CRON. If successful it will update the three rows with new values and your missing person should finally be in place. If not bring up your active directory tool and make sure they actually made it into the security group in the first place. Note this table, ldapsyncparams, will be empty until you have a least one successful run of the LDAPSYNC CRON task.

update ldapsyncparams set paramvalue = ‘0’ where taskinstance = ‘LDAPSYNC01’;

So you have set up your LDAPSYNC and you are still not getting any new MAXUSER entries in the table. The first thing you can do is turn on history in Maximo on the CRON task and see if the task history is updating. If not maybe admin mode is on. Otherwise, if you have entries, verify one of them shows an activity of “ACTION” which indicates a good run. If not then the next step is to review the application log. If you have a single server single Maximo application then you will want to review the log at that applications SYSTEMOUT.log. Which is typically under the WebSphere application called something like “MXServer”. If you have a cluster or your Maximo/WebSphere person has broken out the CRON jobs into their own applications then you will need to work with them to find the log. The server name column of the CRON task history can help you figure out just which environment you are looking for the log in. The other thing you can do is configure additional logging in Maximo for the LDAPSYNC CRON. See

System Configuration > Platform Configuration > Logging

Expand crontask, Expand LDAPSYNC, and change logging to DEBUG.

Don’t forget to apply the settings and change it back to ERROR once you have resolved the issue. Note you will have to wait for the next run of the CRONTASK, or change and save the new time and reload the request. Don’t forget to change the time back. Note these types of changes in Maximo typically do not bother any other aspect of Maximo, so if your environment permits you can debug production issues without taking the system away from your users.

How often should you run the CRON and how much history should you keep? Instead, ask yourself how long you have after they put the new user in the active directory security group until they complain they can’t get in to Maximo. We run the CRON every four hours in my organization. I only keep about a hundred records, that’s a couple weeks’ worth of history. I have never had a need to go back further. Your organization and the frequency at which people are added will determine the timing and volume needed.

What does LDAPSYNC not due that you wish it would. Well it never removes any records. It only adds records, if they don’t exist. So when someone leaves the organization you can remove them from active directory but nothing happens in Maximo to reflect the fact they are no longer there.

You have to have another interface or business process to remove their identity and/or authorizations in Maximo. Though I did see a note online once where it was suggested that you could do a second CRON task, where it does not look at group mappings (objectName=DOES_NOT_EXIST) and then looks for a flag in active directory indicating the user is inactive then hard code the Maximo MAXUSER status to {INACTIVE}. I have never tried this but it sounds feasible.

Switching from Maximo internal authentication and authorization to LDAPSYNC and WebSphere authentication is fairly complicated, due to the fact that you would like to retain all your user data references, and the individual’s user identification in active directory may not be the same as was used internally in Maximo. This issue can be resolved by writing database procedures that convert all references of the old user identification to the new active directory identifier. If the maxattributecfg table is utilized, then the procedures can dynamically parse through the database and update the users identifier everywhere it is referenced. This is a fair amount of code to be written and tested, so plan on some time to develop.

Need more LDAPSYNC or xml help, Google: “IBM Maximo LDAPSYNC” to get the IBM references of interest.