Up and Running: Basic Setup Claus Niesen, Iowa State University Kristina Taylor, Iowa State University

1. Up and Running: Basic Setup Claus Niesen, Iowa State University Kristina Taylor, Iowa State University

2. 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. Distribution Package Layout

4. quickstart_guide.txt • Requirements: • Java 1.5 • Servlet 2.4 / JSP 2.0 Compatible Servlet Containersuch as Apache Tomcat 5.5 • Oracle database instance or MySQL database instance 1. Run the database scripts using the instruction provided In db_scripts/readme.txt

5. db_scripts/ReadMe.txt

6. CreateKualiUser.sql CREATE USER <username> IDENTIFIED BY “<password>” DEFAULT TABLESPACE <tablespace> TEMPORARY TABLESPACE <temp tablespace>; ALTER USER <username> QUOTA UNLIMITED ON <tablespacename>; GRANT CREATE SESSION TO <username>; GRANT CREATE SYNONYM TO <username>; GRANT CREATE PROCEDURE TO <username>; GRANT CREATE TRIGGER TO <username>; GRANT CREATE TABLE TO <username>; GRANT CREATE TYPE TO <username>; GRANT CREATE VIEW TO <username>; GRANT CREATE SEQUENCE TO <username>; QUIT;

7. 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. KC_Install.bat or KC_Install.sh

9. KC_Install.bat or KC_Install.sh

10. 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. quickstart_guide.txt – Step 3 Edit parameters in kc-config.xml <param name="application.http.scheme">http</param> <param name="application.host">127.0.0.1</param> <param name="http.port">8080</param> <param name="app.context.name">${app.code}-${environment}</param> <param name="application.http.scheme">https</param> <param name="application.host”>test.kc.kuali.org</param> <param name="http.port”>443</param> <param name="app.context.name">${app.code}-${environment}</param>

12. quickstart_guide.txt – Step 3 (cont.) Edit parameters in kc-config.xml <!-- KC Client DB --> <param name="datasource.url">jdbc:oracle:thin:@127.0.0.1:1521:KUALI</param> <param name="datasource.username">KCDEV</param> <param name="datasource.password">ask your team</param> <param name="datasource.ojb.platform">Oracle9i</param> <!-- KC Client DB --> <param name="datasource.url">jdbc:oracle:thin:@db.kc.kuali.org:1521:KUALI</param> <param name="datasource.username">KCDLY30</param> <param name="datasource.password”>hahahaha</param> <param name="datasource.ojb.platform">Oracle9i</param>

13. quickstart_guide.txt – Step 3 (cont.) Edit parameters in kc-config.xml <!-- For Embedded Mode --> <param name="rice.app.url">https://test.kc.kuali.org/kr-dly30</param> <param name="kim.runmode">embedded</param> <param name="kcb.runmode">embedded</param> <param name="kew.runmode">embedded</param> <param name="ken.runmode">embedded</param> <param name="dev.mode">false</param> <!-- Rice Server DB --> <!-- Should be the same as KC Client DB when running bundled mode --> <param name="server.datasource.url">jdbc:oracle:thin:@db.kc.kuali.org:1521:KUALI</param> <param name="server.datasource.username">KRDLY30</param> <param name="server.datasource.password”>haha_once_again</param>

14. 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. 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. quickstart_guide.txt – Step 8 (cont.)

17. quickstart_guide.txt – Step 8 (cont.)

18. quickstart_guide.txt – Step 8 (cont.)

19. quickstart_guide.txt – Step 8 (cont.)

20. 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. 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. 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. Common Errors (cont.) • External kc-config.xml file not found

24. Common Errors (cont.) • External kc-config.xml file not found • Can be caused by starting with wrong user

25. 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. 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. Common Errors (cont.)

28. Up and Running: Grants.gov and s2s Geo Thomas, MIT

29. 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. Grants.Gov properties continue… Example from kc-dev <param name="grants.gov.s2s.host"> https://at07ws.grants.gov:446/app-s2s-server/services/ </param> <param name="grants.gov.s2s.port">ApplicantIntegrationSoapPort</param> <param name="s2s.keystore.location”>/kra/s2s/keystore/kc_org.jks</param> <param name="s2s.keystore.password">ks-password</param> <param name="s2s.truststore.location”>/kra/s2s/keystore/cacerts.jks</param> <param name="s2s.truststore.password”>ts-password</param>

31. Certificate registration and setup • Submit the certificate to Grants.gov using the required PDF to certificates@grants.gov • http://www.grants.gov/assets/CertificateRequests3.pdf • 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. 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. Testing connectivity Try accessing Opportunity list by going to Grants.Gov tab in KC application.

34. 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. 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. Up and Running: Advanced Setup Claus Niesen, Iowa State University Kristina Taylor, Iowa State University

37. 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. Rice Embedded

39. 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. Embedded in KC: Setup (cont)

41. Embedded in KC: Setup (cont) • In KC we provide sample templates for different configurations. • https://test.kuali.org/svn/kc_project/trunk/src/main/config/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/launch

42. 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. Configuration Parameters: Overview(cont) Final Configuration can be viewed with the Configuration Viewer pages

44. 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. 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. 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. 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. 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. 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. 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