1. open source administration software for education research administration Up and Running: Basic Setup Claus Niesen, Iowa State University Kristina Taylor, Iowa State University

2. open source administration software for education Obtaining the Distribution Package Download via web browser – Kuali.org – Downloads link – KC 3.0.1 Source (zip) Curl/wget/etc. from your server – downloads.kc.kuali.org/3.0/kc-release-3_0_1.zip

3. open source administration software for education Distribution Package Layout Root directory binarykc-config.xmlkc-ptd.wardb_scriptsReadMe.txt KC_Install.sh (.bat) kc_projectlicenses

4. open source administration software for education quickstart_guide.txt 1. Run the database scripts using the instruction provided In db_scripts/readme.txt Requirements: Java 1.5 Servlet 2.4 / JSP 2.0 Compatible Servlet Container such as Apache Tomcat 5.5 Oracle database instance or MySQL database instance

5. open source administration software for education db_scripts/ReadMe.txt

6. open source administration software for education CreateKualiUser.sql CREATE USER IDENTIFIED BY “ ” DEFAULT TABLESPACE TEMPORARY TABLESPACE ; ALTER USER QUOTA UNLIMITED ON ; GRANT CREATE SESSION TO ; GRANT CREATE SYNONYM TO ; GRANT CREATE PROCEDURE TO ; GRANT CREATE TRIGGER TO ; GRANT CREATE TABLE TO ; GRANT CREATE TYPE TO ; GRANT CREATE VIEW TO ; GRANT CREATE SEQUENCE TO ; QUIT;

7. open source administration software for education KC_Install.sh (.bat) Prerequisites to running KC_Install.sh (.bat) – What type of Rice configuration? Bundled Embedded Remote – What is your current KC database state? None = NEW 2.0 = 2.0 to 3.0.1 upgrade 3.0 = 3.0 to 3.0.1 upgrade – Connect info for kc (and kr) database schema

8. open source administration software for education KC_Install.bat or KC_Install.sh

9. open source administration software for education KC_Install.bat or KC_Install.sh

10. open source administration software for education quickstart_guide.txt – Step 2 Place binary/kc-config.xml in one of the configured default locations – {user.home}/kuali/main/ptd/kc-config.xml – /opt/sa_forms/java/ptd/kra/kc-config.xml – On Windows with Tomcat running as a service, the best location is usually C:\kuali\main\ptd – NOTE: If you are upgrading and have an existing kc-config.xml in this location, please replace it, as new parameters are often added To use a different location, open kc-ptd.war and create an alt.config.location parameter in /WEB-INF/classes/META- INF/kc-config-build.xml. – NOTE: This file also contains the environment parameter referenced in the external kc-config.xml file You should also be able to pass a java parameter of alt.config.location to your j2ee container (not guaranteed to work)

11. open source administration software for education quickstart_guide.txt – Step 3 Edit parameters in kc-config.xml http 127.0.0.1 8080 ${app.code}-${environment} https test.kc.kuali.org 443 ${app.code}-${environment}

12. open source administration software for education quickstart_guide.txt – Step 3 (cont.) Edit parameters in kc-config.xml jdbc:oracle:thin:@127.0.0.1:1521:KUALI KCDEV ask your team Oracle9i jdbc:oracle:thin:@db.kc.kuali.org:1521:KUALI KCDLY30 hahahaha Oracle9i

13. open source administration software for education quickstart_guide.txt – Step 3 (cont.) Edit parameters in kc-config.xml https://test.kc.kuali.org/kr-dly30 embedded false jdbc:oracle:thin:@db.kc.kuali.org:1521:KUALI KRDLY30 haha_once_again

14. open source administration software for education quickstart_guide.txt – Steps 4, 5 & 6 4. Obtain appropriate jdbc driver and install into j2ee container – Tomcat 5.5: common/lib – Tomcat 6: lib 5. Deploy kc-ptd.war (or whatever you’ve named it) to your j2ee container – Tomcat: webapps directory with default config 6. KC app available at: – {application.host}/{app.context.name}

15. open source administration software for education quickstart_guide.txt – Steps 7 & 8 7. Login as ‘ admin ’ 8. Ingest the KEW documents – Located in zip files under the respective release subdirectories db_scripts/KC-RELEASE-2_0-SCRIPT db_scripts/KC-RELEASE-3_0-SCRIPT – Ingest different sets for different installs New Install: Ingest both (in order) Upgrade from 2.0 to 3.0: Ingest only 3.0 Upgrade from 3.0 to 3.0.1: None to ingest – NOTE: If you have more than one zip file to process, ingest one at a time. The ingestion process takes a few minutes per zip file.

16. open source administration software for education quickstart_guide.txt – Step 8 (cont.)

17. open source administration software for education quickstart_guide.txt – Step 8 (cont.)

18. open source administration software for education quickstart_guide.txt – Step 8 (cont.)

19. open source administration software for education quickstart_guide.txt – Step 8 (cont.)

20. open source administration software for education ALL DONE…sort of Very barebones install No test data/users included User data must be populated to db – Will be addressed in patch or script download

21. open source administration software for education Common Errors and Troubleshooting Most common reasons for app not starting – JDBC driver not in the correct place – External kc-config.xml file not found – kc-config.xml not formatted correctly – Tomcat hot deploy exception

22. open source administration software for education Common Errors (cont.) JDBC driver not in the correct place – Causes TONS of errors – Recurring theme – java.sql.SQLException: Error trying to load driver: oracle.jdbc.driver.OracleDriver : oracle.jdbc.driver.OracleDriver

23. open source administration software for education Common Errors (cont.) External kc-config.xml file not found

24. open source administration software for education Common Errors (cont.) External kc-config.xml file not found – Can be caused by starting with wrong user

25. open source administration software for education Common Errors (cont.) External kc-config.xml file formatted incorrectly – Can be caused by nesting comments inside of comments or other XML oddities – Causes Spring error with PropertyPlaceholderConfigurer – Look for: Error parsing config file: {path.to.config}\kc-config.xml

26. open source administration software for education Common Errors (cont.) Tomcat hot deploy exception – KC – usually manifests as Duplicate Connection Descriptor – Rice – various errors about missing files – “touch” the kc-ptd.war (or kr-ptd.war) file

27. open source administration software for education Common Errors (cont.)

28. open source administration software for education research administration Up and Running: Grants.gov and s2s Geo Thomas, MIT

29. open source administration software for education KC-Grants.Gov Setup Properties defined in kc-config.xml – grants.gov.s2s.host Test server Prod Server – grants.gov.s2s.port – s2s.keystore.location – s2s.keystore.password – s2s.truststore.location – s2s.truststore.password

30. open source administration software for education Grants.Gov properties continue… Example from kc-dev https://at07ws.grants.gov:446/app-s2s-server/services/ ApplicantIntegrationSoapPort /kra/s2s/keystore/kc_org.jks ks-password /kra/s2s/keystore/cacerts.jks ts-password

31. open source administration software for education Certificate registration and setup Submit the certificate to Grants.gov using the required PDF to certificates@grants.govcertificates@grants.gov – http://www.grants.gov/assets/CertificateRequests3.p df http://www.grants.gov/assets/CertificateRequests3.p df – Grants.gov will notify you via email once it has been installed After the certificate has been installed, E-Biz Point of Contact must authorize certificate (This step is not required for AT) Create a java keystore file by using keytool utility and import the certificate to keystore Import Grants.Gov public certificate to Truststore

32. open source administration software for education Generating Certificate - Portecle GUI version of the command-line keytool provided with the JAVA SDK http://sourceforge.net/projects/portecle Things to be taken care while creating certificate for Grants.Gov – Select key algorithm as RSA – Select key size as 2048

33. open source administration software for education Testing connectivity Try accessing Opportunity list by going to Grants.Gov tab in KC application.

34. open source administration software for education Troubleshooting Common errors: – SSLHandshake error Certificate is not properly registered at grants.gov or Certificate is not properly imported to keystore – Timeout error Network problem Outgoing port 446 is not open from application server, check firewall setup

35. open source administration software for education Exception Codes from Grants.Gov 00 : E_METHOD_UNSUCCESSFUL 01 : E_NO_SESSION 02 : E_NO_USER_CERT 03 : E_NO_CERT_USER_ID 04 : E_INVALID_CERT 05 : E_NO_AGENCY_TRACK_NUM 06 : E_NO_GG_NUM 07 : E_NO_USER_ID 08 : E_CANT_RETRIEVE_APP 09 : E_UNSUPPORTED_FILTER 10 : E_USER_LACKS_ROLE 11 : E_NOT_USERS_APP 12 : E_AUTHORIZATION_FAILURE 13 : E_UNRECOGNIZED_GG_NUM 14 : E_CANT_DETERMINE_USER_AGENCY 15 : E_APPLICANT_SUBMIT_DOWN 16 : E_RECEIVE_ERROR 17 : E_APPS_NOT_RETRIEVED

36. open source administration software for education research administration Up and Running: Advanced Setup Claus Niesen, Iowa State University Kristina Taylor, Iowa State University

37. open source administration software for education Rice Integration and Deployment Models KC supports 2 of Rice’s Deployment Models – Bundled Single database Local service calls Direct database access No standalone rice server Not recommended for a production environment Great for local development environments – Embedded Standalone rice Split databases No need for plugins (embedded kew) Shared doc search, action list, service registry Rice service calls are local from client* Rice database access is done directly from client* Fast, transactional because local service calls and direct DB access

38. open source administration software for education Rice Embedded

39. open source administration software for education Embedded in KC: Setup Create, Populate client and server databases – Client contains KC tables, rice client tables – Server contains Rice server tables – We have DB scripts for this Generate Security keys for service communication Configure KC to run in an embedded configuration via xml configuration

40. open source administration software for education Embedded in KC: Setup (cont)

41. open source administration software for education Embedded in KC: Setup (cont) In KC we provide sample templates for different configurations. – https://test.kuali.org/svn/kc_project/trunk/src/main/c onfig/userhome/kuali/main/dev https://test.kuali.org/svn/kc_project/trunk/src/main/c onfig/userhome/kuali/main/dev We also provide launch scripts to launch a standalone rice server & kc server up in a single Jetty – Great for quick testing with standalone rice! – https://test.kuali.org/svn/kc_project/trunk/scripts/lau nch https://test.kuali.org/svn/kc_project/trunk/scripts/lau nch

42. open source administration software for education Configuration Parameters: Overview Config Parameters reside in xml files that are used for configuring the system during startup. KC’s final configuration is a combination of the following files – kc-config-build.xml (values set during maven build) – common-config-defaults.xml (rice defaults) – kc-config-defaults.xml (kc defaults & rice overrides) – common-config-locations.xml (a standard set of alternate external locations to find config files) – ${alt.config.location} (a hook to provide an alternate config location which can be set at startup)

43. open source administration software for education Configuration Parameters: Overview(cont) Final Configuration can be viewed with the Configuration Viewer pages

44. open source administration software for education Configuration Parameters: A few notable ones build.environment, build.version – Can be set with maven (ie. mvn install Dbuild.version=1234 – Version is used to display on portal, env is used when constructing the context root rice.struts.message.resources – Lists the messages bundles to be loaded by the kns. Can be used to override messages filter.login.class, filtermapping.login.1 – Used for setting the login filter – you should override these in order to use a SSO solution s2s.*, grants.gov.* – Used for grants.gov integration. Most are already set for you except the security related ones Bottom Line: check our configuration file hierarchy for customization opportunities before changing source code!

45. open source administration software for education System Parameters Parameters are grouped by functional areas – i.e. Award, Proposal, Protocol, etc. The functional areas are known as namespaces – The Kuali Coeus namespaces are prefixed with KC- – i.e. KC-AB for Award Budget There are 314 parameters defined for Kuali Coeus. – 142 are Configuration type parameters – 172 are Help type parameters

46. open source administration software for education Help System Parameters The help icons ( ) in the application link respective pages to the help documentation. Identified by a Parameter Type of HELP Contains the URL where the help document resides Kuali Coeus releases with basic help documentation – These documents can be updated or replaced by implementing institutions.

47. open source administration software for education Configuration System Parameters Identified by a Parameter Type of CONFG Parameters are variables that are not stored in a properties file – Allows for easier end-user maintenance and does not require a restart of the application to take affect. Majority of parameters are used to identify code table values

48. open source administration software for education Configuration System Parameters (cont) Parameters to configure for your institution – *.creditsplit.enabled Activates the Credit Split panel Used by Award, Institute Proposal, and Development Proposal modules – deliveryInfoDisplayIndicator Enables the Delivery Info panel – multipleValueLookupResultsPerPage Defines the number of results returned per page in a multiple value lookup result

49. open source administration software for education Configuration System Parameters (cont) – pessimisticLocking.expirationAge/ – pessimisticLocking.timeout – proposaldevelopment.displayKeywordPanel Enables the Keyword panel in Proposal Development – proposaldevelopment.autogenerate.institutionalproposal Causes the Institutional Proposal to be generated upon final approval – SCHOOL_NAME – SCHOOL_ACRONYM – SCHEDULER_SERVICE_ENABLED Turns on the S2S polling service – MULTI_CAMPUS_ENABLED

50. open source administration software for education Configuration System Parameters (cont) – NSF_SPONSOR_CODE The sponsor code for the main NSF sponsor – budgetCurrentFiscalYear Identifies when the fiscal year starts Important parts are the Month and Day. Year is ignored. – budgetUnrecoveredFandAApplicabilityFlag Enables the Underrecovery allocation panel

51. open source administration software for education Configuration System Parameters (cont) – budgetUnrecoveredFandAEnforcementFlag Requires any underrecovery to be allocated to an account – Irb.protocol.*.linking.enabled Used by Award, Institute Proposal, and Development Proposal modules If enabled the protocol numbers are linked to the IRB module with lookup capabilities If disabled the protocol numbers are not linked to the IRB module

52. open source administration software for education Code Tables Several Code Tables are provided pre-populated out of the box. – Most do not need to be updated and can be used as is. – Some have ties into the application logic Code tables that have related application logic typically have System Parameters defined for each code value Proposal Type is an example of a code table with logic tied to it. – Other Code Tables require the institution to populate These contain institutional data i.e. Unit and Sponsor tables

53. open source administration software for education Code Tables to Modify Caveat: When modifying code descriptions make notes of original values. – When conversing with other institutions, using original values avoids confusion and mis-information Activity Type – These are tied into Institutional Rates Appointment Type – Used to identify how many months a person’s appointment is for when calculating a monthly salary. – Has a value to specify the duration (value in months)

54. open source administration software for education Code Tables to Modify (cont) Budget Category – These are the groupings of your institutional Object Codes. – Used to map to the Grants.Gov categories – Other Related tables Budget Category Mapping Budget Category Maps Cost Element – This stores the institutional Object Codes – Typically populated with expense codes – Best practice would be to align with financial system expense codes

55. open source administration software for education Code Tables to Modify (cont) Cost Share Type IDC Rate Types Institute Rates/Institute LA Rates – Ties the Rate Class/Rate Type/Activity Type/Fiscal Year to a rate Inv Credit Type – Defines how you want to split credit – Has a validation flag to force split to total to 100% IP Review Result Type Job Code – Populating provides valid Job Codes when budgeting personnel – Can be used in conjunction with Valid CE Job Code table to restrict available Object Codes for selected Job Code (which is associated with each of your personnel)

56. open source administration software for education Code Tables to Modify (cont) Narrative Type – Contains the Narrative Types for all Attachments to be submitted with Grants.Gov applications. Identified by a Narrative Type Group of “P” – Institutional Narrative Types are defined in this list as well Identified by a Narrative Type Group of “O” Organization – Populate at least one record with your institutional information DUNS number Needed for Grants.Gov submissions Organization Type List – Should be updated to match current SF424 organization types.

57. open source administration software for education Code Tables to Modify (cont) Person Appointment – Can be optionally populated with the job code, salary, and effective date for each employee at institution. – There is not a UI for this code table, it is intended to be populated through a batch process – The values are used as defaults when budgeting personnel – Budget personnel does not need to be present in this table to be budgeted Person Editable Fields – The list of fields that are modifiable on a proposal after a key person has been added. – Change is not permanent, only reflected on the document change was applied to.

58. open source administration software for education Code Tables to Modify (cont) Person Ext T – Need to populate for each person in KIM tables. – Office Location, Primary Title, and Directory Title need to be populated for Grants.Gov submissions. Rate Class Type/Rate Class/Rate Type – Inter-related with ties into Institute Rates. Rolodex

59. open source administration software for education Code Tables to Modify (cont) Science Keyword Special Review Sponsor – You will have at least one rolodex record for each sponsor that is tied back to the sponsor from the rolodex record (i.e. circular reference) Sponsor Forms/Sponsor Form Templates – The forms need to be mapped back to the appropriate sponsors in your sponsors table

60. open source administration software for education Code Tables to Modify (cont) Sponsor Hierarchy – Create Hierarchy of NIH sponsors named “NIH Multiple PI” with one level named “NIH Multiple PI” TBN Unit – Your institutional departments, colleges, and other divisions – This is a hierarchical table. – Top most node in tree should reference the institutional Organization record. – Top most node must have an id of “000001”

61. open source administration software for education Code Tables to Modify (cont) Unit Administrator – Grants.Gov Proposal Contact type needs to be defined for each unit for submission to Grants.Gov – Other types are used by the default workflow. Validation tables – Begin with Valid_ – Required for certain functionality to work properly. Object Code to Rate Type Object Code to Job Code Forcing certain Special Review types to require values YNQ – Used by Grants.Gov primarily – Additional questions can be added, all are required to fill in

62. open source administration software for education Spring Overrides All services in Rice and KC are configured via Spring as Spring Beans In order to customize KC am implementor can elect to inject their own Spring Beans instead of modifying the existing ones. KCs default Spring Beans are all loaded from a single file located at: classpath:kc-bootstrap-springbeans.xml This location can be overridden by setting the parameter kc.bootstrap.spring.file in either the web.xml file or as a JVM system parameter. The overriding file should contain: as its first directive to ensure that the default KC Beans are loaded. Then other beans can be declared or other files imported. An overriding service must have the same ID as the service being overridden and implement the same interface.

63. open source administration software for education Implementor Spring Beans Files keyValuesService

64. open source administration software for education Spring Overrides Continued If Rice services are being overridden, in addition to the bean declaration for the service itself, the service needs to be added to the list of overridable services: firstServiceName secondServiceName etc... Rice Beans required as references into other beans may need to be exposed using the global resource loader:

65. open source administration software for education Data Dictionary Overrides Data Dictionary overrides are useful for changing the labeling, field size, or other information about fields of the various objects throughout the KC system. DD overrides are implemented by performing a Spring Override and including the new DD files in a new module configuration: classpath:path/to/CustomDD1.xml classpath:path/to/CustomDD2.xml

66. open source administration software for education Getting Help Revisit the quickstart_guide.txt in the KC 3.0.1 Source download Technical Collaboration mailing list http://www.kuali.org/kis/collabs/ Your commercial affiliate