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

open source administration software for education

research administration

Up and Running: Basic Setup

Claus Niesen, Iowa State UniversityKristina Taylor, Iowa State University

http://creativecommons.org/licenses/by/3.0/


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



Distribution Package Layout

Root directory

binary

kc-config.xml kc-ptd.war

db_scripts

ReadMe.txt KC_Install.sh (.bat)

kc_project licenses



quickstart_guide.txt

1. Run the database scripts using the instruction providedIn db_scripts/readme.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



db_scripts/ReadMe.txt



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;



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



KC_Install.bat or KC_Install.sh



KC_Install.bat or KC_Install.sh



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)



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>



quickstart_guide.txt – Step 3 (cont.)


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

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





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

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



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}



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.















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



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



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




• External kc-config.xml file not found




• External kc-config.xml file not found– Can be caused by starting with wrong user




• 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




• 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







Up and Running: Grants.gov and s2s

Geo Thomas, MIT



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



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>

https://at07ws.grants.gov:446/app-s2s-server/services/



Certificate registration and setup

• Submit the certificate to Grants.gov using the required PDF to [email protected]– 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

mailto:[email protected]

http://www.grants.gov/assets/CertificateRequests3.pdf



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

http://sourceforge.net/projects/portecle



Testing connectivity

• Try accessing Opportunity list by going to Grants.Gov tab in KC application.



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



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




Up and Running: Advanced Setup

Claus Niesen, Iowa State UniversityKristina Taylor, Iowa State University



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



Rice Embedded



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



Embedded in KC: Setup (cont)



Embedded in KC: Setup (cont)

• In KC we provide sample templates for different configurations.– https://test.kuali.org/svn/kc_project/trunk/src/m

ain/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

https://test.kuali.org/svn/kc_project/trunk/src/main/config/userhome/kuali/main/dev

https://test.kuali.org/svn/kc_project/trunk/src/main/config/userhome/kuali/main/dev

https://test.kuali.org/svn/kc_project/trunk/scripts/launch

https://test.kuali.org/svn/kc_project/trunk/scripts/launch



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)



Configuration Parameters: Overview(cont)

• Final Configuration can be viewed with the Configuration Viewer pages



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!



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



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.



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



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




– 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




– 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




– 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



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



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)



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




• 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)




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




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




• 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




• 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




• 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”




• 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



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:

<import resource="classpath:kc-bootstrap-springbeans.xml" />

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.



Implementor Spring Beans Files

<?xml version="1.0" encoding="UTF-8"?><beans ...>

<import resource="classpath:kc-bootstrap-springbeans.xml" /><import resource="classpath:edu/myschool/springbeans/custom-springbeans.xml" />

</beans>

<?xml version="1.0" encoding="UTF-8"?><beans ...>

<bean id="businessObjectDao" class="org.kuali.rice.kns.config.GlobalResourceLoaderServiceFactoryBean"><property name="serviceName" value="businessObjectDao" />

</bean>

<bean id="kraRootResourceLoader" parent="kraRootResourceLoaderParent"><property name="overridableServices"><set merge="true"><value>keyValuesService</value></set></property>

</bean>

<bean id="keyValuesService" class="edu.myschool.CustomKeyValuesServiceImpl"><property name="businessObjectDao"><ref bean="businessObjectDao" /></property><property name="persistenceStructureService"><ref bean="persistenceStructureService" /></property>

</bean></beans>



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:

<bean id="kraRootResourceLoader" parent="kraRootResourceLoaderParent">  <property name="overridableServices"> <set merge="true"> <value>firstServiceName</value> <value>secondServiceName</value> <value>etc...</value> </set> </property></bean>

• Rice Beans required as references into other beans may need to be exposed using the global resource loader:

<bean id="businessObjectDao" class="org.kuali.rice.kns.config.GlobalResourceLoaderServiceFactoryBean"> <property name="serviceName" value="businessObjectDao" /></bean>



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:

<bean id="customModConf" class="org.kuali.rice.kns.bo.ModuleConfiguration"> <property name="initializeDataDictionary" value="true" /> <property name="dataDictionaryPackages"> <list> <value>classpath:path/to/CustomDD1.xml</value> <value>classpath:path/to/CustomDD2.xml</value> </list> </property></bean>



Getting Help

• Revisit the quickstart_guide.txt in the KC 3.0.1 Source download

• Technical Collaboration mailing listhttp://www.kuali.org/kis/collabs/

• Your commercial affiliate

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

Documents

projectlicenses slide

mysql database instance

iowa state university

kr database schema slide

source zip curlwgetetc

location parameter

bat kc

current kc database