ŠĻą”±į > ž’ p r ž’’’ o ’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’ģ„Į q` ųæ ; bjbjqPqP .T : : 3 ’’ ’’ ’’ ¤ č č č č č č č ü d> d> d> d> x> L ü ŹS ¶ Š> ( ų> ų> ų> ų> ų> ų> ų> IS KS KS KS KS KS KS $ T h čV ^ oS č ? ų> ų> ? ? oS č č ų> ų> S P P P ? > č ų> č ų> IS P ? IS P P R č č įR ų> Ä> °Ū źÄ d> ŌJ ö R IS S 0 ŹS µR , FW ŹO F FW įR FW č įR h ų> ? P ? &? p ų> ų> ų> oS oS P
ų> ų> ų> ŹS ? ? ? ? ü ü ü ä ą! ü ü ü ą! ü ü ü č č č č č č ’’’’ MYGDS Library Overview
The mygds library is a library to assist java developers in accessing information contained in the EDS service. The EDS service is a directory of user information, that is fed by the SIS, HRMS, and DAGS systems, EDS project documentation can be found at the following url HYPERLINK "http://gds.iu.edu/gds_eds_docs.html" http://gds.iu.edu/gds_eds_docs.html. All of the data is brought together and scripts load this data into an LDAP directory. Our systems can then interact with this directory, to look up information about the people using our systems, or about the people that are referenced in our systems. That is where MYGDS library comes in. Instead of requiring every team to learn how to interact with the directory, we have tried to abstract the directory access bits away from the developer and provide a clear object based interaction mechanism that keeps the learning curve small for those that do need to access the directory from java applications.
Requirements in order to be able to use this library:
You must have an account set up by the IMS (Alan Walshs team) team in order to be able to access this service. You will need a test account which will be used for development and testing environments, and a production account. This account can be requested by sending an email to the IMS team with the subject line, EDS account request. This email should be sent to HYPERLINK "mailto:imshelp@indiana.edu" \o "mailto:imshelp@indiana.edu" imshelp@indiana.edu
You will also need to create two properties files one for your settings directory, and one for your security directory. For consistency, both should be named MYGDS.properties. The file in the security directory structure will contain the username and password used to authenticate to the EDS service which you should have received from Step one. The file in the settings directory will contain the ldapUrl and webServiceServer properties.
Example files:
MYGDS.properties - settings file contents for production
##########################################################
# This file should contain
#
# ldapUrl=ldap://eds.iu.edu:636
# webServiceServer=https://uisapp.iu.edu
#
# Description:
# where these values represent the ldapUrl to access eds directly
# and webServiceServer for fallback access
##########################################################
ldapUrl=ldap://eds.iu.edu:636
webServiceServer=https://uisapp.iu.edu
MYGDS.properties - settings file contents for dev/test
##########################################################
# This file should contain
#
# ldapUrl=ldap://eds-stage.iu.edu:636
# webServiceServer=https://tamarack.iu.edu
#
# Description:
# where these values represent the ldapUrl to access eds directly
# and webServiceServer for fallback access
##########################################################
ldapUrl=ldap://eds-stage.iu.edu:636
webServiceServer=https://tamarack.iu.edu
MYGDS.properties security file contents for test and production (here you will need to substitute the values to match your account)
##########################################################
# This file should contain
#
# username=xxxxxx
# password=xxxxxx
#
# Description:
# where these values represent the username and password
# to be used to log into the ldap EDS service
##########################################################
username=IU-UITS-UIS-APP-ONESTART
password=xxxxxx
What can I do with this library?
The library can be used to fetch user entries from the ldap EDS service based on a number of different criteria, and turn the fetched data into strongly typed java beans. You can then use the returned beans to get information about the user such as name, email, address, and much more.
How do I use this library?
Unfortunately the documentation of this library is not quite up to date, and so I will provide some example usages in this section, however in the future expect this section to just reference where the javadoc is for the mygds library, and be prepared to use that, with some hints as to which classes that end users of this library will interact with.
Some Basics about using the library
It is recommended to keep a handle on the GdsClient object statically in some sort of Utility class in your application. This will ensure that the application is making the most efficient and effective use of the library, because once it has been instantiated, it will attempt to keep its connections open to the EDS service. This results if quicker retrieval times of user information. This library currently averages around 0.05 seconds to fetch a users information. Below is an example of how that was done in the OneStart Calendar project. Note that this counts on an object called PathInformation (available in UIS utilities library) that was populated with the PathToSettings and PathToSecurity variables that are based on execution environment, and are specified in the web.xml of your project. Here is an example of how those would be specified in the web.xml of your project. These then become available in the servlet context of your application and can then be used to populate the PathInformation class, which can then help you to retrieve settings and security properties files.
PathToSecurity
/opt/sa_forms/java/dev
PathToSettings
/opt/j2ee/dev
Examples assume that mygds library version 1.0 or greater are being used.
Examples also assume that uisutilities version 1.4 or greater are being used, and that prior to calling the getGdsClient() of this example Utilities class, that you have populated the PathInformation object.
public class Utilities {
private static org.apache.log4j.Logger LOG = org.apache.log4j.Logger.getLogger(Utilities.class);
private static GdsClient gdsClient;
public static GdsClient getGdsClient() {
if (gdsClient == null) {
try {
Properties settingsProperties = PathInformation.getInstance().getSettingsProperties("/edu/iu/uis/settings/ccl/MYGDS.properties");
Properties securityProperties = PathInformation.getInstance().getSecurityProperties("/edu/iu/uis/security/ccl/MYGDS.properties");
gdsClient = GdsClient.initGdsClient(settingsProperties.getProperty("webServiceServer"), settingsProperties.getProperty("ldapUrl"), securityProperties.getProperty("username"), securityProperties.getProperty("password"));
} catch (Exception e) {
LOG.error("Error initing GDS Client",e);
}
}
return gdsClient;
}
}
Example case of usage: I have gotten a network Id back from CAS, and now I need to find the users EmplId and email address.
Requires imports
import edu.iu.uis.sit.util.directory.gds.GdsPerson;
import edu.iu.uis.sit.util.directory.gds.NetworkId;
and code body of
kerberosUserName = FilterCAS.getRemoteUser(request);
NetworkId networkId = new NetworkId(kerberosUserName);
String firstName = null;
String lastName = null;
String emailAddress = null;
String personSequenceNumber = null;
List affiliations = null;
try {
LOG.info("starting gds lookup");
GdsPerson gdsPerson = Utilities.getGdsClient().fetchGdsUser(networkId);
firstName = gdsPerson.getGivenName();
lastName = gdsPerson.getSn();
emailAddress = gdsPerson.getMail();
personSequenceNumber = gdsPerson.getIuEduPSEMPLID();
affiliations = gdsPerson.getEduPersonAffiliation();
LOG.info("ending gds lookup: ");
} catch (Exception e) {
LOG.error("Error in gds Kerberos login", e);
}
Example case of usage: I have the emplid of the user that I would like to fetch, and I need to be able to get email address.
Requires imports
import edu.iu.uis.sit.util.directory.gds.GdsPerson;
import edu.iu.uis.sit.util.directory.gds.IUEduPSEMPLID;
and code body of
IUEduPSEMPLID emplId = new IUEduPSEMPLID (id);
String firstName = null;
String lastName = null;
String emailAddress = null;
String personSequenceNumber = null;
List affiliations = null;
try {
LOG.info("starting gds lookup");
GdsPerson gdsPerson = Utilities.getGdsClient().fetchGdsUser(id);
firstName = gdsPerson.getGivenName();
lastName = gdsPerson.getSn();
emailAddress = gdsPerson.getMail();
personSequenceNumber = gdsPerson.getIuEduPSEMPLID();
affiliations = gdsPerson.getEduPersonAffiliation();
LOG.info("ending gds lookup: ");
} catch (Exception e) {
LOG.error("Error in gds Kerberos login", e);
}
So to this point, you can see that there are multiple types of Ids that can be used to fetch a person. We have shown about how you can use emplId, and networkId. All of the attributes that can be used to ideally uniquely identify a person have extended the interface GdsIdentifiableAttribute. The list of classes that have extended this interface are: IUEduEIDN, IUEduPSEMPLID, IUEduSIDN, IUEduSequenceNum, IUEduUUID, NetworkId. Note that in order to be able to use EIDN or SIDN that your account must be set up with the privilege to do this in EDS. And at this point that IUEduUUID is not fully populated in EDS.
In addition to being able to look up a user in EDS, you can also use the mygds library to perform a lookup of multiple users. When looking up multiple users, you can use any of the objects that extend the GdsSearchableAttribute interface, which includes all of the above, although I would think that most often people would search by name or something more like that. The list of classes that implement the GdsSearchableAttribute is: Cn, EduPersonAffiliation, EduPersonNickname, GivenName, IUEduBirthdate, IUEduEIDN, IUEduPSEMPLID, IUEduPersonAffiliation, IUEduSIDN, IUEduSequenceNum, IUEduUUID, NetworkId, ObjectClass, Ou, Sn. So as you can see there are many attributes that can be used when searching for a list of users based on some criteria. Here is an example from the OneStart Calendar, how they used the mygds library to perform a lookup of people. It searches based on last name, first name, and campus. It does wildcarding automatically as appropriate.
Requires imports
import edu.iu.uis.sit.util.directory.gds.GdsAttributeCollection;
import edu.iu.uis.sit.util.directory.gds.GdsPerson;
import edu.iu.uis.sit.util.directory.gds.GdsPersonCollection;
import edu.iu.uis.sit.util.directory.gds.GivenName;
import edu.iu.uis.sit.util.directory.gds.IUEduPSEMPLID;
import edu.iu.uis.sit.util.directory.gds.NetworkId;
import edu.iu.uis.sit.util.directory.gds.Ou;
import edu.iu.uis.sit.util.directory.gds.Sn;
and code body of
private static GdsPersonCollection findGdsPeople(EventMaintenanceForm eventMaintenanceForm){
String lastName = eventMaintenanceForm.getLastName();
String campus = eventMaintenanceForm.getCampus();
String firstName = eventMaintenanceForm.getFirstName();
lastName = removeCharacter(lastName, "*");
lastName = removeCharacter(lastName, "%");
lastName = removeCharacter(lastName, "?");
eventMaintenanceForm.setLastName(lastName);
firstName = removeCharacter(firstName, "*");
firstName = removeCharacter(firstName, "%");
firstName = removeCharacter(firstName, "?");
eventMaintenanceForm.setFirstName(firstName);
if(lastName.trim().length() < 3){
eventMaintenanceForm.setExactLastName("T");
}
GdsAttributeCollection collection = new GdsAttributeCollection();
if(campus != null && campus.trim().length() > 0 && !campus.equals("none")){
collection.add(new Ou(campus.toUpperCase()));
}
if(lastName != null && lastName.trim().length() > 0){
String wildcard = "";
if(!"T".equals(eventMaintenanceForm.getExactLastName())){
wildcard = "*";
}
collection.add(new Sn(lastName.toUpperCase()+wildcard));
}
if(firstName != null && firstName.trim().length() > 0){
String wildcard = "";
if(!"T".equals(eventMaintenanceForm.getExactFirstName())){
wildcard = "*";
}
collection.add(new GivenName(firstName.toUpperCase()+wildcard));
}
GdsPersonCollection gdsPersons = null;
if(!collection.isEmpty()){
try {
gdsPersons = Utilities.getGdsClient().fetchGdsUsers(collection);
} catch (Exception e) {
LOG.error("Error connecting to GDS", e);
}
}
if(gdsPersons != null && !gdsPersons.isEmpty()){
return gdsPersons;
} else {
return null;
}
}
ė ) * 6 Y [ \ ]
ä å ś ¢ Ŗ ę
E
p
Ų
Ł
ģ
ķ
ļ
Ø © Ū ó ō å h i üųšųéųŽšÕšüŃüųŃĶųĶŃĶÉĶÉĶÉĶÅĮŖŖŖĮĶ||üü h"/ h#t h µ hVu° 0J CJ OJ QJ ^J aJ #hVu° B* CJ OJ QJ ^J aJ ph ,j hVu° B* CJ OJ QJ U^J aJ ph hVu° h$ h("Ę hÖ5ē hn h;KÖ hjW 0J j hjW UhjW hjW j hjW UhjW h`4Ō 0 å ę ī
ļ
© Ŗ ¹ ŗ ō õ 0 K M m § é ś ų ų ų ó ų ė ā Ś Õ ó Õ Š Õ Ė Ė Ė Ė Ė Ė Ė Ė Ė gd#t gdd gd µ
&