Date post: | 01-Apr-2015 |
Category: |
Documents |
Upload: | junior-purser |
View: | 216 times |
Download: | 1 times |
open source administration software for education
research administration
Up and Running: Basic Setup
Claus Niesen, Iowa State UniversityKristina Taylor, Iowa State University
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
open source administration software for education
Distribution Package Layout
Root directory
binary
kc-config.xml kc-ptd.war
db_scripts
ReadMe.txt KC_Install.sh (.bat)
kc_project licenses
open source administration software for education
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
open source administration software for education
db_scripts/ReadMe.txt
open source administration software for education
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;
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
open source administration software for education
KC_Install.bat or KC_Install.sh
open source administration software for education
KC_Install.bat or KC_Install.sh
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)
open source administration software for education
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>
open source administration software for education
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>
open source administration software for education
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>
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}
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.
open source administration software for education
quickstart_guide.txt – Step 8 (cont.)
open source administration software for education
quickstart_guide.txt – Step 8 (cont.)
open source administration software for education
quickstart_guide.txt – Step 8 (cont.)
open source administration software for education
quickstart_guide.txt – Step 8 (cont.)
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
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
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
open source administration software for education
Common Errors (cont.)
• External kc-config.xml file not found
open source administration software for education
Common Errors (cont.)
• External kc-config.xml file not found– Can be caused by starting with wrong user
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
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
open source administration software for education
Common Errors (cont.)
open source administration software for education
research administration
Up and Running: Grants.gov and s2s
Geo Thomas, MIT
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
open source administration software for education
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>
open source administration software for education
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
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
open source administration software for education
Testing connectivity
• Try accessing Opportunity list by going to Grants.Gov tab in KC application.
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
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
open source administration software for education
research administration
Up and Running: Advanced Setup
Claus Niesen, Iowa State UniversityKristina Taylor, Iowa State University
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
open source administration software for education
Rice Embedded
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
open source administration software for education
Embedded in KC: Setup (cont)
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/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
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)
open source administration software for education
Configuration Parameters: Overview(cont)
• Final Configuration can be viewed with the Configuration Viewer pages
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!
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
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.
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
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
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
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
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
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
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)
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
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)
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.
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.
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
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
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”
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
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:
<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.
open source administration software for education
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"><!-- Define service names that are overridable --><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>
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:
<bean id="kraRootResourceLoader" parent="kraRootResourceLoaderParent"> <!-- Define service names that are overridable --> <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>
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:
<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>
open source administration software for education
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