installation guide - fairmont state university · oracle database supported versions of the oracle...

BannerAdministrative Pages

Installation GuideBanner Admin Common Release 9.3.17

June 2019

Notices and Privacy

Notices and Privacy© 2017-2019 Ellucian.

Contains confidential and proprietary information of Ellucian and its subsidiaries. Use of thesematerials is limited to Ellucian licensees, and is subject to the terms and conditions of one or morewritten license agreements between Ellucian and the licensee in question.

In preparing and providing this publication, Ellucian is not rendering legal, accounting, or othersimilar professional services. Ellucian makes no claims that an institution's use of this publicationor the software for which it is provided will guarantee compliance with applicable federal or statelaws, rules, or regulations. Each organization should seek legal, accounting, and other similarprofessional services from competent providers of the organization's own choosing.

Ellucian's Privacy Statement is available at: www.ellucian.com/privacy.

Ellucian shall have the right to (a) use, store, process, modify, reproduce, distribute and displaycustomer data, and to grant sublicenses to third parties, for the sole purposes of providing thesoftware, performing Ellucian's obligations under its agreements with customers and complying withapplicable law or legal requirements; (b) use, store, process, modify and reproduce customer datafor Ellucian's internal business purposes, including development, diagnostic, forecasting, planning,analysis and corrective purposes in connection with the software, and for otherwise improving andenhancing the software; and (c) use, store, process, modify, reproduce, display, perform, distribute,disclose and otherwise exploit in any manner Aggregated Data for Ellucian's business purposes,including disclosure within its public statements and marketing materials describing or promotingEllucian or the software. “Aggregated Data” means any data obtained or generated by Ellucian,including data pertaining to the software, Ellucian's systems and software, and the use of any ofthe foregoing, and includes data derived from customer data, which in all instances (i) does notidentify any individual and (ii) is not attributed or attributable to a specific customer. AggregatedData includes data that has been combined into databases which include third party data.

Ellucian2003 Edmund Halley DriveReston, VA 20191United States of America

Ellucian - Confidential and Proprietary 2

https://www.ellucian.com/privacy

Contents

Contents

Before you get started.............................................................................................................. 6Supporting documentation............................................................................................................ 8Hardware requirements.................................................................................................................8Software requirements.................................................................................................................. 9

Oracle database......................................................................................................................9Web application servers......................................................................................................... 9Middle tier (application server) platforms............................................................................... 9Single sign-on (SSO) support.............................................................................................. 10Java dependencies...............................................................................................................10Software browsers................................................................................................................ 10Ellucian software requirements and setup........................................................................... 10

Ellucian Solution Manager............................................................................................ 10Ellucian applications.......................................................................................................11Banner Administrative Pages release version numbers................................................ 11Application Navigator.................................................................................................... 12

Navigation within the 9.x administrative applications.............................................. 12Allow users database access........................................................................................ 12

First time installing an Administrative Pages release............................................... 13Set up the web application server.............................................................................................. 13

WebLogic web application server configuration...................................................................13Create a new WebLogic machine..................................................................................13Create a new WebLogic managed server..................................................................... 14Create a new data source and connection pool............................................................15

Configure a Tomcat web application server.........................................................................16Edit the configuration files and provide the JDBC JAR file............................................16

Install CAS or Ellucian Ethos Identity certificate for the web application server......................... 18Install the release using Ellucian Solution Manager...................................................................18Add the machine for the web application server to Solution Manager....................................... 19Add the web application server to Solution Manager.................................................................20

WebLogic configuration settings...........................................................................................20Tomcat configuration settings............................................................................................... 21

Set up a staging directory on your Jobsub server..................................................................... 22Add the Admin Common (Administrative Pages) hosting application to Solution Manager........ 23Define the environment configuration......................................................................................... 23Deploy to your web application server....................................................................................... 27Clear the Administrative Pages views cache............................................................................. 27

Clear the views cache on a WebLogic managed server......................................................28Clear the views cache on a Tomcat web application server................................................ 28

Set up a service provider definition in your SSO provider......................................................... 29Set up Application Navigator...................................................................................................... 30

Edit the Application Navigator configuration file...................................................................32Next steps after your installation is complete.............................................................................32

Upgrade from a previous Administrative Pages 9.3.n.m release.......................... 34


Contents

Install the release using Ellucian Solution Manager...................................................................34Deploy to your web application server....................................................................................... 36Clear the Administrative Pages views cache............................................................................. 36

Clear the views cache on a WebLogic managed server......................................................36Clear the views cache on a Tomcat web application server................................................ 37

Set up a service provider definition in your SSO provider......................................................... 37Set up Application Navigator...................................................................................................... 38

Edit the Application Navigator configuration file...................................................................40Next steps after your installation is complete.............................................................................41

Use external configuration files..........................................................................................42Enable external configuration files and the Export Data feature for WebLogic.......................... 42Configuration properties file values............................................................................................ 43

Display ID image files..............................................................................................................46Prepare ID image files................................................................................................................ 46Define HTTP access to image files with WebLogic....................................................................47Define HTTP access to image files with Tomcat........................................................................48Configure access to ID image files.............................................................................................49

Configuration settings to access image files........................................................................49

Change single sign-on configuration from CAS to SAML....................................... 51Modify the configuration files...................................................................................................... 51

Edit the config.xml file.....................................................................................................52Edit the applicationContext.xml file........................................................................... 52Edit the appsupportlib.config.xml file....................................................................................53

Provide a digital certificate..........................................................................................................54Extract the Ellucian Ethos Identity certificate....................................................................... 55Add the Ellucian Ethos Identity certificate to the Banner pages configuration file................56

Update the WAR files and EAR file............................................................................................57Set up the Ellucian Ethos Identity service provider....................................................................58Redeploy the WAR or EAR files.................................................................................................59

Redeploy the WAR or EAR files prerequisites.....................................................................59Redeploy the WAR files using Tomcat.................................................................................59Redeploy the EAR file with WebLogic................................................................................. 60

Multi-language support........................................................................................................... 61Customized translation of labels and messages........................................................................ 61Supported languages for browser settings................................................................................. 62Supported calendars................................................................................................................... 63Support for language-specific sorting......................................................................................... 63Language-specific label and message properties files...............................................................64

Location of the properties file...............................................................................................64Languages that are territory-specific.................................................................................... 64

Data mapping for JLOC2ORA and JLO2ORAX......................................................................... 65Edit the JLOC2ORA and JLOC2ORAX tables........................................................................... 73

JLOC2ORA and JLOC2ORAX edits.................................................................................... 73

Jasper Server Installation and Configuration for Banner Reports....................... 79


Contents

System requirements.................................................................................................................. 79Prepare for Installation................................................................................................................80Install JasperReports Server.......................................................................................................80Install license...............................................................................................................................82Configure JasperReports Server for Banner reports.................................................................. 83Deploy/Import Reports in Jasper Server.................................................................................... 84Configure JNDI datasource in JasperReports Server................................................................ 85Troubleshooting Error Running js-install scripts......................................................................... 86

Third-party document image integration configuration............................................88Update the BannerAdmin.war file for third-party document imaging integration.........................88Update config.properties file for the BannerAdmin.ws.war file for third-party documentimaging integration...................................................................................................................... 89Redeployment of Banner Administrative Pages with updated configuration files....................... 90

Redeploy to a WebLogic application server.........................................................................90Redeploy to a Tomcat application server.............................................................................91

Runner plugin integration......................................................................................................93


Before you get started

Before you get startedReview these prerequisites for hardware, software, and the supporting documentation.

After reviewing the prerequisites, go to the section that applies to your installation.

• First time installing an Administrative Pages release on page 13• Upgrade from a previous Administrative Pages 9.3.n.m release on page 34

Note: The new Administrative Pages application replaces the previously released XE (ZK)administrative applications. The Banner XE pages that used ZK technology have been transformedto Java pages. The new functionality that the Banner XE pages introduced will continue to beprovided in the transformed Administrative Pages 9.3.n.m version of the pages.

Table 1: List of Banner XE pages and their associated modules

Page name Page description Associated module

GEAATID Event Registration Events

GEAATTD Attendance Events

GEAATRK Attendance Tracking Events

GEAFCOM Function Comments Events

GEAPART Function Participants Events

GEIIDEN Entity Query Events

GEIIDFN Individual Function Inquiry Events

GUAINFO Information Text Editor Student Overall

SFABLCK Block Registration Control Registration

SFABLPA Student Block Pre-Assignment Registration

SFABRDF Block Rule Definition Registration

SFAESTS Enrollment Status Control Registration

SFAMHRS Registration Minimum MaximumHours

Registration

SFIWLNT Waitlist Notification Query Registration

SFAPABC Pre-assigned Block Configuration Registration

SFARCTT Registration Priority Control Registration

SFAROVR Registration Permit-OverridesControl

Registration

SFARSTS Course Registration Status Registration




SFARWLP Reserved Seats Waitlist PriorityManagement

Registration

SFASTCA Student Course Registration Audit Registration

SFATMST Time Status Rules Registration

SFAWLPR Waitlist Priority Management Registration

SFAXWLP Cross List Waitlist PriorityManagement

Registration

SFIBSEL Student Block Selection Inquiry Registration

SFQSECT Registration Course Query Registration

SGACOOP Cooperative Education Academic History

SHAEGBC Electronic Gradebook Control Student Overall

SHAGCOM Gradable Component Definition Student Overall

SHATCKN Student Course Maintenance Academic History

SHAINST Student Term Course Maintenance Academic History

SLAEVNT Event Events

SLIAEVN Event Available Room Query Events

SOAATMT Attendance Tracking Meeting RuleSetup

Attendance Tracking

SOAATRK Attendance Tracking Rule Setup Attendance Tracking

SOAHOLD Hold Information Registration

SOAIDEN Person Search Student Overall

SOAIDNS Person Search Detail Student Overall

SOAORUL Open Learning Section DefaultRules

Student Overall

SOAPERS Persona Rule Control Student Overall

SOAREST External API ConnectionInformation

Student Overall

SOATERM Term Control Student Overall

SOAWLTC Automated Waitlist Term Control Student Overall

SOAWSCR Overall Page and FieldConfiguration

Student Overall

STVGCHG Grade Change Code Validation Student Overall

STVPERS Persona Validation Student Overall

STVREST External API Information Validation Student Overall




STVRSTS Course Registration Status CodeValidation

Registration

STVWSFD Overall Configurable Page FieldValidation

Student Overall

STVWSPG Overall Configurable PageValidation

Student Overall

Supporting documentation

There is additional documentation available that is associated with the installation process.

• To access documentation for any release you download through Solution Manager, go toProducts page > Latest Available Releases version number and click the documentationicon.

• Banner Single Sign-On Handbook - found in the Banner General library in the EllucianCustomer Center.

• Solution Manager Installation and Configuration Guide - found in the Ellucian Solution Managerdocumentation library in the Ellucian Customer Center.

• Solution Manager User Guide - found in the Ellucian Solution Manager documentation library inthe Ellucian Customer Center. The same information is available in the Solution Manager onlinehelp.

• Application Navigator Installation Guide - found in the Banner General library in the EllucianCustomer Center.

• Banner XE Sizing and Configuration Guide - found in the Banner XE Sizing and Configurationlibrary in the Ellucian Customer Center.

Hardware requirements

These are the minimum hardware requirements.

CPU and memory

Recommended: Quad core CPU with 4 to 8 GB of memory for the application server.

Minimum: Dual core CPU with 2 GB of memory for the application server.

Screen resolution

The minimum PC screen resolution is 1024 x 768.



Software requirements

These are the minimum software requirements.

Oracle database

Supported versions of the Oracle database depend on multiple factors, including third-party supporttime lines. For a complete list of supported Oracle technologies, refer to the Ellucian Oracle SupportCalendar. The calendar is available in the Interactive Banner Compatibility Guide, which you canaccess from the Ellucian Download Center.

Web application servers

The Administrative Pages applications are supported by WebLogic and Tomcat web servers.

• Oracle WebLogic: 10.3.6, 12.2.1• Apache Tomcat: 7 and 8

Oracle Fusion Middleware (OFM) consists of several software products, including WebLogic Server.Oracle Banner 9.x application server environments require WebLogic. No other OFM products arerequired. However, if you are using an SSL-enabled Oracle HTTP Server (OHS) port, you shouldalso install the Oracle Web Tier to use the Oracle WebLogic Server proxy plug-in (mod_wl_ohs).

Middle tier (application server) platforms

The Administrative Pages applications support multiple operating systems on both Tomcat andWebLogic application servers.

Tomcat (64 bit) WebLogic (64 bit)

Red Hat Linux 5.3 (minimum version) Red Hat Linux 5.3 (minimum version)

Windows Server 2008 Windows Server 2008

Solaris 10 Solaris 10

AIX 6.1 (JDK 1.7 SR 10 or later) AIX 6.1 (JDK 1.7 SR 10 or later)

HP UX HP UX: 11iV3 (11.31)

Note: You can create the managed server for the Banner Administrative Pages application in eithera WebLogic Classic domain or base domain. If you choose to deploy to a managed server in aClassic domain, you must ensure that the managed server is properly configured for successfulautomated deployment of the Banner Admin Pages application through Solution Manager, asdescribed in Article 35085 in the Ellucian Customer Center regarding deployment of Bannertransformation applications to a WebLogic Classic domain.



Single sign-on (SSO) support

You must establish the single sign-on environment before implementing Administrative Pages.Central Authentication Service (CAS) and Security Assertion Markup Language (SAML) 2.0 are thesingle sign-on (SSO) protocols supported by Administrative Pages. Both are certified to run withEllucian Ethos Identity.

You can download Ellucian Ethos Identity from the Ellucian Customer Center. For more informationon how to establish a single sign-on environment, refer to the Banner Single Sign-On Handbookor Setting Up Ellucian Ethos Identity. Both are available for download from the Ellucian CustomerCenter.

Java dependencies

The Administrative Pages application is currently supported on Java 7 and 8, and Java 1.7.x or1.8.x JDK (64-bit version) must be installed on the web application server before you deploy theapplication.

Software browsers

Banner Administrative Pages currently supports using the following browsers.

• Internet Explorer 11• Google Chrome• Mozilla Firefox• Safari 6 or 7• Microsoft Edge

For more information about supported browsers, refer to the Interactive Banner Compatibility Guideon the Ellucian Customer Center.

Ellucian software requirements and setup

Make sure that you have the required software and setup that Ellucian applications need to use theAdministrative Pages applications.

Ellucian Solution Manager

You must install or upgrade to Solution Manager version 1.12 or later to download and installBanner Admin Common 9.3.17 and the other Banner Administrative Pages 9.3.n releases that haveBanner Admin Common 9.3.17 as a prerequisite.

See the Ellucian Solution Manager content pack in the Documentation Libraries of the EllucianCustomer Center for installation and upgrade instructions.



For best results, Ellucian recommends that you upgrade Solution Manager to the latest availableversion.

Ellucian applications

Banner Admin Common 9.3.17 is compatible with all previously released 9.3.n versions of Bannerproducts and localizations which are in an Active and Maintenance Support Status at the time of thisAdmin Common 9.3.17 release.

Banner Administrative Pages releases deploy as a single Java web application. Through EllucianApplication Navigator, you have access to all of the pages in the Banner General, AccountsReceivable, Finance, Financial Aid, Human Resources, Position Control, Student, Student Aid,Document Management, and Document Retention products, and the localizations that extend theseproducts.

The upgrade for each product has additional product-specific requirements, which you can findin the Installation Reference document for each product. This is available in the Ellucian SolutionManager release package for each product and in the Documentation Libraries section of theEllucian Customer Center.

Note: Solution Manager checks for the latest required software with each installation you perform.If you do not have the required software, Solution Manager prompts you to install that software orautomatically includes it in the upgrade job if it is available through Solution Manager.

If you have the following software installed, these are the minimum versions required.

• Luminis 5.2.2 patch 51• Banner Workflow 8.5• Banner Channels 8.4.0.1

Banner Administrative Pages release version numbers

Ellucian uses a five-part release version number for each Banner Administrative Pages productrelease package.

The first four parts of the version number represent the product release version number, and the fifthpart is the release package build number. Ellucian defines the five-part release version number forAdministrative Pages releases as follows:

1. Major Banner Release Version2. Major Admin Common Release Version3. Scheduled Update Release Version4. Unscheduled Minor Update Release Version5. Internally-generated Build Number

Earlier Banner Administrative Pages release packages used a four-part version number, wherethe first three parts represented the product release version number and the fourth part was thepackage build number.



Application Navigator

Application Navigator provides seamless navigation between Banner 9.x administrative applications.

Navigation within the 9.x administrative applications

To navigate among your installed Banner 9.x administrative applications, you must updateconfiguration information in the Banner database that Application Navigator uses to access theinstalled Banner 9.x administrative application pages. Refer to Set up Application Navigator on page30 for instructions on how to enter configuration information.

Allow users database access

To allow Administrative Pages users database access, you must grant the BANPROXY user accessto read the BANSECR.GUBIPRF table.

Procedure

1. Issue the following grant in your database:grant select on bansecr.gubiprf to banproxy

2. To ensure that a user is allowed to log in to Banner as BANPROXY, access the user on theSecurity Maintenance (GSASECR) page.

3. Select the Authorize ban proxy check box if not already selected to grant the user access.


First time installing an Administrative Pages release

First time installing an Administrative Pagesrelease

To install the Administrative Pages release for the first time, you must perform the initial installationand configuration steps.

Set up the web application server

You can use a WebLogic web application server or a Tomcat web application server with BannerAdministrative Pages.

WebLogic web application server configuration

Follow these instructions if using a WebLogic web application server.

Create a new WebLogic machine

Create a machine for the WebLogic server.

Before you begin

• You must have WebLogic installed. If it is not, download and install the WebLogic Server fromthe Oracle website. This release is compatible with WebLogic 10.3.6 or WebLogic 12c (12.2.x).If you install WebLogic 10.3.6, make sure the domain you use to run Banner AdministrativePages uses the ojdbc7.jar file, available from Oracle JDBC Drivers (use the Oracle 12.1.0.2version).

• You must have both the WebLogic node manager and the administration server started. Accessthe administration server using a URL similar to this: HTTP://server:7001/console.

Procedure

1. In the Change Center frame, click Lock & Edit.2. In the Domain Structure frame, expand the environments list, select Machines, and click New.3. Enter a machine name, and click Next.4. Accept the defaults, and click Finish.5. In the Change Center frame, click Activate Changes.


https://www.oracle.com/technetwork/database/application-development/jdbc/downloads/index.html


Create a new WebLogic managed server

If you previously created a WebLogic server for the application, you can use the same server.

Procedure

1. In the Change Center frame, click Lock & Edit.2. In the Domain Structure frame, expand the list of environments, select Servers, and click

New.3. Enter a server name and server listen port, and click Finish.

For example, you can enter a server name as BannerAdmin and server listen port as 7020.4. Click the created server link.5. Under the General tab, assign the machine to this server, and click Save.6. Select the Server Start tab, and add the following Arguments in the text area.

Parameter Notes

-Dlog4j.configuration=config.properties- Xms2816m -Xmx4g -XX:MaxPermSize=768m

-Djava.io.tmpdir=temp-files-path temp-files-path is the absolute path to adirectory to which the WebLogic managedserver has write access. For example,

-Djava.io.tmpdir=/tmp/BannerAdmin

If you do not specify a temp directory usingthis parameter, temporary files, including aviews cache directory, will write directly to the/tmp directory.

Specifying a target directory ensures thatthose files do not combine with temporary filescreated by other applications. It also ensuresthat a second managed server running on thesame machine does not overwrite files for thismanaged server.

7. Click Save, and in the Change Center frame, click Activate Changes.8. Review Use external configuration files on page 42. If you plan to use external configuration

files, perform the additional setup steps for a WebLogic managed server outlined in that section.9. In the Domain Structure frame, click Servers.10. Select the Control tab and select the check box next to your new server definition.11. Click Start.



Create a new data source and connection pool

Create a new data source and connection pool to complete the WebLogic configuration.

Procedure

1. In the Change Center frame, click Lock & Edit.2. In the Domain Structure frame, expand Services and select Data Sources.3. Click New.4. Select Generic DataSource, and specify the name bannerDataSource.5. For JNDI name, specify bannerDataSource.6. For Database Type, specify Oracle, and click Next.7. For Service Connections select OracleDriver(Thin), and click Next.8. Clear the Supports Global Transactions check box, and click Next.9. Enter the following information, and click Next.

Field Description

Database name For example, BANTEST.

Hostname For example, yourhostname.yourdomain.com

Port For example, 1521.

Username banproxy

Password your banproxy password

10. Click Test Configuration, and click Next.11. Select the managed server that you previously created to allow the data source to be deployed

and used by this server, and click Finish.12. Select the data source link you created, select the Connection Pool tab, enter the following

information, and click Save.

Field Description

Initial Capacity 25

Maximum Capacity 400

Statement Cache Type FIXED

Statement Cache Size 0

13. In the Change Center frame, select Activate Changes.14. In the Domain Structure frame, expand Services, and select Data Sources.15. Select the data source you created, and select the Targets tab.16. Select the check box next to the name of the new managed server you set up, and click Save.



Configure a Tomcat web application server

Use the instructions in this section to configure a Tomcat web application server.

Edit the configuration files and provide the JDBC JAR file

To configure your Tomcat server, you must edit the configuration files and provide the JDBC JARfile.

Procedure

1. For the system account that runs the Tomcat application server, configure the environmentsettings to support the application.On Linux, ensure that you defined CATALINA_HOME to reference your Tomcat softwareinstallation location.CATALINA_HOME=/opt/apache-tomcat-xxx, where xxx indicates the version of Tomcatyou installed and opt is the directory of the Tomcat installation.

2. Define JAVA_OPTS to configure the JVM settings. Ellucian recommends the following settings:

JAVA_OPTS="-Dlog4j.configuration=config.properties -Xms2048m -Xmx4g -XX:MaxPermSize=1024m"

You can define this variable in the account's profile startup script and export the value to make itavailable to the Tomcat startup script, or you can add this definition in $CATALINA_HOME/bin/catalina.sh.

3. Optional: Set up the Tomcat server to enable remote JMX connections. This is useful fordebugging and logging.a) Add the following options to the Catalina.sh file, and restart the Tomcat server.

set CATALINA_OPTS=-Dcom.sun.management.jmxremote-Dcom.sun.management.jmxremote.port=8999-Dcom.sun.management.jmxremote.ssl=false-Dcom.sun.management.jmxremote.authenticate=false-Djava.rmi.server.hostname=your.hostname.com

b) Change the -Djava.rmi.server.hostname value to the host name or IP address of themachine where you installed Tomcat.For example, -Djava.rmi.server.hostname=prod.appserver1.com or

-Djava.rmi.server.hostname=149.24.3.178

c) Optional: JMX does not define a default port number to use. If necessary,changecom.sun.management.remote.port to use port 8999.

Note: Ellucian recommends that you connect remotely to the Tomcat server user JMX.

4. Define the JNDI datasource resource name for the application.a) Edit the context.xml file in the $CATALINA_HOME/conf directory to uncomment

<Manager pathname="" />.


For example, <Manager pathname="" />

b) Add this ResourceLink definition inside the <Context> element, and save your changes incontext.xml.

<ResourceLink global="jdbc/bannerDataSource"name="jdbc/bannerDataSource" type="javax.sql.DataSource"/>

c) Edit the server.xml file in the $CATALINA_HOME/conf directory to configure thedatabase JNDI resource name and connection pool configuration by adding the followingResource definition inside the <GlobalNamingResources> element.For example, if your database server name is myserver.university.edu and theOracle TNS Listener is accepting connections on port 1521, and your database servicename is SEED, the entry would look like this for Tomcat 7:

<Resource name="jdbc/bannerDataSource" auth="Container" type="javax.sql.DataSource" driverClassName="oracle.jdbc.OracleDriver" url="jdbc:oracle:thin:@//myserver.university.edu:1521/SEED" username="banproxy" password="the_banproxy_password" initialSize="25" maxActive="400" maxIdle="-1" maxWait="30000" validationQuery="select 1 from dual" testOnBorrow="true"/>

For Tomcat 8:

<Resource name="jdbc/bannerDataSource" auth="Container"type="javax.sql.DataSource"driverClassName="oracle.jdbc.OracleDriver"url="jdbc:oracle:thin:@//myserver.university.edu:1521/SEED"username="banproxy" password="the_banproxy_password"initialSize="25" maxTotal="400" maxIdle="-1" maxWaitMilllis="30000"validationQuery="select 1 from dual" testOnBorrow="true"/>

d) Save your changes in server.xml.e) Download the ojdbc7.jar file from Oracle JDBC Drivers (use the Oracle 12.1.0.2 version)

and copy it to the $CATALINA_HOME/lib directory.f) Validate the configuration by starting the application server and accessing the Tomcat

Management Server page.


https://www.oracle.com/technetwork/database/application-development/jdbc/downloads/index.html


Install CAS or Ellucian Ethos Identity certificate for the webapplication server

The web application server that runs Administrative Pages must have the security certificate of yourCAS or Ellucian Ethos Identity server installed as a trusted certificate for access by single sign-onthrough Application Navigator.

See the Banner Single Sign-On Handbook for information on installing the CAS or Ellucian EthosIdentity security certificate on a client web application server.

Install the release using Ellucian Solution Manager

Install this release using Solution Manager. Solution Manager is a software system that allows forthe download, installation, configuration, and management of Ellucian products.

About this task

Selecting Get New Releases in Solution Manager, downloads all of your available, licensed Bannerrelease packages.

The release version number that shows in Solution Manager for all of the upgrades that are part ofthe Administrative Pages 9.3.n.m releases is in the format 9.3.n.m.x, where 9.3.n.m is the releasenumber (such as 9.3.0, 9.3.1, 9.3.1.1, etc.), and x is the package build number of the releasepackage for each product. The package build number for some products may be different fromothers. All references to the upgrade release package version number in this document is in theformat 9.3.n.m.x.

Warning! With the Banner 9.3.n.m releases, there is a new product, Banner Admin Common. Youmust install Banner Admin Common, because it contains the required common libraries and filesyou need to deploy the Administrative Pages applications.

After you install the Banner Admin Common 9.3.17.0.x. release and your selected 9.3.n.m.x productreleases, deploy the Administrative Pages application by running the Solution Manager deploymentjob associated with the Banner Admin Common 9.3.17.0.x release.

Procedure

1. In Solution Manager, go to the Products tab, and in the Name column, find the BannerAdministrative Pages 9.3.n.m.x release for each product and localization you want to install.Ellucian recommends that you select all of the Administrative Pages releases that you want toinstall at once, so that you have to run the upgrade job only one time.

2. For each product that you want to install, click the Latest Available Release column to accessthe Available Releases page.

Note: If you do not see a release on the Available Releases page, download new releases withSolution Manager to refresh the list.



3. Select the Target Release option for the 9.3.n.m.x version you want, and click OK to return tothe Products page.

4. Scroll down the Products page to view Selected Target Release for all products, and clickUpgrade.Solution Manager includes in the upgrade job any prerequisite releases that you have notpreviously installed.

5. Enter a description for the upgrade job in the Description field.6. Click Upgrade Properties for each upgrade in the upgrade job, and review the information.

a) Enter any required information the messages that display, and select the check box toacknowledge each message.

7. Click Start Upgrade to run the upgrade job.8. Monitor the upgrade job status.

The following message displays when the upgrade successfully completes:

BMUI upgrade task completed with status: 0Finished: SUCCESS

On the Upgrade tab, the Install Status displays the message Successfully Completed.

Results

The release package for each product updates the GUBMODU, GUBPAGE, GUROPTM, andGUBOBJS tables as required for the transformed Administrative Pages.

If you previously installed any Banner 9.x XE (ZK) Administrative applications, this release willchange the GUBPAGE entries for some of the pages in those applications to make them part of theAdministrative Pages application (modules SP, CAP, and TP). They will no longer be accessiblefrom Application Navigator as part of the previously installed administrative applications (theADMZK modules). The new Administrative Pages application replaces the previously released XE(ZK) administrative applications.

The Banner Admin Common 9.3.17.0.x release package delivers a file named release-Admin-9.3.17.0.x.zip (where x is the package build number for the current release) into theBanner-home/general/java directory. Other product release packages deliver a file namedrelease-Admin-product-9.3.n.m.x.zip, depending on the version you selected to install,into the corresponding Banner-home/product/java directory. These files contain the binaries,configuration file templates, and other files required to deploy the application.

Add the machine for the web application server to SolutionManager

To prepare for deployment, you must define the configuration of the web application server to whichyou will deploy the application in your environment setup in Solution Manager.

Procedure

1. In Solution Manager, go to the Machines tab for your environment, and click Add.



2. Enter the Admin (Private) Host Name of the machine, select the App role, and click Add.3. Select the row for the new machine in the Machines table to open up the machine configuration

page.4. Enter the Public Network Host Name. It must be just the host name portion of the machine's

fully qualified domain name.For example, if the machine's fully qualified domain name isappserver1.myinstitution.edu, then you should enter appserver1 in the machine'sPublic Network Host Name field.

5. On the Env Settings page, under Environment Appservers – Public Network > Domain > ,enter the domain name.For example, if the fully qualified domain name for the machine is appserver1.myinstitution.edu,you should enter myinstitution.edu in the Domain field in the Environment Appservers -Public Network section of the Env Settings page.

Add the web application server to Solution Manager

Before you can deploy the application, you must define in your environment setup in SolutionManager the web application server that you have configured to run it.

Procedure

1. In Solution Manager, go to the App Servers tab for the environment and click Add.2. Enter a name for your WebLogic or Tomcat web application server.3. Choose the appropriate type and click Add.4. Select the row for the new app server in the App Servers table to access the App Server

Configuration page.

WebLogic configuration settings

If you are using a WebLogic web application server, enter these configuration settings.

Field Description

Managed Server Name Must match the name of the managed server that you set up to run theapplication in WebLogic.

Admin Port Number Port number of the WebLogic administrative server. Use the AdminPort Number to connect to WebLogic and deploy the application.

Application Port Number Port number of the WebLogic managed server that you set up to runthis application. Use the Application Port Number to configure theapplication when it is deployed.



Field Description

Use SSL If the application port number you entered is a secure (HTTPS) portnumber, select the UseSSL check box. The deployment script uses“HTTPS” instead of “HTTP” in the application's URL.

If you choose to access the application through a secure (HTTPS)endpoint, you are responsible for setting up and installing the requiredsecurity certificate on the application server.

Admin User Name andPassword

Same user name and password that you use to log into the WebLogicadministrative console. The deployment process uses the AdminUser Name and Password to connect to WebLogic to deploy theapplication.

Note: If you are using Ellucian Solution Manager version 1.8 Update2 or later: Instead of using the Admin User Name and Password,Ellucian recommends that you set up secure WebLogic credentialsand use the User Config File and User Key File fields to specify theinformation needed by Solution Manager to deploy the applicationto WebLogic. See the Ellucian Solution Manager User Guide or theSolution Manager online help for additional information.

Domain Name

Domain EnvironmentSetup Script

You must enter the correct WebLogic domain name and the correct fullpath to the domain environment setup script for the WebLogic server.Deploying the application to WebLogic requires the Weblogic domainname and the domain environment setup script.

Banner Pages App DataPath

If you want to use external configuration files, enter the absolutepath for storage of these files. The system account running the webapplication server must have write privileges for this path. See Useexternal configuration files on page 42 for additional information.

This must be the same path that you specified for the "app" JNDIproperty when you set up the WebLogic managed server.

Tomcat configuration settings

If you are using a Tomcat web application server, enter these configuration settings.

Field Description

Admin Port Number Not applicable.

Not used by Solution Manager at this time for Tomcat applicationservers.

Application Port Number Application port number of your Tomcat web application server.(Typically, the application port number for a Tomcat web applicationserver is the same as the admin port number.) The application portnumber is used to configure the application when it is deployed.



Field Description

Use SSL If the application port number you entered is a secure (HTTPS) portnumber, select the UseSSL check box. This causes the Bannerpages deployment script to use “HTTPS” instead of “HTTP” inconfiguring the application's URL.

If you choose to access the application through a secure endpoint,you are responsible for setting up and installing the required securitycertificate on the app server.

Catalina WebApps Path This should be the full path to the Tomcat webapps directory whereyou want the Banner pages application to be deployed. This path isused to deploy the application.

Admin User Name andPassword

Not applicable. These are not used by Solution Manager at this timefor Tomcat app servers.

BannerPages App DataPath

If you want to use the external configuration files feature, enter theabsolute path for storage of external configuration files. The systemaccount running the Tomcat web application server must have writepermissions for this path.

See Use external configuration files on page 42 for additionalinformation.

Set up a staging directory on your Jobsub server

To stage the application for deployment, you must set up a staging directory on your Jobsubmachine and enter the path on the machine that hosts the Jobsub application in Solution Manager.

About this task

This is necessary only if you have not set up a staging directory for the Banner 9.x deployments. Formore information see the “Deployment Jobs” section in the Ellucian Solution Manager User Guide orin Solution Manager online help.

Procedure

1. In Solution Manager, go to the Applications tab for your environment, and select the row forthe Jobsub type in the Applications table.

2. Click Go to Machine to go to the Machine page for the machine that hosts the Jobsubapplication.

3. Enter the staging directory path in the Banner 9 WAR File Staging Path field.



Add the Admin Common (Administrative Pages) hostingapplication to Solution Manager

Enter the path in Solution Manager used to stage the application for deployment.

Procedure

1. In Solution Manager, go to the Applications tab for your environment, and click Add.2. Give the application a unique name.3. Select the BXE type, and click Add.4. Select the row for the new application in the Applications table.5. From the Machine/App Server list, select the application server and machine combination that

corresponds to the web application server you installed for deployment of this AdministrativePages application.

6. Click Go to Machine to go to the Machine page for the machine that hosts the Jobsubapplication.

7. Enter the Banner 9 WAR File Staging Path from the perspective of the machine on which theAdministrative Pages web application server is installed.

Define the environment configuration

Use this information to configure the Administrative Pages application during deployment.

Procedure

1. In Solution Manager, go to the Env Settings tab for your environment.2. Enter the following information to complete the Environment Configuration settings.

Field Description

SSO Protocol Select the Single Sign-On (SSO) protocol that you want to use whendeploying Banner Administrative Pages. Choose CAS or SAML.



Field Description

Note: The following fields are only available if you deploy BannerAdmin Common using Ellucian Solution Manager (ESM) version 1.13or a later version.

• SSO Protocol• SAML Configuration Files Directory• SAML Service Provider Metadata File Name• SAML Identity Provider Metadata File Name• SAML Keystore File Name• SAML Keystore Password

If you deploy Banner Admin Common using an earlier version of ESM,it will automatically deploy Banner Admin configured for CAS SSOprotocol. To change the SSO protocol to SAML you must edit theconfiguration files after you initially deploy through ESM as describedin Change single sign-on configuration from CAS to SAML on page51.

Identity ServicesURL

Enter the root URL for your CAS protocol identity services application.This is typically Ellucian Ethos Identity (EEId) or Central AuthenticationService (CAS).

Example: https://auth.myinstitution.edu:8443/cas

Note: If using Solution Manager version 1.13 or later, you can leavethis field blank if you did not select CAS for the SSO Protocol.

SAML ConfigurationFiles Directory (fullpath, Jobsub)

If you selected SAML for the SSO Protocol, enter the full path to thedirectory containing the stored SAML service provider and identityprovider metadata files. The ESM Banner Pages deployment processthat builds the Banner Admin WAR file on the Jobsub machine (step1 of the Banner Pages deployment job) must have read access to thespecified directory and to the files in the directory.

For example, if you store your SAML service provider and identityservice provider metadata files in a directory named saml-config-files in your Banner 9 WAR file staging area, and the path to thatstaging area specified on your Jobsub Machine is /usr/staging/ban9 (Linux/Unix) or D:\banstage\ban9 (Windows), enter /usr/staging/ban9/samlconfig-files (for Linux/Unix) or D:\banstage\ban9\samlconfig-files (for Windows).

Leave this field blank if you did not select SAML for the SSO Protocol.

SAML ServiceProvider MetadataFile Name

If you selected SAML for the SSO Protocol, enter the name of the filecontaining the SAML service provider metadata. You must store thefile in the directory you specified in the SAML Configuration FilesDirectory field.



Field DescriptionBanner Admin Common delivers a sample SAML service providermetadata file in the Banner Admin Common zip file at the followinglocation:

BannerAdmin/deliver/config/BannerAdmin.ws/WEB-INF/classes/banner-sp-metadata.xml


SAML IdentityProvider MetadataFile Name

If you selected SAML for the SSO Protocol, enter the name of the filecontaining the SAML identity provider metadata. You must store thefile in the directory you specified in the SAML Configuration FilesDirectory field.

Banner Admin Common delivers a sample SAML identity providermetadata file in the Banner Admin Common zip file at the followinglocation:

BannerAdmin/deliver/config/BannerAdmin.ws/WEB-INF/classes/wso2-idp.xml


SAML Keystore FileName (full path, AppServer)

If you selected SAML for the SSO Protocol, enter the full path to thefile containing the SAML keystore.

For example:

• /home/tomcat/banadmsamlsso/samlkeystore.jks (Linux/Unix)

• D:\banadmsamlsso\samlkeystore.jks (Windows)

Note: The location of the keystore file is on the web application serverwhere Solution Manager deploys the Banner application, so the pathspecified must be the path on that server. The system account thatruns the web application server must have read access to the file.


SAML KeystorePassword

If you selected SAML for the SSO Protocol, enter the keystorepassword that the Banner Admin application will use to read the SAMLkeystore file.


ApplicationNavigator URL

Enter the base URL for accessing Application Navigator.

Example: https://appnav.myinstitution.edu:8888/applicationNavigator



Field Description

Reports Server URL Enter the Jasper Reports Server URL if you are planning to deployreports. See Jasper Server Installation and Configuration for BannerReports on page 79 for additional information.

Example: https://jasperserver.myinstitution.edu:8443/jasperserver-pro

Theme Server URL Enter the URL of the custom theme server that Banner 9Administrative Pages should use in the environment.

Example 1:

* If you are using the Banner Theme Editor from Banner Extensibility(see the Theme Editor section of the Banner Extensibility Handbookavailable in the Ellucian Customer Center for additional information):

http://themeserver.greatvalleyu.edu:8080/BannerExtensibility/theme/getTheme?name=greatvalleyu&template=admin

Example 2:

* If you are using the cloud-based Ellucian Theme Editor (see theEllucian Theme Editor Handbook available in the Ellucian CustomerCenter for additional information):

https://theme.elluciancloud.com/<theme-client-ID>/theme/getTheme?name=<theme-name>&template=<template-name>

where

<theme-client-ID> is the client ID you received when you registered foruse of Ellucian Theme Editor<theme-name> is the name of the theme you defined in Theme Editorthat you want to use<template-name> is the name of the template you defined in ThemeEditor that you want to use

Leave this field blank if you are not using a theme server.

ID Image Files URL Enter the URL of the ID images server that Banner AdministrativePages should use in the environment.

For example, http://imgserver.greatvalleyu.com:8180/resources/id_images/

Leave this field blank if you are not using an ID images server.

See Display ID image files on page 46 for additional information.

ID Image Files NameFormat

Select the ID image files name format value from the drop-down list.

Do not select an option in this field if you are not using an ID imagesserver.



Field DescriptionSee Display ID image files on page 46 for additional information.

ID Image FilesExtension

Select the ID image files filename extension value from the drop-downlist.

Do not select an option in this field if you are not using an ID imagesserver.

See Display ID image files on page 46 for additional information.

Deploy to your web application server

This process assembles and deploys a single Administrative Pages application for all Bannerbaseline products and any localization packages you have installed.

Procedure

1. In Solution Manager, go to the Deployments tab for your environment and select thedeployment job associated with the Banner Admin Common 9.3.17.0.x upgrade to display theDeployment page. That deployment job creates and deploys a single Administrative Pagesdeployment containing the latest installed version of each of the Administrative Pages upgradesthat you have installed.

2. On the Deployment page, in the Application Servers table, select the web application server towhich you want to deploy the application.

3. Click Start Deployment.4. Optional: If the Monitor page does not display on the Deployments tab, click Monitor

to monitor the deployment job. When each deployment step completes, you will see thegreen check mark icon. As each step is complete, you can click the Console icon on theDeployment Monitoring tab to see the console log file.When the deployment completes successfully, a Deployment Status of Complete appears onthe Deployments tab.

Clear the Administrative Pages views cache

If you are deploying a new version of the Banner Administrative Pages application to the same webapplication server where you were running a previous version, you must clear the views cache.

The Banner Administrative Pages application caches HTML views on the server to improveperformance, so you must clear the cache when you deploy a new version to ensure that the pagesfor the new version display properly.



Clear the views cache on a WebLogic managed server

For Weblogic managed servers the views cache is stored in the temporary files location.

About this task

By default WebLogic temporary files are stored in the /tmp directory. You can control wherethey are stored by using the java.io.tmpdir property in the Server Startup parameters forthe managed server. See Create a new WebLogic managed server on page 14 for additionalinformation.

Perform the following steps to clear the views cache for Banner Administrative Pages deployed to aWeblogic managed server.

Procedure

1. Using the Weblogic console, stop the BannerAdmin deployment on the managed server thatyou deployed Banner Administrative Pages to.

2. If you specified the temporary files location using the java.io.tmpdir property, delete all thefiles in that directory. If the temporary files are being written to the default location /tmp,delete the files morphis%002ecache%002eviewscache.data and morphis%002ecache%002eviewscache.index.

3. Using the Weblogic console, restart the BannerAdmin deployment.

Clear the views cache on a Tomcat web application server

For Tomcat web application servers, the views cache is stored in the temporary files location.

About this task

By default, Tomcat stores temporary files in the $CATALINA_HOME/temp directory. You canoverride this location by specifying -Djava.io.tmpdir when starting Tomcat. Perform thefollowing steps to clear the views cache for Banner Administrative Pages deployed to a Tomcat webapplication server.

Procedure

1. Shut down the Tomcat instance that hosts the Banner Administrative Pages application.2. Delete the files morphis%002ecache%002eviewscache.data and morphis%002ecache

%002eviewscache.index from the $CATALINA_HOME/temp directory, or from thetemporary files directory specified by -Djava.io.tmpdir in your Tomcat configuration.

3. Restart the BannerAdmin and BannerAdmin.ws applications by restarting Tomcat.



Set up a service provider definition in your SSO provider

After you deploy Banner Administrative Pages you must create a service provider definition forBanner Administrative Pages in your SSO provider.

About this task

You can deploy Banner Administrative Pages to use CAS or SAML protocol for single sign-on (SSO)using Solution Manager version 1.13 or later, see Define the environment configuration on page23. If you are deploying Banner Administrative Pages using Solution Manager version 1.12, youmust deploy with CAS SSO configuration, but you can manually edit the configuration files afterdeployment to use SAML SSO. See Change single sign-on configuration from CAS to SAML onpage 51. Whether you use CAS or SAML protocol, you must create a service provider definitionfor Banner Administrative Pages in your SSO provider if you did not already do so or you defined itdifferently for your previous Administrative Pages 9.3.n deployment.

You can use Ellucian Ethos Identity to provide either CAS or SAML SSO services.

Procedure

1. In Ellucian Ethos Identity or another SSO provider, the service provider definition must includethe URL for Banner Administrative Pages, in the format protocol://admin-web-app-server-host-name:port/BannerAdmin.ws/

Component Description

protocol Use http if the application endpoint is notsecure. Use https if the endpoint is secure.

admin-web-app-server-host-name Use the host name for the web applicationserver that you installed and configured forAdministrative Pages. The host name mustmatch the host name of the machine that linksto the application server that you configurein Solution Manager for deployment of theapplication.

port Use the port number of the AdministrativePages application.

2. In the Attributes field of the service provider definition, enter or select UDC_IDENTIFIER .



Set up Application Navigator

Configure settings in the Banner database to set up Application Navigator access to your BannerAdministrative Pages deployment.

About this task

Application Navigator reads the GUBMODU table in your Banner database to get the URL tothe location of your Banner Administrative Pages deployment. The Banner 9 Module and PageMaintenance (GUAPAGE) page manages the information in the GUBMODU table after you haveBanner Administrative Pages fully functional (or if you still have Banner INB installed and runningyou can access GUAPAGE through INB), but you can use a script to set up this configurationinformation when you are first installing Banner Administrative Pages or you have changed the URLfor the Banner Administrative Pages application.

Configure these settings any time you install a new Administrative Pages 9.3.n.m.x upgrade anddeploy or re-deploy the application. This ensures that the module URL for all Administrative Pages(module code ADMJF) is correct. It also ensures that the menus rebuild to reflect any changes inthe GUBPAGE entries that might have occurred with the most recently installed 9.3.n.m.x upgrades.If there are no other changes required, force a menu rebuild as described in Step 5 on page 31.

In this procedure you will enter the URL for the web application server where youdeployed Banner Administrative Pages. The URL should be in the following format:<protocol>://<server>:<port>/BannerAdmin. For example, https://banneradmin.myinstitution.edu:7050/BannerAdmin.

URL component Description

<protocol> Use http if the application endpoint is not secure. Use https if theendpoint is secure.

<server> Use the name of the host for the web application server that youinstalled for Administrative Pages.

<port> Use the port number of the Banner pages web application server.

Procedure

Use the table below to determine the appropriate step at which to start your Application Navigatorsetup.

Condition Step

This is your initial installation of BannerAdministrative Pages

Go to step 1 on page 31

You deployed Banner Administrative Pages to anew URL and can no longer access GUAPAGE fromApplication Navigator, and you do not have BannerINB (Internet Native Banner) installed and running




Condition Step

Neither of the conditions above matches yourcurrent Banner Administrative Pages installation ordeployment.

Skip to step 3 on page 31

1. Log in to the Jobsub server for your Banner environment as the user you have specified as theBanner Install User (typically banner) in Ellucian Solution Manager.

2. Run the script stored in your Banner General product home directory to set the BannerAdministrative Pages URLs in the GUBMODU table.a) Enter sqlplus baninst1 and when prompted, provide the password for the baninst1

Oracle account.b) Execute the script <Banner-home>/general/plus/gubmodu_url.sql, where

<Banner-home> is the path to your environment Banner home directory.c) When the script displays the prompt Enter value for splpref:, you can either press

Enter to create the script log (spool) file in the directory from which you executed the sqlpluscommand or enter the full path, ending with "/", to create the log file in a different directory.Make sure you have permissions to create files and write to them in the directory that youspecify.

d) When the script displays the prompt Enter the Banner Admin URL:, enter theURL of the web application server where you deployed the Banner Administrative Pagesapplication.The script sets that URL as the URL for each of the Banner Administrative Pages modulesin the GUBMODU table, in addition to setting the integrated flag for each module. Thescript also runs the menu rebuild process required for Application Navigator to access theadministrative pages.

The script creates a log (spool) file named gubmodu_url.lst in the directory that youspecified. You can view the contents of that file to see the list of GUBMODU rows that the scriptmodified.Your Application Navigator setup is complete. Skip the remaining steps of this procedure.

3. Log in to Banner as the user, baseline, to make these changes.4. Go to GUAPAGE and change the URL for all modules with a platform type of ADMJF to the

URL of the web application server where you deployed the Banner Administrative Pagesapplication.

5. In the Integrated column, select the check box for all of the modules with a platform type ofADMJF.When you select the Integrated check box for any module on GUAPAGE, Application Navigatorwill display the Administrative Pages version of the pages instead of the INB version.If you select the check box in the Integrated column and save the GUAPAGE, the menus willbe rebuilt. To force a menu rebuild, unselect and then reselect the check box and save the pageagain.

Results

The setup of Application Navigator completes the full deployment of Banner Administrative Pages.You can access the application by logging in to Application Navigator.



Edit the Application Navigator configuration file

You can edit the Application Navigator configuration file to exclude system processing pages fromApplication Navigator search results.

About this task

Banner opens some forms and pages when needed for processing, but the user cannot see oraccess them directly. The baseline version of the applicationNavigator_configurationfile includes these files for exclusion from the Search, Menu, and Recently Opened. To preventadditional pages and forms from being displayed in the Search, Menu, and Recently Opened,perform the following action.

Procedure

Add these mnemonics to the delivered list included in the seamless.excludeObjectsFromSearchparameter in the applicationNavigator_configuration file.

seamless.excludeObjectsFromSearch =["GUAGMNU","GUAINIT","GUQSETI","FOQMENU","SOQMENU","TOQMENU","AOQMEMU","GOQMENU","ROQMENU","NOQMENU","POQMENU","FACICON","FAQINVP","FAQMINV","FAQVINV","FGQACTH","FGQAGYH","FGQDOCB","FGQDOCN","FGQDOCP","FGQFNDE","FGQFNDH","FGQLOCH","FGQORGH","FGQPRGH","FOQADDR","FOQDCSR","FOQENCB","FOQFACT","FOQINVA","FOQJVCD","FOQPACT","FOQRACT","FOQSDLF","FOQSDLV","FPCRCVP","FPQBLAP","FPQCHAP","FRCBSEL","FSCISSR","FSCSTKL","FTQATTS","FXQDOCN","FXQDOCP","**SSB_MASKING","TSQCONT","TSQEXPT","TOQCALC","GPBADMN","SFQESTS","SFQPREQ","SFQRQST","SFQRSTS","SFQSECM","SFQSECT","SHQDEGR","SHQSECT","SHQSUBJ","SHQTERM","SHQTRAM","SLQBCAT","SLQEVNT","SLQMEET","SLQROOM","SMQSACR","SMQSGCR","SMQSGDF","SMQSPDF","SOQCSCP","SOQCTRM","SOQHOLD","RPQLELG","RPQCOMP","ROQADDR"]

Next steps after your installation is complete

You have a few other options that you can set up after your installation.

• You can use external files that contain some of your configuration settings. By doing this, youcan make configuration changes by restarting the application instead of redeploying it. Forinstructions, see Use external configuration files on page 42.

• You can display ID image files. For instructions, see Display ID image files on page 46.• If you deployed Banner Administrative Pages using Ellucian Solution Manager (ESM) 1.12,

which only supports deployment with CAS SSO protocol, you can change single sign-on fromCAS to SAML. For instructions, see Change single sign-on configuration from CAS to SAML onpage 51.

• If you plan to use reports in any of the applications, see Jasper Server Installation andConfiguration for Banner Reports on page 79.

• You must implement Oracle Wallet Proxy for Job Submission to execute job submission from adeployment of Banner Administrative Pages. For additional information, see the Banner General



Release Guide 8.8 and Ellucian Support Center Article 000034656, Steps to implement theOracle Wallet Proxy for Banner Job Submission - BANJSPROXY.


Upgrade from a previous Administrative Pages 9.3.n.m release

Upgrade from a previous Administrative Pages9.3.n.m release

If you have a previously deployed Administrative Pages 9.3.n.m release, you can deploy thisrelease to the same web application server that you used for the previously deployed releases.

If you are deploying to a different web application server than you used for the previousAdministrative Pages 9.3.n.m release, you need to manually stop and undeploy the earlierAdministrative Pages 9.3.n.m release. Then, follow the instructions in First time installing anAdministrative Pages release on page 13.

Install the release using Ellucian Solution Manager

Install this release using Solution Manager. Solution Manager is a software system that allows forthe download, installation, configuration, and management of Ellucian products.

About this task

Selecting Get New Releases in Solution Manager, downloads all of your available, licensed Bannerrelease packages.

The release version number that shows in Solution Manager for all of the upgrades that are part ofthe Administrative Pages 9.3.n.m releases is in the format 9.3.n.m.x, where 9.3.n.m is the releasenumber (such as 9.3.0, 9.3.1, 9.3.1.1, etc.), and x is the package build number of the releasepackage for each product. The package build number for some products may be different fromothers. All references to the upgrade release package version number in this document is in theformat 9.3.n.m.x.

Warning! With the Banner 9.3.n.m releases, there is a new product, Banner Admin Common. Youmust install Banner Admin Common, because it contains the required common libraries and filesyou need to deploy the Administrative Pages applications.

After you install the Banner Admin Common 9.3.17.0.x. release and your selected 9.3.n.m.x productreleases, deploy the Administrative Pages application by running the Solution Manager deploymentjob associated with the Banner Admin Common 9.3.17.0.x release.

Procedure

1. In Solution Manager, go to the Products tab, and in the Name column, find the BannerAdministrative Pages 9.3.n.m.x release for each product and localization you want to install.Ellucian recommends that you select all of the Administrative Pages releases that you want toinstall at once, so that you have to run the upgrade job only one time.

2. For each product that you want to install, click the Latest Available Release column to accessthe Available Releases page.



Note: If you do not see a release on the Available Releases page, download new releases withSolution Manager to refresh the list.

3. Select the Target Release option for the 9.3.n.m.x version you want, and click OK to return tothe Products page.

4. Scroll down the Products page to view Selected Target Release for all products, and clickUpgrade.Solution Manager includes in the upgrade job any prerequisite releases that you have notpreviously installed.

5. Enter a description for the upgrade job in the Description field.6. Click Upgrade Properties for each upgrade in the upgrade job, and review the information.

a) Enter any required information the messages that display, and select the check box toacknowledge each message.

7. Click Start Upgrade to run the upgrade job.8. Monitor the upgrade job status.

The following message displays when the upgrade successfully completes:

BMUI upgrade task completed with status: 0Finished: SUCCESS

On the Upgrade tab, the Install Status displays the message Successfully Completed.

Results

The release package for each product updates the GUBMODU, GUBPAGE, GUROPTM, andGUBOBJS tables as required for the transformed Administrative Pages.

If you previously installed any Banner 9.x XE (ZK) Administrative applications, this release willchange the GUBPAGE entries for some of the pages in those applications to make them part of theAdministrative Pages application (modules SP, CAP, and TP). They will no longer be accessiblefrom Application Navigator as part of the previously installed administrative applications (theADMZK modules). The new Administrative Pages application replaces the previously released XE(ZK) administrative applications.

The Banner Admin Common 9.3.17.0.x release package delivers a file named release-Admin-9.3.17.0.x.zip (where x is the package build number for the current release) into theBanner-home/general/java directory. Other product release packages deliver a file namedrelease-Admin-product-9.3.n.m.x.zip, depending on the version you selected to install,into the corresponding Banner-home/product/java directory. These files contain the binaries,configuration file templates, and other files required to deploy the application.



Deploy to your web application server

The deployment process includes the Administrative Pages application for all Banner baselineproducts and any localization packages you have installed.

Procedure

1. In Solution Manager, go to the Deployments tab for your environment and select thedeployment job associated with the Banner Admin Common 9.3.17.0.x upgrade to display theDeployment page. That deployment job creates and deploys a single Administrative Pagesdeployment containing all the Administrative Pages upgrades that you have installed.

2. On the Deployment page, in the Application Servers table, select the web application server towhich you want to deploy the application.

3. Click Start Deployment.4. Optional: If the Monitor page does not display automatically, on the Deployments tab, click

Monitor to monitor the deployment job. When each step of the deployment is complete, you willsee the green check mark icon. As each step is complete, you can click the Console icon onthe Deployment Monitoring tab to see the console log file.When the entire deployment is successful, you will see a Deployment Status of Complete onthe Deployments tab.

Clear the Administrative Pages views cache

If you are deploying a new version of the Banner Administrative Pages application to the same webapplication server where you were running a previous version, you must clear the views cache.

The Banner Administrative Pages application caches HTML views on the server to improveperformance, so you must clear the cache when you deploy a new version to ensure that the pagesfor the new version display properly.

Clear the views cache on a WebLogic managed server

For Weblogic managed servers the views cache is stored in the temporary files location.

About this task

By default WebLogic temporary files are stored in the /tmp directory. You can control wherethey are stored by using the java.io.tmpdir property in the Server Startup parameters forthe managed server. See Create a new WebLogic managed server on page 14 for additionalinformation.

Perform the following steps to clear the views cache for Banner Administrative Pages deployed to aWeblogic managed server.



Procedure

1. Using the Weblogic console, stop the BannerAdmin deployment on the managed server thatyou deployed Banner Administrative Pages to.

2. If you specified the temporary files location using the java.io.tmpdir property, delete all thefiles in that directory. If the temporary files are being written to the default location /tmp,delete the files morphis%002ecache%002eviewscache.data and morphis%002ecache%002eviewscache.index.

3. Using the Weblogic console, restart the BannerAdmin deployment.

Clear the views cache on a Tomcat web application server

For Tomcat web application servers, the views cache is stored in the temporary files location.

About this task

By default, Tomcat stores temporary files in the $CATALINA_HOME/temp directory. You canoverride this location by specifying -Djava.io.tmpdir when starting Tomcat. Perform thefollowing steps to clear the views cache for Banner Administrative Pages deployed to a Tomcat webapplication server.

Procedure

1. Shut down the Tomcat instance that hosts the Banner Administrative Pages application.2. Delete the files morphis%002ecache%002eviewscache.data and morphis%002ecache

%002eviewscache.index from the $CATALINA_HOME/temp directory, or from thetemporary files directory specified by -Djava.io.tmpdir in your Tomcat configuration.

3. Restart the BannerAdmin and BannerAdmin.ws applications by restarting Tomcat.

Set up a service provider definition in your SSO provider

After you deploy Banner Administrative Pages you must create a service provider definition forBanner Administrative Pages in your SSO provider.

About this task

You can deploy Banner Administrative Pages to use CAS or SAML protocol for single sign-on (SSO)using Solution Manager version 1.13 or later, see Define the environment configuration on page23. If you are deploying Banner Administrative Pages using Solution Manager version 1.12, youmust deploy with CAS SSO configuration, but you can manually edit the configuration files afterdeployment to use SAML SSO. See Change single sign-on configuration from CAS to SAML onpage 51. Whether you use CAS or SAML protocol, you must create a service provider definitionfor Banner Administrative Pages in your SSO provider if you did not already do so or you defined itdifferently for your previous Administrative Pages 9.3.n deployment.

You can use Ellucian Ethos Identity to provide either CAS or SAML SSO services.



Procedure

1. In Ellucian Ethos Identity or another SSO provider, the service provider definition must includethe URL for Banner Administrative Pages, in the format protocol://admin-web-app-server-host-name:port/BannerAdmin.ws/

Component Description

protocol Use http if the application endpoint is notsecure. Use https if the endpoint is secure.

admin-web-app-server-host-name Use the host name for the web applicationserver that you installed and configured forAdministrative Pages. The host name mustmatch the host name of the machine that linksto the application server that you configurein Solution Manager for deployment of theapplication.

port Use the port number of the AdministrativePages application.

2. In the Attributes field of the service provider definition, enter or select UDC_IDENTIFIER .

Set up Application Navigator

Configure settings in the Banner database to set up Application Navigator access to your BannerAdministrative Pages deployment.

About this task

Application Navigator reads the GUBMODU table in your Banner database to get the URL tothe location of your Banner Administrative Pages deployment. The Banner 9 Module and PageMaintenance (GUAPAGE) page manages the information in the GUBMODU table after you haveBanner Administrative Pages fully functional (or if you still have Banner INB installed and runningyou can access GUAPAGE through INB), but you can use a script to set up this configurationinformation when you are first installing Banner Administrative Pages or you have changed the URLfor the Banner Administrative Pages application.

Configure these settings any time you install a new Administrative Pages 9.3.n.m.x upgrade anddeploy or re-deploy the application. This ensures that the module URL for all Administrative Pages(module code ADMJF) is correct. It also ensures that the menus rebuild to reflect any changes inthe GUBPAGE entries that might have occurred with the most recently installed 9.3.n.m.x upgrades.If there are no other changes required, force a menu rebuild as described in Step 5 on page 31.

In this procedure you will enter the URL for the web application server where youdeployed Banner Administrative Pages. The URL should be in the following format:<protocol>://<server>:<port>/BannerAdmin. For example, https://banneradmin.myinstitution.edu:7050/BannerAdmin.



URL component Description

<protocol> Use http if the application endpoint is not secure. Use https if theendpoint is secure.

<server> Use the name of the host for the web application server that youinstalled for Administrative Pages.

<port> Use the port number of the Banner pages web application server.

Procedure

Use the table below to determine the appropriate step at which to start your Application Navigatorsetup.

Condition Step

This is your initial installation of BannerAdministrative Pages


You deployed Banner Administrative Pages to anew URL and can no longer access GUAPAGE fromApplication Navigator, and you do not have BannerINB (Internet Native Banner) installed and running


Neither of the conditions above matches yourcurrent Banner Administrative Pages installation ordeployment.

Skip to step 3 on page 31

1. Log in to the Jobsub server for your Banner environment as the user you have specified as theBanner Install User (typically banner) in Ellucian Solution Manager.

2. Run the script stored in your Banner General product home directory to set the BannerAdministrative Pages URLs in the GUBMODU table.a) Enter sqlplus baninst1 and when prompted, provide the password for the baninst1

Oracle account.b) Execute the script <Banner-home>/general/plus/gubmodu_url.sql, where

<Banner-home> is the path to your environment Banner home directory.c) When the script displays the prompt Enter value for splpref:, you can either press

Enter to create the script log (spool) file in the directory from which you executed the sqlpluscommand or enter the full path, ending with "/", to create the log file in a different directory.Make sure you have permissions to create files and write to them in the directory that youspecify.

d) When the script displays the prompt Enter the Banner Admin URL:, enter theURL of the web application server where you deployed the Banner Administrative Pagesapplication.The script sets that URL as the URL for each of the Banner Administrative Pages modulesin the GUBMODU table, in addition to setting the integrated flag for each module. Thescript also runs the menu rebuild process required for Application Navigator to access theadministrative pages.



The script creates a log (spool) file named gubmodu_url.lst in the directory that youspecified. You can view the contents of that file to see the list of GUBMODU rows that the scriptmodified.Your Application Navigator setup is complete. Skip the remaining steps of this procedure.

3. Log in to Banner as the user, baseline, to make these changes.4. Go to GUAPAGE and change the URL for all modules with a platform type of ADMJF to the

URL of the web application server where you deployed the Banner Administrative Pagesapplication.

5. In the Integrated column, select the check box for all of the modules with a platform type ofADMJF.When you select the Integrated check box for any module on GUAPAGE, Application Navigatorwill display the Administrative Pages version of the pages instead of the INB version.If you select the check box in the Integrated column and save the GUAPAGE, the menus willbe rebuilt. To force a menu rebuild, unselect and then reselect the check box and save the pageagain.

Results

The setup of Application Navigator completes the full deployment of Banner Administrative Pages.You can access the application by logging in to Application Navigator.

Edit the Application Navigator configuration file

You can edit the Application Navigator configuration file to exclude system processing pages fromApplication Navigator search results.

About this task

Banner opens some forms and pages when needed for processing, but the user cannot see oraccess them directly. The baseline version of the applicationNavigator_configurationfile includes these files for exclusion from the Search, Menu, and Recently Opened. To preventadditional pages and forms from being displayed in the Search, Menu, and Recently Opened,perform the following action.

Procedure

Add these mnemonics to the delivered list included in the seamless.excludeObjectsFromSearchparameter in the applicationNavigator_configuration file.

seamless.excludeObjectsFromSearch =["GUAGMNU","GUAINIT","GUQSETI","FOQMENU","SOQMENU","TOQMENU","AOQMEMU","GOQMENU","ROQMENU","NOQMENU","POQMENU","FACICON","FAQINVP","FAQMINV","FAQVINV","FGQACTH","FGQAGYH","FGQDOCB","FGQDOCN","FGQDOCP","FGQFNDE","FGQFNDH","FGQLOCH","FGQORGH","FGQPRGH","FOQADDR","FOQDCSR","FOQENCB","FOQFACT","FOQINVA","FOQJVCD","FOQPACT","FOQRACT","FOQSDLF","FOQSDLV","FPCRCVP","FPQBLAP","FPQCHAP","FRCBSEL","FSCISSR","FSCSTKL","FTQATTS","FXQDOCN","FXQDOCP","**SSB_MASKING","TSQCONT","TSQEXPT","TOQCALC","GPBADMN","SFQESTS","SFQPREQ","SFQRQST","SFQRSTS","SFQSECM","SFQSECT","SHQDEGR","SHQSECT","SHQSUBJ","SHQTERM","SHQTRAM","SLQBCAT","SLQEVNT","SLQMEET","SLQROOM","SMQSACR","



SMQSGCR","SMQSGDF","SMQSPDF","SOQCSCP","SOQCTRM","SOQHOLD","RPQLELG","RPQCOMP","ROQADDR"]

Next steps after your installation is complete

You have a few other options that you can set up after your installation.

• You can use external files that contain some of your configuration settings. By doing this, youcan make configuration changes by restarting the application instead of redeploying it. Forinstructions, see Use external configuration files on page 42.

• You can display ID image files. For instructions, see Display ID image files on page 46.• If you deployed Banner Administrative Pages using Ellucian Solution Manager (ESM) 1.12,

which only supports deployment with CAS SSO protocol, you can change single sign-on fromCAS to SAML. For instructions, see Change single sign-on configuration from CAS to SAML onpage 51.

• If you plan to use reports in any of the applications, see Jasper Server Installation andConfiguration for Banner Reports on page 79.

• You must implement Oracle Wallet Proxy for Job Submission to execute job submission from adeployment of Banner Administrative Pages. For additional information, see the Banner GeneralRelease Guide 8.8 and Ellucian Support Center Article 000034656, Steps to implement theOracle Wallet Proxy for Banner Job Submission - BANJSPROXY.


Use external configuration files

Use external configuration filesWhen you store configuration settings in files outside of the WAR/ EAR files, you can make changesby restarting the application instead of redeploying it.

If you want to use external configuration files, you should have entered the absolute path forstorage of the configuration files in the Banner Pages App Data Path field during the Add the webapplication server to Solution Manager on page 20 step. After that is complete, there are someadditional setup steps you need to perform to enable the functionality.

Enable external configuration files and the Export Datafeature for WebLogic

For WebLogic users only. If you want to use external configuration files and the Export Data feature,you need to enable the support for publishing simple string properties through JNDI.

Procedure

1. Download the weblogic-jndi-startup-1.3.zip file from the following location:https://code.google.com/p/weblogic-jndi-startup/downloads/list

2. Unzip the file and put the weblogic-jndi-startup-1.3.jar file in the domain/server/lib directory on your application server.

3. Create a new WebLogic startup class to define the required JNDI object.a) In the Change Center frame, click Lock& Edit.b) In the Domain Structure frame, expand the list of environments, click Start up and

Shutdown Classes, and click New.c) Select the Startup Class check box, and click Next.d) Enter a name for the startup class or accept the default.e) Enter the following in the Class Name field:

nz.co.senanque.jndi.WebLogicJndiStartup, and click Next.f) Select the managed server that you previously created for Administrative Pages to be the

target for this startup class, and click Finish.g) Click the startup class that you just created in step 3 on page 42, and select the Failure

is Fatal and Run Before Application Activations check boxes.h) In the Arguments field, enter the definition of the JNDI object app in the format

app<java.lang.String>=ext-config-files-directory

where ext-config-files-directory is the directory for the external configuration files, and clickSave.

The path specified must be a path for which WebLogic has write privileges. It must be thesame path that you enter into the Banner Pages App Data Path field on the App Server



that you define in Solution Manager for the web application server that you will deploy theadministrative pages application to.For example, app<java.lang.String>=/home/oracle/BannerAdmin.

i) In the Domain Structure frame, click Servers, and select the server to which you justassigned the startup class.

j) Click the Server Start tab, enter -Djava.awt.headless=true to the Arguments textarea, and click Save.

k) In the Change Center frame, click Activate Changes.If the server was previously running, you must stop and restart it for the changes to takeeffect.

Configuration properties file values

You can edit these properties in the config.properties file.

Warning! Do not edit properties other than the ones mentioned below unless Ellucian providesyou additional information beyond the information in this section regarding the need or abilityto change the behavior of the Banner Administrative Pages software by changing the values ofother properties. The deployment process sets the property values to be consistent with otherconfiguration properties in the external configuration files directory and to provide the behavior ofthe Banner Administrative Pages software intended and supported by Ellucian.

The config.properties file is stored in the config sub-directory of the external configurationfiles path that you specified in the Banner Pages App Data Path field on the App Server that youdefined in Solution Manager for the web application server that you will deploy the administrativepages application to. After you have made changes to the config.properties file, you mustrestart the BannerAdmin application in Weblogic or Tomcat to get the application to recognize thecustomized configuration.

Ellucian recommends making a backup copy of the modified configuration file after you makeany configuration file changes. This is because the next time you run a Banner Admin Commondeployment in Solution Manager to update the deployed Banner Administrative Pages application,with or without the Build War option selected, the external configuration files will be overwritten withthe default configurations based on the configuration information you entered into Solution Manager.You will then need to re-apply your customizations and restart the BannerAdmin application to pickup the customized configuration.

Warning! When you re-apply your customizations to the external configuration files following anew Banner Admin Common deployment, compare your backup copies of the configuration filesto the configuration files from the new deployment and only apply your customizations to the newlydeployed configuration files rather than copying your backups over the newly deployed configurationfiles. This process ensures that you do not overwrite any changes to the configuration files in thenewly deployed version of Admin Common required for correct operation of the newly deployedversion.

Property Description

webapp.location URL for the deployed Administrative Pages application.




cas.server.location Root URL of the server providing CAS protocol userauthentication.

env.guaimge.id_range;env_image_extension;env_image_path

Configuration for accessing ID image files. See Configureaccess to ID image files on page 49 for further details.

localizationProvider;locale.properties.db.refresh.interval

Configuration properties to control whether or notthe Banner Administrative Pages application usesmessage translations from the database. See Customizedtranslation of labels and messages on page 61 forfurther details.

env.image.url, env.image.parameters See step 4 on page 89 in Update config.properties filefor the BannerAdmin.ws.war file for third-party documentimaging integration on page 89 for configurationinformation.

env.nls.sort Default value is BINARY, which is the Oracle default. Youcan change the value to any legal value for the Oracleglobalization parameter NLS_SORT, as described in theOracle Database Globalization Support Guide. The valueyou specify should match the value used in your Oracledatabase.

The following configuration parameters control some of the behavior of the export data function inBanner Administrative Pages. For more information about the export data function, see the "Dataexport" section in Banner Transformed: Getting Started With Your Administrative Applications,available in the Banner 9 section of the Documentation Library in the Ellucian Customer Center.


env.defaultNumRecordsWarningExport Specifies the minimum number of records selected bya user for export to trigger a warning message "Theexport functionality may take some time, do you want tocontinue?".

Default value delivered with Banner Admin Common:5000.

env.timerToRefreshCounterExport Specifies how often (number of seconds) the exportedrecords counter display refreshes. The counter displayrefreshes whenever the specified number of secondspasses from the last time the counter refreshed, or thenumber of records exported from the time of the lastrefresh is greater than or equal to the value specified forenv.refreshCounterRecordsExport, whichever occurs first.

Default value delivered with Banner Admin Common: 30.




env.refreshCounterRecordsExport Specifies how often (number of records) the exportedrecords counter display refreshes. The counterdisplay refreshes whenever the specified number ofrecords have exported from the last time the counterrefreshed, or the number of seconds specified forenv.timerToRefreshCounterExport has passed, whicheveroccurs first.

Default value delivered with Banner Admin Common: 2500

env.showWarningExport Controls whether or not the warning messagedisplays if the number of records selected to exportis greater than or equal to the value specified forenv.defaultNumRecordsWarningExport. Change the valueto "N" to not display the warning message.

Default value delivered with Banner Admin Common: "Y".


Display ID image files

Display ID image filesYou can display ID image files when the user is on an ID field and selects Tools > DisplayIDImage.

You must complete the following items to display ID image files:

• Prepare your ID image files as described in Prepare ID image files on page 46.• Set up a web server to provide access to the ID image files.

– Define HTTP access to image files with WebLogic on page 47– Define HTTP access to image files with Tomcat on page 48

• Configure access to the ID image files for the Banner Administrative Pages as described inConfigure access to ID image files on page 49

Prepare ID image files

Prepare ID image files following the naming convention described below and store them in adirectory from which Banner Administrative Pages can access them through a WebLogic or TomcatHTTP server.

About this task

Use image files in BMP, GIF, or JPG formats. All ID image files must use the same format. Name thefiles according to one of the following naming conventions.

Naming convention File name

3,7 File name begins with the letter "I" followed by the 7 digits ofthe person's Banner ID starting at position 3.

For example, using the JPG format, a person with BannerID "A01394287" would have an ID image file name ofI1394287.jpg.

1,9 Use the first 9 digits of the person's Banner ID.

For example, using the GIF format, a person with BannerID "A01394287" would have an ID image file name ofA01394287.gif.

Procedure

1. Name the ID image files according to one of the naming conventions described above.2. Store the ID image files.



Store the files in a directory that you can access from a WebLogic or Tomcat web server thatyou set up to provide access to the files. Make sure to secure the directory to prevent access byunauthorized users.

Define HTTP access to image files with WebLogic

Set up a web server to provide HTTP access to the ID image files in the Oracle WebLogicEnterprise Manager application.

Procedure

1. Log in to the Oracle WebLogic Enterprise Manager application on the machine that has readaccess to the ID image files.

2. Select the appropriate HTTP server.This is typically ohs1, an Oracle HTTP server.

3. Select Administration > Advanced Configuration4. Find the section of the httpd.conf file that defines aliases, and between the <IfModule

alias_module> element tag and its closing </IfModule> tag, add an alias for accessing theID image files.For example, if your ID image files are stored in /home/oracle/id_images and you wantAdministrative Pages to access the image files using a URL of http://server:port/id_images, add the following alias definition : Alias /id_images/ “/home/oracle/id_images/”

5. Add a directory element after the alias definition to allow access to the directory that containsthe ID image files, and restrict that access to requests from users who are allowed to connect toAdministrative Pages.For example, if all users are on devices with IP addresses in the 10.67.5.xxx range, you wouldenter the following directory definition element:

<Directory "/home/oracle/id_images/">AllowOverride NoneOptions None Order deny,allowDeny from all Allow from 10.67.5</Directory>

6. Click Apply to save your changes.7. Restart the Oracle HTTP server for the changes to take effect.



Define HTTP access to image files with Tomcat

Set up a Tomcat server to provide HTTP access to the ID image files with access restricted to theBanner Administrative Pages application server.

Before you begin

The system account you use to run the Tomcat ID image server must have read access to thedirectory where you store the ID image files.

Procedure

1. Install or use an existing Tomcat instance to provide HTTP access to the image files.You can configure Tomcat for HTTP or HTTPS. If you configure for HTTPS and use a self-signed certificate, you need to install the certificate in the cacerts file for the Java VM used torun the Banner Administrative Pages application.

2. Modify the Tomcat-home/conf/context.xml file to configure the Tomcat instance toprovide access to the ID image files. Do this by adding a resource definition to define thedirectory that contains the ID image files, and the resource path to use in the URL.This table describes the path values that you must specify when you add the resource definitionshown in the example following this table.

Path name Path description Path examples

path-to-ID-images-directory

Directory that contains theID image files from theperspective of the Tomcatserver.

• Linux or Unix server: /var/banner/id_images

• Windows server: D:/banner/id_images

http-resource-path Used to access the ID imagefiles in the Tomcat URL.

If path is /banneridimages/ andthe Tomcat instance is running onHTTPS port 8180 on mytcserver.edu,then the URL to access the IDimage files would be https://mytcserver.edu:8180/banneridimages/.

<Resources allowLinking="false"> <PostResources readOnly="false" className="org.apache.catalina.webresources.DirResourceSet" base="path-to-ID-images-directory" webAppMount="http-resource-path"/></Resources>

3. Optional: Restrict access to the ID images hosted by the Tomcat webserver to only the BannerAdministrative Pages server by adding an entry to the context.xml file that restricts access toa particular IP address or list of IP addresses, as shown in the example below.



In the example, access to the ID images URL would be restricted to IP addresses 10.67.2.98and 149.24.34.207.

<Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="10\.67\.2\.98|149\.24\.34\.207" />

Configure access to ID image files

To complete the setup, you need to configure access to the ID image files.

About this task

You can provide the configuration information for Banner Administrative Pages to access the IDimage files by entering the appropriate information into the ID Image Files URL, ID Image FilesName Format, and ID Image Files Extension fields on the Env Settings tab for the environment inSolution Manager. When you run the deployment for Banner Admin Common in Solution Manager,it automatically configures the deployment to access your ID image files.

If you want to change the parameters for ID image access after you have deployed Banner AdminCommon and you do not want to run the deployment job for Admin Common in Solution Manageragain, you must deploy Banner Admin Common using the external configuration files option, andyou can change the ID image files access parameters directly in the external configuration file andthen restart the Banner Administrative Pages application to recognize the new ID image files accessparameters. See Use external configuration files on page 42.

Procedure

1. Go to the directory that contains the external configuration files.2. Edit the config.properties file.3. Restart the application for the changes to take affect.

Configuration settings to access image files

Use these config.properties settings to display the ID image files.


env.guaimge.id_range Set the value to match the naming convention you used for your IDimage files.

Valid values:

• 1, 9• 3, 7




env.guaimge.extension Set the value for this property to match the format extension youchose for naming your ID image files.

Valid values:

• JPG• GIF• BMP

env.guaimge.path Set the value for this property to the URL needed to access the HTTPserver that you configured to provide access to the ID image filesdirectory.

If the host name of the server on which the files are stored isbanimg.myinstitution.edu, the value might be

http://banimg.myinstitution.edu:8888/id_images/


Change single sign-on configuration from CAS to SAML

Change single sign-on configuration from CASto SAML

After deployment of Banner Administrative Pages with the CAS SSO protocol with Ellucian SolutionManager (ESM) 1.12, you can change the configuration to use the SAML SSO protocol for userauthentication with Ellucian Ethos Identity as the authentication server.

If you deploy Banner Admin Common using ESM 1.13 or a later version, you can enter configurationinformation for deployment with CAS or SAML SSO protocol. See Define the environmentconfiguration on page 23 for additional information.

If you deploy Banner Admin Common with ESM 1.12, you set up single sign-on capability usinga CAS authentication server. When you deployed the release using ESM, ESM configured theapplication to use the CAS protocol for user authentication. If you use Ellucian Ethos Identity (EEID)as your authentication server, you can change the user authentication protocol from CAS to SAMLfollowing the instructions in this section.

Note: If you are using an authentication server other than Ellucian Ethos Identity, you must adaptthese instructions accordingly.

Modify the configuration files

To change the protocol that is used by the authentication server, you must manually edit severalconfiguration files.

About this task

Some of these are not external configuration files, so you will need to rebuild the application WARfiles (and EAR file if you deployed to WebLogic) with the updated configuration files and thenredeploy the application.

Procedure

1. Log on to the Jobsub server as the install user.The install user is specified in Solution Manager on the Credentials page for the environment. Itis typically banner.

2. Make backup copies of the following directories.staging-dir/javaforms-93/BannerAdmin/config/BannerAdmin staging-dir/javaforms-93/BannerAdmin/config/BannerAdmin.ws

In the example, staging-dir is the directory specified in the Banner 9 War File Staging Path fieldon the configuration page for the Jobsub application in Solution Manager.


Edit the config.xml file

Edit the config.xml file to set the session URL for the SAML login.

Procedure

Edit the config.xml file in the staging-dir/javaforms-93/BannerAdmin/config/BannerAdmin directory to remove the comment tags surrounding the element andchange wrksp.ws to BannerAdmin.ws.For example: Change



to

<param name="SESSION_URL" value="/BannerAdmin.ws/saml/login" />

Edit the applicationContext.xml file

Set the applicationContext.xml file for SAML user authentication.

Procedure

1. In the backup copy that you made of the staging-dir/javaforms-93/BannerAdmin/config/BannerAdmin.ws directory, open the WEB-INF/applicationContext.xml fileand note the text that is between the <value> start and </value> end tags in the <bean>definition shown in this example.

<beanclass="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"><propertyname="locations"><array><value>file://config_files_path/config.properties</value></array></property> </bean>

2. Delete the applicationContext.xml file from the staging-dir/javaforms-93/BannerAdmin/config/BannerAdmin.ws/WEB-INF directory.

3. In the staging-dir/javaforms-93/BannerAdmin/config/BannerAdmin.ws/WEB-INFdirectory, rename the applicationContext_saml.xml file to applicationContext.xml.

4. In the application Context.xml file, replace the root portion of the default target URL(http://localhost:8081/wrksp.ws) with the URL that you have specified for yourinstallation. For example: http://app1.myinstitution.edu:7120/BannerAdmin.ws.For example, change

<bean id="successRedirectHandler" class="org.springframework.security.web.authentication.

SavedRequestAwareAuthenticationSuccessHandler"><propertyname="defaultTargetUrl" value="http://localhost:8081/wrksp.ws/services/message.wsdl"/></bean>

to

<beanid="successRedirectHandler" class="org.springframework.security.web.authentication. SavedRequestAwareAuthenticationSuccessHandler"><propertyname="defaultTargetUrl" value="http:// app1.myinstitution.edu:7120/BannerAdmin.ws/services/message.wsdl"/></bean>

Note: The protocol (http or https), host name, and port number should match the URL specifiedin the webapp.location property in the config.properties file in the staging-dir/javaforms-93/BannerAdmin/config/BannerAdmin.ws/WEB-INF/classes directory.

5. Find the following section of code and replace the text that is between the <value>start and </value> end tags with the text that you noted from the backup copy of theapplicationContext.xml file in step 1 on page 52.

<beanclass="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"><propertyname="locations"><array><value>##BAN_PAGES_APP_DATA_PATH##/config.properties</value></array></property></bean>

Edit the appsupportlib.config.xml file

Change the user authentication setting from CAS to SAML.

Procedure

1. In the appsupportlib.config.xml file in the <staging-dir>/javaforms-93/BannerAdmin/config/BannerAdmin.ws/WEB-INF/classes directory,remove the comment tags surrounding the SamlLoginProvider <bean> element.For example, remove the comment tags around the following:

2. Add comment tags around the CasLoginProvider<bean> element.For example:



Provide a digital certificate

Provide a digital certificate for Banner Administrative Pages to use for encrypting SAML assertions.

About this task

You must provide a Java keystore file that contains the certificate stored on the machine wherethe application is running. The user running the web application server that is hosting BannerAdministrative Pages (typically “oracle” if you are using WebLogic as your application server) musthave read access to the keystore file.

Procedure

1. In the config.properties file in the <staging-dir>/javaforms-93/BannerAdmin/config/BannerAdmin.ws/WEB-INF/classes directory, set the value of the saml.keystoreproperty to the path for the SAML keystore file and the value of the saml.keystore.passwordproperty to the password that you specified for the SAML keystore file.For example:

#SAML2saml.keystore =file:///home/oracle/saml-keystore.jks saml.keystore.password = changeit

2. Extract the x509 certificate from the keystore file using the following Java keytool command.

keytool -export -alias samlcert -file samlcert.crt-keystore saml-keystore.jks

In the example, samlcert is the name of the certificate, samlcert.crt is the name of thefile that will be created containing the certificate information, and saml-keystore.jks is thename of the keystore file containing the certificate.

3. Convert the x509 certificate information to base 64 using the base64 command.

base64 samlcert.crt

In the example samlcert.crt is the name of the file containing the certificate. The outputof the command will be a long string of characters which is the base 64 representation of thecertificate.

4. In the banner-sp-metadata.xml file in the <staging-dir>/javaforms-93/BannerAdmin/config/BannerAdmin.ws/WEB-INF/classes directory,insert the base 64 representation of your SAML certificate into the file, replacing the sampledata between the <ds:X509Certificate> and </ds:X509Certificate> tags in both ofthe following elements.

<md:KeyDescriptor use="signing"><md:KeyDescriptor use="encryption">

5. Find the <md:AssertionConsumerService> element for the HTTP-POST binding, andinsert in front of that element another<md:AssertionConsumerService> element for theHTTP-Redirect binding.

6. In both elements, change the default URL (http://localhost:8081/wrksp.ws) to theactual URL of Banner Admin Pages.

<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"Location="http://app1.myinstitution.edu:7120/BannerAdmin.ws/saml/SSO" index="0" isDefault="true" /><md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"Location="http://app1.myinstitution.edu:7120/BannerAdmin.ws/saml/SSO" index="0" isDefault="true" />

Extract the Ellucian Ethos Identity certificate

Extract the EEId security certificate so it can be made available to the Banner pages application.

Procedure

1. Log on to the machine where Ellucian Ethos Identity is running.2. Look in the <KeyStore> node of the carbon.xml configuration file to find the location of the

keystore file, the name of the certificate, and the keystore password.You will find the carbon.xml configuration file in the eis-home/repository/confdirectory, where eis-home is the directory in which you installed Ellucian Ethos Identity.

• The path to the keystore file is specified by the <Location> element.• The name of the certificate is specified by the <KeyAlias> element.• The keystore password is specified by the <Password> element.

For example:

<KeyStore>  <Location>${carbon.home}/repository/resources/security/cacerts</Location>  <Type>JKS</Type>  <Password>changeit</Password>

<KeyAlias>mykey</KeyAlias>  <KeyPassword>changeit</KeyPassword></KeyStore>

3. Go to the directory that contains the keystore file.For example: ${carbon.home}/repository/resources/security)

4. Extract the certificate from the keystore file by using the following Java keytool command.

keytool -export -keystore wso2keystore.jks -rfc -alias mykey -file wso2idp.crt

Where wso2keystore.jks is the keystore file name and mykey is the key alias.5. Copy the wso2idp.crt file that was created by the keytool command to the machine where

Banner Administrative Pages is deployed.6. Install the certificate into the keystore file that you previously specified as the SAML keystore.

a) Log on to the machine where the Administrative Pages application server is running, andchange to the directory that contains the SAML keystore file that you specified to be usedfor Banner Administrative Pages.

b) Use the following Java keytool command.

keytool -import -trustcacerts -alias eeidcert -file wso2idp.crt -keystore saml -keystore.jks

In this example, eeidcert is the alias you provide for the certificate, and saml-keystore.jks isthe name of the SAML keystore file specified to be used for Banner Administrative Pages.

7. Convert the Ellucian Ethos Identity certificate to base 64 using the base64 command as shownbelow.

base64 wso2idp.crt

Add the Ellucian Ethos Identity certificate to the Banner pagesconfiguration file

Edit the Banner pages configuration file wso2-idp.xml in the staging-dir/javaforms-93/BannerAdmin/config/BannerAdmin.ws/WEB-INF/classes directory tocontain the Ellucian Ethos Identity security certificate and other required information for SAML userauthentication.

Procedure

1. Log onto the Jobsub server as the install user. The install user is specified in Solution Manageron the Credentials page for the environment. It is typically banner.

2. Insert the base 64 representation of the Ellucian Ethos Identity certificate into the file, replacingthe sample data between the <ds:X509Certificate> and </ds:X509Certificate> tagsin the <KeyDescriptor> node.

3. Edit the SingleSignOnService and SingleLogoutService elements to update the URL in theLocation attribute by replacing the existing text (https://localhost:9443) with the actualFQDN of your Ellucian Ethos Identity Provider.The example below is for an Ellucian Ethos Identity application accessed through the URLhttps://auth.myinstitution.edu:8443.

<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://auth.myinstitution.edu:8443/samlsso" /><SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://auth.myinstitution.edu:8443/samlsso" />

Update the WAR files and EAR file

After modifying the Ellucian Ethos Identity configuration files, you must update theBannerAdmin.war and the BannerAdmin.ws.war files with the configuration changes.

About this task

If you have deployed Banner Admin Pages to a WebLogic web application server you also need toupdate the BannerAdmin.ear file with the updated WAR files.

Procedure

1. Log onto the Jobsub server as the install user. The install user is specified in Solution Manageron the Credentials page for the environment. It is typically banner.

2. Change your working directory to staging-dir/javaforms-93/BannerAdmin/config/BannerAdmin.

3. Run the following command to update the BannerAdmin.war file:

jar uvf ../../dist/BannerAdmin.war config.xml

4. Change your working directory to staging-dir/javaforms-93/BannerAdmin/config/BannerAdmin.ws.

5. Run the following commands to update the BannerAdmin.ws.war file:

jar uvf ../../dist/BannerAdmin.ws.war WEB-INF/applicationContext.xmljar uvf ../../dist/BannerAdmin.ws.war WEB-INF/classes/config.propertiesjar uvf ../../dist/BannerAdmin.ws.war WEB-INF/classes/appsupportlib.config.xml jar uvf ../../dist/BannerAdmin.ws.war WEB-INF/classes/wso2-idp.xmljar uvf ../../dist/BannerAdmin.ws.war WEB-INF/classes/banner-sp-metadata.xml

6. If you have deployed Banner Administrative Pages to WebLogic, complete the following steps.a) Change your working directory to staging-dir/javaforms-93/BannerAdmin/dist.


b) Run the following commands to update the BannerAdmin.ear file with the updated WARfiles:

jar uvf BannerAdmin.ear BannerAdmin.war jar uvf BannerAdmin.ear BannerAdmin.ws.war

7. Make a backup of the staging-dir/javaforms-93/BannerAdmin directory to preserveyour configuration changes.By making a backup copy of your changes, you will be able to restore them, if necessary, aftera subsequent Solution Manager redeployment of the application with the BuildWar optionselected.

Set up the Ellucian Ethos Identity service provider

You must set up a service provider, specifying that it will authenticate using the SAML protocol.

Before you begin

There will already be a service provider set up for authentication using the CAS protocol. Reviewthe configuration information for that service provider, because you will need some of the sameinformation when you set up the SAML service provider. For additional information, see “ManagingService Providers” in the Setting Up Ellucian Ethos Identity Service manual.

Procedure

1. Log onto the Ellucian Ethos Identity admin console using the administrator credentials.2. Select Add under Identity > Service Providers.3. Complete the Service Provider Name and Description fields.

The name must be unique among all of the service providers.4. Click Register to add the new provider.5. Open Claim Configuration and click Define Custom Claim Dialect option, then click Add

Claim URI.6. In the Service Provider Claim field, enter UDC_IDENTIFER.7. In the Local Claim field, select the same local claim that was used in the service provider for

the CAS protocol.8. Select the Requested Claim check box.9. Open Inbound Authentication Configuration > SAML2 Web SSO Configuration, and click

Configure.10. In the Issuer field, enter banner.11. In the Assertion Consumer URL field, enter banner-pages-app-URL/saml/SSO, where

banner-pages-app-URL is the same URL that you entered for the CAS protocol service providerunder Inbound Authentication Configuration > CAS Configuration> in the Service URLfield.

12. Select the Enable Attribute Profile and the Include Attributes in the Response Alwaysoptions.



13. Click Update to save the service provider definition.

Redeploy the WAR or EAR files

After updating the WAR and EAR files and setting up the SAML service provider in Ellucian EthosIdentity, you are ready to redeploy.

You can redeploy by re-running the Solution Manager deployment job for Banner Admin Commonand skipping the build phase (clearing the Build War option), or you can manually redeploy. Skippingthe build phase protects any changes you have made to the configuration files in the stagingdirectory.

Redeploy the WAR or EAR files prerequisites

Perform these steps before manually redeploying.

Procedure

1. Log onto the machine that is hosting the Banner Administrative Pages application server(WebLogic or Tomcat) as the user that is running the web application server.The user is typically oracle for WebLogic.

2. Make a backup copy of the config subdirectory of the external configuration files directory.The external configuration files directory is the directory that you entered in the BannerPages App Data Path field of the App Server definition in Solution Manager for the BannerAdministrative Pages web application server.

3. Copy the modified configuration files from the application staging directory to the configsubdirectory of the external app server configuration files directory.

The application staging directory is the directory that you entered in the Banner 9 War FileStaging Path field on the App Server Configuration page in Solution Manager.

For example, the following command would copy the new configuration files to the externalconfiguration files directory, where staging-dir is the staging directory and ext-con fig-dir is theexternal configuration files directory.

cp –p staging-dir/javaforms-93/BannerAdmin/config/BannerAdmin.ws/ WEB-INF/classes/* ext-config-dir/config

Redeploy the WAR files using Tomcat

If you deployed Banner Administrative Pages to a Tomcat web application server, complete thefollowing steps.

Procedure

1. Stop the Tomcat application server.2. Copy the modified Banner Admin WAR files to the Tomcat webapps directory.



a) On the machine where the Tomcat server runs, copy the BannerAdmin.warand the BannerAdmin.ws.war files from the app-staging-dir/javaforms-93/BannerAdmin/dist directory to the webapps directory of the Tomcatinstallation.You should replace the files of the same name that were previously deployed by SolutionManager.

The app-staging-dir is the path to the Administrative Pages staging area from theperspective of the application server machine. It is the same as the path in the Banner 9War File Staging Path field on the app server configuration page in Solution Manager.

Redeploy the EAR file with WebLogic

If you deployed Banner Administrative Pages to a WebLogic web application server, complete thefollowing steps.

Procedure

1. Log on to the WebLogic admin console on the machine where the Administrative Pagesapplication is running.

2. Go to the Deployments section of the console.3. Stop and delete the existing Administrative Pages deployment.4. Install the new deployment from the app-staging-dir/javaforms-93/BannerAdmin/

dist directory.The app-staging-dir is the path to the Administrative Pages staging area from the perspectiveof the application server machine. It is the same as the path in the Banner 9 War File StagingPath field on the configuration page in Solution Manager.


Multi-language support

Multi-language supportThis release supports multiple languages for field names and messages based on the language orlocale you select in your web browser. This includes number, date, and calendar formats for eachsupported language. For system-level messages to be translated correctly, you must use externalconfiguration files.

To install a full Banner 9 language system, the Banner 8 language releases for a specific languageneed to be installed on top of the Banner 8 Baseline prerequisite releases.

Administrative Pages only delivers UI labels and message translations corresponding to formslabels and messages. Dbprocs messages, C resources, Cobol and table data are still provided aspart of the Banner 8.x baseline deliveries. To install in your preferred language, the correspondingBanner Database language releases must be installed before installing Administrative Pages9.3.n.m.

Customized translation of labels and messages

You can create your own customized translation of labels and messages used in the BannerAdministrative Pages application by using Text Manager.

For more information about how to do this in Text Manager, see the Banner General Text ManagerHandbook.

In order for the Administrative Pages application to use your customized translations, you mustchange the following configuration parameters in the config.properties file. To facilitateupdating the config.properties file, you should deploy the Administrative Pages applicationusing the external configuration files option. See Use external configuration files on page 42 formore information.


localizationProvider Controls whether or not Banner Administrative Pagesuses customized label and messages translationsstored in the Banner database. Default value fromautomated deployment by Solution Manager is"dbLocalizationServicesProvider" which configuresthe Banner Administrative Pages application to useyour customized labels and messages created byText Manager in the Banner database. Change to"defaultLocalizationServicesProvider" to configure theBanner Administrative Pages application to only use theresource files delivered with the Banner AdministrativePages releases for labels and messages.




locale.properties.db.refresh.interval Specifies the number of minutes between timesthat the Banner Administrative Pages applicationchecks the database for new label and messagetranslations if the localizationProvider property is set to"dbLocalizationServicesProvider". Default value fromautomated deployment by Solution Manager is 30.

Supported languages for browser settings

You can change the UI language for field names and messages by changing your browser localeto one of these supported languages. The following languages, except for those marked with anasterisk, are supported in Chrome 61 and higher.

• Arabic• Arabic (Saudi Arabia)*• English (UK or GB)• English (Australia)• English (Ireland)• English (India)• English (United States)• French• French (France)• French (Canada)• Spanish• Spanish (Argentina)• Spanish (Chile)• Spanish (Colombia)• Spanish (Costa Rica)• Spanish (Dominican Republic) *• Spanish (Ecuador)*• Spanish (Guatemala)*• Spanish (Latin America)• Spanish (Mexican)• Spanish (Panama)*• Spanish (Peru)• Spanish (Puerto Rico)*• Spanish (Venezuela)• Portuguese



• Portuguese (Brazil)

*Chrome 63.0.3239.132 does not support these languages. If you want to use these languages youmust use Firefox or Internet Explorer.

Supported calendars

Banner 9 supports the following calendar types.

Gregorian

The Gregorian calendar is the default calendar for all languages except Arabic and Arabic (SaudiArabia).

Islamic (or Hijri) calendars

• Islamic civil calendar

For the Arabic locale, the default calendar is the Islamic civil calendar. This is a lunar calendarthat uses a fixed cycle of alternating 29- and 30-day months, with a leap day added to thelast month of 11 out of every 30 years. Several Arab countries use this calendar as the civilcalendar.

• Umm Al-Qura calendar

The Arabic (Saudi Arabia) locale was introduced to support the Umm al-qura calendar. TheUmm al-qura calendar is a Hijri calendar that is based on the sighting method of the crescentmoon and standardized by Saudi Arabia. Public Saudi institutions follow it. The governmentof Saudi Arabia provides an official Gregorian to Hijri / Hijri to Gregorian converter at http://www.ummulqura.org.sa/Index.aspx. Date calculation for the Umm al-qura calendar is donebased on the lunation calculation on jquery.calendars.ummalqura.js. The basis for thatcalculation is the data stored in the 'ummalqura_dat' array.

Note: Chrome does not provide an Arabic (Saudi Arabia) locale, only an Arabic locale. If youwould like to use Chrome's Umm al-qura calendar, you can set the Umm al-qura calendar asthe default calendar for the Arabic locale instead of the Islamic civil calendar. To do so, you mustmake the following change to the Arabic locale configuration: in the Arabic formats.js file (/app/flat/nls/ar/formats.js), replace CALENDARS: [ "islamic", "gregorian" ] with CALENDARS:[ "ummalqura", "gregorian" ].

Support for language-specific sorting

You can configure Banner Administrative Pages to sort appropriately for your database languagesettings using the env.nls.sort parameter in the config.properties file.

For additional information, see Use external configuration files on page 42.



Language-specific label and message properties files

Banner Administrative Pages delivers language and territory specific properties files containing thetranslations for field labels and messages displayed by the Banner Administrative Pages software.

Location of the properties file

For the supported languages, .properties files are delivered, which contain the messages and fieldlabels in the base language.

Message translations are in the .properties file in the /messages/ folder. UI labels are locatedin the .properties file in the /views/ folder.

The following .properties files for French are delivered.

• /messages/fr.properties

• /views/fr.properties

Languages that are territory-specific

The .properties file is also delivered for languages with a territory-specific locale.

For example, the .properties file for French Canadian is delivered with the territory specificlocale, .../messages/fr_CA.properties.

A locale for a specific language and territory can be set up without translations for the specificlanguage and territory installed. For example, to enable to see the same language with the differentdate format or number format settings preferred by a specific territory, the Banner AdministrativePages system will default back to the base language.

To use a locale, you must include it in the config.json file, as shown in the following example.

"formats": ["formats.js"], "messages": ["messages.js","$runtime/js/validation/localization/messages_{lang}.js" ], "default": "en", "locales": ["ar", "en", "es", "fr", "pt", "pt-br" ]}

The pre-configuration sets the default date and number formats for the locale in the formats.jsfile. Calendars and date-picker settings are contained in the calendar and date-picker files. Considerthe following example of a formats.js file for French Canadian (fr-ca):

/* fr-ca formats initialization */



$.extend(Frames.Locale.formats, {INTEGER_FORMAT: "##########", DECIMAL_SEPARATOR: ",", GROUP_SEPARATOR: " ",NUMBER_FORMAT: "#G###G###G###D###############", CURRENCY_SYMBOL: "$",CURRENCY_FORMAT: "#G###G###G###D###############L", DATE_FORMAT: "YYYY/MM/DD",TIME_FORMAT: "hh24:mm"DATE_PARTS: "J M A H M S" });

Data mapping for JLOC2ORA and JLO2ORAX

These are the suggested mappings for browser locales, Banner 8 translations, and Banner 9properties. The values entered for NLS_DATE_FORMAT must be consistent with the OracleSession NLS_DATE_FORMAT Parameter.

BrowserLocale

Locale inJLOC2ORA

Oracle Language andTerritory setting inJLOC2ORA

Date and Calendarsettings in JLOC2ORAX

UsesTransformationtranslations fromproperties withlanguage andterritory code

00-00 00-00 AMERICAN AMERICA NLS_DATE_FORMAT=DD-MON-RRRR

en-US

ar ar ARABIC SAUDI ARABIA NLS_DATE_FORMAT=RRRR/MONTH/DD

NLS_CALENDAR=ARABIC HIJRAH

Optional:

NLS_DATE_LANGUAGE=ARABIC

ar

ar-SA ar-SA ARABIC SAUDI ARABIA NLS_DATE_FORMAT=RRRR/MONTH/DD NLS_CALENDAR=ARABIC HIJRAH

Optional:NLS_DATE_LANGUAGE=ARABIC

ar

cy-GB cy-GB ICELANDIC UNITEDKINGDOM

NLS_DATE_LANGUAGE=ENGLISH

cy-GB



BrowserLocale

Locale inJLOC2ORA




en-AU en-AU ENGLISH AUSTRALIA NLS_DATE_LANGUAGE=ENGLISH

en-AU

en-GB en-GB ENGLISH UNITEDKINGDOM

NLS_DATE_LANGUAGE=ENGLISH

en-GB

en-IE en-IE ENGLISH IRELAND NLS_DATE_LANGUAGE=ENGLISH

en-IE

en-IN en-IN ENGLISH INDIA NLS_DATE_LANGUAGE=ENGLISH

en-IN

en-US en-US AMERICAN AMERICA NLS_DATE_FORMAT=DD-MON-RRRR

en-US

es es LATIN AMERICANSPANISH SPAIN

NLS_DATE_FORMAT=DD/MM/RRRR

es

es-419(ChromeforSpanishLatinAmerica)

es-419 LATIN AMERICANSPANISH MEXICO

NLS_DATE_FORMAT=DD-MON- RRRR

NLS_TIMESTAMP_FORMAT=DD-MON-RRRRHH:MI:SSXFF AM

NLS_TIMESTAMP_TZ_FORMAT=DD-MON-RRRRHH:MI:SSXFF AM TZR

NLS_TIME_FORMAT=HH:MI:SSXFF AM

NLS_TIME_TZ_FORMAT=HH:MI:SSXFF AMTZR

es



BrowserLocale

Locale inJLOC2ORA




es-AR es-AR LATIN AMERICANSPANISH ARGENTINA

NLS_DATE_FORMAT=DD-MON-RRRR

NLS_TIMESTAMP_FORMAT=DD-MON-RRRRHH24:MI:SSXFF

NLS_TIMESTAMP_TZ_FORMAT=DD-MON-RRRRHH24:MI:SSXFF TZR

NLS_TIME_FORMAT=HH24:MI:SSXFF

NLS_TIME_TZ_FORMAT=HH24:MI:SSXFF TZR

es

es-CL es-CL LATIN AMERICANSPANISH CHILE



NLS_TIMESTAMP_TZ_FORMAT=D-MON-RRRRHH24:MI:SSXFF TZR


NLS_TIME_TZ_FORMAT= HH24:MI:SSXFFTZR

es



BrowserLocale

Locale inJLOC2ORA




es-CO es-CO LATIN AMERICANSPANISH COLOMBIA



NLS_TIMESTAMP_TZ_FORMAT= DD-MON-RRRRHH24:MI:SSXFF TZR


NLS_TIME_TZ_FORMAT=HH24:MI:SSXFF

es

es-CR es-CR LATIN AMERICANSPANISH COSTA RICA






es



BrowserLocale

Locale inJLOC2ORA




es-DO es-DO LATIN AMERICANSPANISH PERU *


NLS_TIMESTAMP_FORMAT=DD-MON-RRRRHH24:MI:SS




es

es-EC es-EC LATIN AMERICANSPANISH ECUADOR





NLS_TIME_TZ_FORMAT=HH24:MI:SSXFFTZR**

es



BrowserLocale

Locale inJLOC2ORA




es-GT es-GT LATIN AMERICANSPANISH GUATEMALA






es

es-MX es-MX LATIN AMERICANSPANISH MEXICO






es



BrowserLocale

Locale inJLOC2ORA




es-PA es-PA LATIN AMERICANSPANISH PANAMA






es

es-PE es-PE LATIN AMERICANSPANISH PERU






es



BrowserLocale

Locale inJLOC2ORA




es-PR es-PR LATIN AMERICANSPANISH PUERTORICO


NLS_TIMESTAMP_FORMAT=DD/MM/RRRRHH24:MI:SSXFF

NLS_TIMESTAMP_TZ_FORMAT=DD/MM/RRRRHH24:MI:SSXFF TZR



es

es-VE es-VE LATIN AMERICANSPANISH VENEZUELA






es

fr fr FRENCH FRANCE NLS_DATE_FORMAT=DD/MM/RRRR

fr

fr-ca fr-CA CANADIAN FRENCHCANADA

NLS_DATE_FORMAT=RRRR/MM/DD

fr-ca

fr-fr fr-FR FRENCH FRANCE NLS_DATE_FORMAT=DD-MON- RRRR

fr

pt pt BRAZILIANPORTUGUESE


pt

pt-BR pt-BR BRAZILIANPORTUGUESEPORTUGAL


pt-br



*The Dominican Republic territory is not recognized by Oracle. The Peru territory has been selectedto be used in its place because its characteristics are the closest to the Dominican Republicterritory’s.

**For es-CO and es-EC, the Oracle default time format (12-hour format) needs to be overriddenbecause the customer base in those countries would like it to be 24-hour format.

Edit the JLOC2ORA and JLOC2ORAX tables

Update the JLOC2ORA and JLOC2ORAX tables in the Banner database to provide full support forthe non-English languages.

About this task

The Banner General 8.9.4 delivers a DML script that inserts JLOC2ORAand JLOC2ORAX values.As maintenance, Ellucian recommends that each client log into the Banner database to review thevalues present at your institution, to determine if erroneous, non-supported languages should beremoved.

Procedure

1. Log in to the database with sqlplus user NLSUSER.2. Edit the tables.

JLOC2ORA and JLOC2ORAX edits

You must add these rows to the JLOC2ORA and JLOC2ORAX tables.

Table 2: JLOC2ORA

Locale ORA_LANG ORA_TERR Supports BrowserLanguage

00-00 AMERICAN AMERICA English

ar ARABIC SAUDI ARABIA Arabic

ar-SA ARABIC SAUDI ARABIA Arabic (SaudiArabia)

cy-GB ICELANDIC UNITED KINGDOM English

en-AU ENGLISH AUSTRALIA English

en-GB ENGLISH UNITED KINGDOM English

en-IE ENGLISH IRELAND English

en-IN ENGLISH INDIA English

en-US AMERICAN AMERICA English



Locale ORA_LANG ORA_TERR Supports BrowserLanguage

es LATIN AMERICAN SPANISH SPAIN Spanish

es-419 LATIN AMERICAN SPANISH MEXICO Spanish (LatinAmerica)

es-AR LATIN AMERICAN SPANISH ARGENTINA Spanish (Argentina)

es-CL LATIN AMERICAN SPANISH CHILE Spanish (Chile)

es-CO LATIN AMERICAN SPANISH COLOMBIA Spanish (Colombia)

es-CR LATIN AMERICAN SPANISH COSTA RICA Spanish (CostaRica)

es-DO LATIN AMERICAN SPANISH PERU* Spanish (DominicanRepublic)

es-EC LATIN AMERICAN SPANISH ECUADOR Spanish (Ecuador)

es-ES LATIN AMERICAN SPANISH SPAIN Spanish (Spain)

es-GT LATIN AMERICAN SPANISH GUATEMALA Spanish(Guatemala)

es-MX LATIN AMERICAN SPANISH MEXICO Spanish (Mexico)

es-PA LATIN AMERICAN SPANISH PANAMA Spanish (Panama)

es-PE LATIN AMERICAN SPANISH PERU Spanish (Peru)

es-PR LATIN AMERICAN SPANISH PUERTO RICO Spanish (PuertoRico)

es-VE LATIN AMERICAN SPANISH VENEZUELA Spanish(Venezuela)

fr FRENCH FRANCE French

fr-CA CANADIAN FRENCH CANADA French (Canada)

fr-FR FRENCH FRANCE French (France)

pt BRAZILIAN PORTUGUESE PORTUGAL Portuguese

pt-BR BRAZILIAN PORTUGUESE BRAZIL Portuguese (Brazil)

*The Dominican Republic territory is not recognized by Oracle. The Peru territory has been selectedto be used in its place because its characteristics are the closest to the Dominican Republicterritory’s.

The values entered for NLS_DATE_FORMAT in the JLOC2ORAX table must be consistent with theOracle Session NLS_DATE_FORMAT Parameter.



Table 3: JLOC2ORAX

Locale ORA_PARM ORA_VALUE

00-00 NLS_DATE_FORMAT DD-MON-RRRR

ar NLS_CALENDAR ARABIC HIJRAH

ar NLS_DATE_FORMAT RRRR/MONTH/DD

ar NLS_DATE_LANGUAGE ARABIC

ar-SA NLS_CALENDAR ARABIC HIJRAH

ar-SA NLS_DATE_FORMAT RRRR/MON/DD

ar-SA NLS_DATE_LANGUAGE RRR/MONTH/DD

cy-GB NLS_DATE_LANGUAGE ENGLISH

en-AU NLS_DATE_LANGUAGE ENGLISH

en-GB NLS_DATE_LANGUAGE ENGLISH

en-IE NLS_DATE_LANGUAGE ENGLISH

en-IN NLS_DATE_LANGUAGE ENGLISH

en-US NLS_DATE_FORMAT DD-MON-RRRR

es NLS_DATE_FORMAT DD/MM/RRRR

es NLS_TIMESTAMP_FORMAT DD/MM/RRRRHH24:MI:SSXFF

es NLS_TIMESTAMP_TZ_FORMAT DD/MM/RRRRHH24:MI:SSXFF TZR

es NLS_TIME_FORMAT HH24:MI:SSXFF

es NLS_TIME_TZ_FORMAT HH24:MI:SSXFF TZR

es-419 NLS_DATE_FORMAT DD-MON-RRRR

es-419 NLS_TIMESTAMP_FORMAT DD-MON-RRRRHH:MI:SSXFF AM

es-419 NLS_TIMESTAMP_TZ_FORMAT DD-MON-RRRRHH:MI:SSXFF AM TZR

es-419 NLS_TIME_FORMAT HH:MI:SSXFF AM

es 419 NLS_TIME_TZ_FORMAT HH:MI:SSXFF AM TZR

es-AR NLS_DATE_FORMAT DD-MON-RRRR

es-AR NLS_TIMESTAMP_FORMAT DD-MON-RRRRHH24:MI:SSXFF

es-AR NLS_TIMESTAMP_TZ_FORMAT DD-MON-RRRRHH24:MI:SSXFF TZR

es-AR NLS_TIME_FORMAT HH24:MI:SSXFF




es-AR NLS_TIME_TZ_FORMAT HH24:MI:SSXFF TZR

es-CL NLS_DATE_FORMAT DD-MON-RRRR

es-CL NLS_TIMESTAMP_FORMAT DD-MON-RRRRHH24:MI:SSXFF

es-CL NLS_TIMESTAMP_TZ_FORMAT DD-MON-RRRRHH24:MI:SSXFF TZR

es-CL NLS_TIME_FORMAT HH24:MI:SSXFF

es-CL NLS_TIME_TZ_FORMAT HH24:MI:SSXFF TZR

es-CO NLS_DATE_FORMAT DD-MON-RRRR

es-CO NLS_TIMESTAMP_FORMAT DD-MON-RRRRHH24:MI:SSXFF

es-CO NLS_TIMESTAMP_TZ_FORMAT DD-MON-RRRRHH24:MI:SSXFF TZR

es-CO NLS_TIME_FORMAT HH24:MI:SSXFF

es-CO NLS_TIME_TZ_FORMAT HH24:MI:SSXFF TZR

es-CR NLS_DATE_FORMAT DD-MON-RRRR

es-CR NLS_TIMESTAMP_FORMAT DD-MON-RRRRHH24:MI:SSXFF

es-CR NLS_TIMESTAMP_TZ_FORMAT DD-MON-RRRRHH24:MI:SSXFF TZR

es-CR NLS_TIME_FORMAT HH24:MI:SSXFF

es-CR NLS_TIME_TZ_FORMAT HH24:MI:SSXFF TZR

es-DO NLS_DATE_FORMAT DD-MON-RRRR

es-DO NLS_TIMESTAMP_FORMAT DD-MON-RRRRHH24:MI:SSXFF

es-DO NLS_TIMESTAMP_TZ_FORMAT DD-MON-RRRRHH24:MI:SSXFF TZR

es-DO NLS_TIME_FORMAT HH24:MI:SSXFF

es-DO NLS_TIME_TZ_FORMAT HH24:MI:SSXFF TZR

es-EC NLS_DATE_FORMAT DD-MON-RRRR

es-EC NLS_TIMESTAMP_FORMAT DD-MON-RRRRHH24:MI:SSXFF

es-EC NLS_TIMESTAMP_TZ_FORMAT DD-MON-RRRRHH24:MI:SSXFF TZR

es-EC NLS_TIME_FORMAT HH24:MI:SSXFF




es-EC NLS_TIME_TZ_FORMAT HH24:MI:SSXFF TZR

es-GT NLS_DATE_LANGUAGE DD-MON-RRRR

es-GT NLS_TIMESTAMP_FORMAT DD-MON-RRRRHH24:MI:SSXFF

es-GT NLS_TIMESTAMP_TZ_FORMAT DD-MON-RRRRHH24:MI:SSXFF TZR

es-GT NLS_TIME_FORMAT HH24:MI:SSXFF

es-GT NLS_TIME_TZ_FORMAT HH24:MI:SSXFF TZR

es-MX NLS_DATE_FORMAT DD-MON-RRRR

es-MX NLS_TIMESTAMP_FORMAT DD-MON-RRRRHH:MI:SSXFF AM

es-MX NLS_TIMESTAMP_TZ_FORMAT DD-MON-RRRRHH:MI:SSXFF AM TZR

es-MX NLS_TIME_FORMAT HH:MI:SSXFF AM

es-MX NLS_TIME_TZ_FORMAT HH:MI:SSXFF AM TZR

es-PA NLS_DATE_FORMAT DD-MON-RRRR

es-PA NLS_TIMESTAMP_FORMAT DD-MON-RRRRHH:MI:SSXFF AM

es-PA NLS_TIMESTAMP_TZ_FORMAT DD-MON-RRRRHH:MI:SSXFF AM TZR

es-PA NLS_TIME_FORMAT HH:MI:SSXFF AM

es-PA NLS_TIME_TZ_FORMAT HH:MI:SSXFF AM TZR

es-PE NLS_DATE_FORMAT DD-MON-RRRR

es-PE NLS_TIMESTAMP_FORMAT DD-MON-RRRRHH24:MI:SSXFF

es-PE NLS_TIMESTAMP_TZ_FORMAT DD-MON-RRRRHH24:MI:SSXFF TZR

es-PE NLS_TIME_FORMAT HH24:MI:SSXFF

es-PE NLS_TIME_TZ_FORMAT HH24:MI:SSXFF TZR

es-PR NLS_DATE_FORMAT DD/MM/RRRR

es-PR NLS_TIMESTAMP_FORMAT DD/MM/RRRRHH24:MI:SSXFF

es-PR NLS_TIMESTAMP_TZ_FORMAT DD/MM/RRRRHH24:MI:SSXFF TZR

es-PR NLS_TIME_FORMAT HH24:MI:SSXFF




es-PR NLS_TIME_TZ_FORMAT HH24:MI:SSXFF TZR

es-VE NLS_DATE_FORMAT DD-MON-RRRR

es-VE NLS_TIMESTAMP_FORMAT DD-MON-RRRRHH24:MI:SSXFF

es-VE NLS_TIMESTAMP_TZ_FORMAT DD-MON-RRRRHH24:MI:SSXFF TZR

es-VE NLS_TIME_FORMAT HH24:MI:SSXFF

es-VE NLS_TIME_TZ_FORMAT HH24:MI:SSXFF TZR

fr NLS_DATE_FORMAT DD/MM/RRRR

fr-CA NLS_DATE_FORMAT RRRR/MM/DD

fr-FR NLS_DATE_FORMAT DD-MON-RRRR

pt-BR NLS_DATE_FORMAT DD/MM/RRRR

* For es-CO and es-EC, the Oracle default time format (12-hour format) needs to be overriddenbecause the customer base in those countries would like it to be 24-hour format.


Jasper Server Installation and Configuration for Banner Reports

Jasper Server Installation and Configuration forBanner Reports

Banner Administrative Pages uses Tibco JasperReports Server to produce some reports in BannerStudent, Banner Accounts Receivable, and Banner Finance.

Each new release of Student, AR, and Finance delivers a file containing the latest specifications forthe reports that JasperReports Server produces.

To use these reports, you must install JasperReports Server version 7.1.0, and deploy the latestreports specifications file delivered by each product to the reports server.

If you are upgrading to a new version of Student, AR, or Finance, and you have previously installedthe Jasper reports server, you must deploy the latest version of the reports specifications file foreach product following the instructions in Deploy/Import Reports in Jasper Server.

If you are installing Banner Administrative Pages for the first time or have not previously installedthe reports server, follow all instructions in this section to install and configure JasperReports Serverand deploy the Banner Administrative Pages reports specifications.

Banner Administrative Pages supports using JasperReports Server installed on a Tomcatapplication server.

See the JASPERREPORTS-SERVER-INSTALL-GUIDE for additional details on how to installthe Jasper Reports Server. Yo can download this from the Ellucian Customer Center. Navigate toBanner > Banner-General-9X > Banner-General 7.x JasperServer.

See the JASPERREPORTS-SERVER-UPGRAD-GUIDE for details about the upgrade process ifyou are upgrading from Jasper Server version 6.1.1 to version 7.1.0.

Related tasksDeploy/Import Reports in Jasper Server on page 84

System requirements

You must meet the minimum and recommended requirements to complete a full installation ofJasperReports Server version 7.1.

The following table contains the minimum and recommended resources for a full installation thatincludes Oracle as the ORDBMS and Apache Tomcat as the application server.

The success of your deployment depends on the intended load of the system, number ofconcurrent users, data sets, and whether the databases are installed on the same system as theJasperReports Server

Resource Footprint Minimum Recommended

Disk 10 GB 40 GB+

RAM 4 GB 8 GB+



Resource Footprint Minimum Recommended

Processor 2 core 2.5 GHz + multi-corePentium for Linux

Prepare for Installation

Prepare for the Jasper server installation by ensuring that you have the required Java JDK andTomcat versions installed, and that you download the Jasper Server installation package from theEllucian Download Center.

Procedure

1. Install Oracle JDK-8.2. Create or set the JAVA_HOME system environment variable to point to the Java JDK location.3. Install Tomcat-8.x.

Note: Jasper Soft recommends using 8.5.30. This is the certified version delivered with theJasper Server 7.1.0 default Installation. The installation instructions refer to this version.

4. Download the installation package (TIB_js-jrs_7.1.0_bin.zip), license key, anddocumentation from the Ellucian Download Center located in the Banner > Banner-General-9X> Banner-General 7.x JasperServer download folder.

5. Start the Oracle database instance if it is not already running.The Jasper Server installation process creates Schema/Tables to store metadata.

Install JasperReports Server

Install the JasperReports Server on a Windows, Linux, or Mac OSX server.

Procedure

1. Extract the files from TIB_js-jrs_7.1.0_bin.zip and select a destination.

Server Type Destination

Windows C:\Jaspersoft

Linux /home/user

Mac OSX /Users/user

The jaspereports-server-pro-7.1.0-bin directory appears in the file destination thatyou chose when you extracted the files. The installation instructions refer to this directory as js-install.



2. Copy the oracle_master.properties from js-install/buildomatic/sample_confto js-install/buildomatic.

3. Rename the oracle_master.properties you just copied todefault_master.properties.

4. Edit the default_master.properties file to enter your database and application serversettings.Remove the comment symbol (#) for the corresponding property.

# Application Server SettingsappServerType = tomcat# Tomcat app server root dirappServerDir = /u01/app/tomcat/apache-tomcat-8.5.30#appServerDir = C:\\apache-tomcat-8.5.30# if linux package managed tomcat instance, set two properties belowCATALINA_HOME = /u01/app/tomcat/apache-tomcat-8.5.30CATALINA_BASE = /u01/app/tomcat/apache-tomcat-8.5.30# database typedbType=oracle# name for js user and user to create js userdbUsername = jasperserverdbPassword=passwordsysUsername=systemsysPassword=passworddbHost=localhostdbPort=1521sid=ORCL

Note:

• If you set the appServerType property to skipAppServerCheck, buildomatic skips anyapplication server validation.

• You must use double backslashes (\\) when specifying paths in properties files. Forexample, appServerDir=C:\\Apache Software Foundation\\Tomcat 8.

• The dbUsername must be the same as the Oracle username. Also, buildomatic does notwork with the "sys as sysdba" syntax.

• For Oracle 12c with CDB/PDB, you must prefix jasperserver with c## if using a commonuser (A common user is present in all containers, root and PDBs). For example:c##jasperserver.

• For Oracle 12c without CDB/PDB, or if you are not using a common user, (i.e. you are usinga local user) do not use the c##jasperserver dbUsername. Use the standard jasperserverdbUsername instead.

Refer to Oracle documentation for more information about creating common and localusers.

5. Save the file when you are done entering the settings.6. Start the database server if not already running.7. Stop the Tomcat server.8. Run the js-install script.



This deploys the War file to Tomcat and creates the database objects in oracle.a) Open a Command Prompt as Administrator if using Windows, or open a terminal window if

using Linux or Mac OSX.b) Enter cd js-install/buildomatic to change the directory.c) Run the following test command to ensure that the default_master.properties setup

is correct.

• ./js-install.sh test (Linux command)• js-install.bat test (Windows command)

If the setup is correct, a BUILD SUCCESSFUL message appears at the end of the log.d) Run the following command to install the JasperReports Server without the sample data

and sample databases.

• ./js-install.sh minimal (Linux command)• js-install.bat minimal (Windows command)

Refer to Troubleshooting Error Running js-install scripts on page 86 to reviewtroubleshooting errors during the installation process.

Install license

By default, when you install JasperReports Server it includes an evaluation license that expires afterthe evaluation period. You must replace the evaluation license with a commercial license.

Procedure

1. Download the commercial license (jasperserver.license), from the Ellucian DownloadCenter located in the Banner > Banner-General-9X > Banner-General 7.x JasperServerdownload folder.

2. Stop the tomcat server if it is running.3. Replace the existing jasperserver.license with the new commercial file that you

downloaded.When the JasperReports Server starts, it automatically looks for the jasperserver.licensefile in the home directory of the system user running the application server.

Server Home directory

Linux /home/user/jasperserver.license

Windows C:\Users\user\jasperserver.license

Mac OSX /Users/user/jasperserver.license

4. Optional: Edit the tomacat/bin/setenv.sh file to set a JAVA_OPT value in tomcat toexplicitly point to the license folder that contains the jasperserver.license file if you wantto keep the license file in a directory other that the home directory of the application server user.On Linux and MacOSX, add: export JAVA_OPTS="$JAVA_OPTS -Djs.license.directory=/home/user/Jasper-license-dir".



On Windows, add: set JAVA_OPTS=%JAVA_OPTS% -Djs.license.directory="C:\Jasper-license-dir".

5. Restart JasperReports Server and look at the catalina.out file or the configured log files ofTomcat. After starting Tomcat, check catalina.out to ensure that there are no log statementswhich are marked as ERROR.

6. To ensure that your license is valid, open the Jasper Server URL in a browser, which redirectsyou to the login page. On the login page, if you do not see any red error messages related tolicense, then your license is valid.

Configure JasperReports Server for Banner reports

The integration of Banner Administrative Pages and Jasper Reports Server requires some setupand configuration changes.

About this task

You must perform the following tasks to set up and configure the Jasper Server to integrate it withBanner Administrative Pages:

• Configure Jasper Reports Server URL in Banner Admin• Copy libraries to the Jasper Server• Create a datasource• Import Banner deployable reports

Procedure

1. Stop Jasper Server, if it is running.a) Open a terminal window to the machine where you installed the Tomcat instance that hosts

the JasperReports server and navigate to CATALINA_HOME/binb) Enter the ./catalina.sh stop command.

2. Ensure that you specified the JasperReports Server URL in the configuration of the deployedAdministrative Pages application. You can do this in one of the following ways:a) Enter the JasperReports Server URL in the Reports Server URL field on the Env Settings

page for the environment in Solution Manager, as described in Define the environmentconfiguration on page 23. Then run the Solution Manager deployment job associated withthe Banner Admin Common 9.3.17.0.x release.

Note: You can do this even if you have previously run that deployment job, and SolutionManager will reconfigure, rebuild, and redeploy the Administrative Pages application withthe new configuration information

b) If you have already deployed the Banner Admin Common 9.3.17.0.x release and youdeployed with the external configuration files option (see Use external configuration fileson page 42), you can edit the config.properties file in the external configuration filesdirectory and set the value of the property env.report.thirdparty.service.url tothe URL of the JasperReports Server. After editing the configuration file, you must stop and



then restart the Administrative Pages deployment (BannerAdmin.ws.war in Tomcat or theBannerAdmin deployment in Weblogic) to pick up the configuration change in the externalconfiguration files.

3. Extract reports-jasper-resources.zip to a temporary location in your file system. Youcan find this file in the following locations:

• If you have already deployed the Banner Administrative Pages 9.3.17.0.x release, you canfind the file in the staging-dir/javaforms-93/BannerAdmin/reports directory,where staging-dir is the Banner Pages deployment staging directory (the directory specifiedin Solution Manager for the "Ban 9 War File Staging" field on the BXE-type Application thatyou set up for the Banner Admin Pages deployment for the environment).

• If you have not already deployed the Banner Administrative Pages9.3.17.0.x release, you can find these files in the reports directory of therelease_Admin_application_9.3.17.0.x.zip file in the $BANNER_HOME/general/java directory.

4. From the extracted location:a) Copy WEB-INF/applicationContext-externalAuth-preAuth-mt.xml TO

CATALINA_HOME/webapps/jasperserver-pro/WEB-INF.b) Copy all the jar files from WEB-INF/lib TO CATALINA_HOME/webapps/

jasperserver-pro/WEB-INF/lib.5. Define a JNDI data source resource with the name bannerDS in CATALINA_HOME/webapps/

jasperserver-pro/META-INF/context.xml.The username in this context should represent the user who has “read permission” to theunderlying tables used by the reports (i.e. banproxy). The database URL defined in this datasource should point to the same database as with bannerDataSource defined for Banner 9 datasource configuration.

For example, if you configured bannerDataSource to point to a database on host gvudbs01,then you should also configure bannerDS to point to the same database on gvudbs01.

Reports deployed in JasperReports server will not execute if a JNDI data source with namebannerDS is not present in the CATALINA_HOME/webapps/jasperserver-pro/META-INF/context.xml. Refer to Configure JNDI datasource in JasperReports Server on page85 for sample data source.

While defining datasource , if you did not provide a datasource name as bannerDS, then youmust associate each of the deployed reports with the datasource name that you provided whiledefining it.

Deploy/Import Reports in Jasper Server

Deploy and import Banner reports on the installed JasperReports server.

Procedure

If you are deploying these reports for the first time, then follow the steps as described below. If youalready have deployed reports on this instance of JasperReports server, take a backup of thosebefore you perform these steps.



Follow these instructions for each application for whose reports you want to deploy. For applicationuse finance, student, or arsys.1. Copy the jasper_server_deployable_application_reports.zip file to a temporary

location in your file system from which the files can be uploaded to the Jasper Server through abrowser.You can find these files in the following locations:

a. If you have already deployed the Banner Administrative Pages 9.3.17.0.x release, you canfind the files in the staging-dir/javaforms-93/BannerAdmin/reports directory,where staging-dir is the Administrative Pages deployment staging directory (the directoryspecified in Solution Manager for the "Ban 9 War File Staging" field on the BXE-typeApplication that you set up for the Administrative Pages deployment for the environment).

b. If you have not already deployed the Administrative Pages 9.3.17.0.xrelease, you can find these files in the reports directory of therelease_Admin_application_9.3.n.m.x.zip file in the$BANNER_HOME/application/java directory.

c. There are 3 deployable reports zip files.

• jasper_server_deployable_finance_reports.zip

• jasper_server_deployable_student_reports.zip

• jasper_server_deployable_arsys_reports.zip

2. Start the Jasper Server by navigating to CATALINA_HOME/bin and enter ./catalina.shstart.

3. Login to JasperReports Server portal as superuser/superuser.4. On the landing page on the JasperReports Server portal, click Server Settings from the

Manage menu.5. Click Import on the left side panel.6. On the Import page, click Choose File and select

jasper_server_deployable_application_reports.zip from the temporary locationwhere you had copied the file in Step 1 on page 85.

7. Click Import to deploy the reports and settings.A message similar to Import was successful should appear at the top of the page.

Related conceptsJasper Server Installation and Configuration for Banner Reports on page 79

Configure JNDI datasource in JasperReports Server

Create a Datasource with jndi name as bannerDS.

Procedure

1. Edit the context.xml file in the CATALINA_HOME/webapps/jasperserver-pro/META-INF/context.xml.



The following example is the format for defining a JDNI datasource in Tomcat-8 for the Oracledatabase.

<Resource name="bannerDS" auth="Container" type="javax.sql.DataSource" maxActive="50" maxIdle="10" maxWait="10000" username="banproxy" password="password" driverClassName="tibcosoftware.jdbc.oracle.OracleDriver" accessToUnderlyingConnectionAllowed = "true" testOnBorrow="true" validationQuery="SELECT 1 FROM DUAL" url="jdbc:tibcosoftware:oracle://HostName:Port;SID=ServiceName"factory="com.jaspersoft.jasperserver.tomcat.jndi.JSCommonsBasicDataSourceFactory"/>

Note: TIBCO JasperReports Server has two JNDNI data source factories implementations:

factory="com.jaspersoft.jasperserver.tomcat.jndi.JSBasicDataSourceFactory"

factory="com.jaspersoft.jasperserver.tomcat.jndi.JSCommonsBasicDataSourceFactory"

If the tomcat-dbcp.jar is present in the Tomcat classpath, the JasperReports server uses theJSBasicDataSourceFactory

If the tomcat-dbcp.jar is missing in the Tomcat classpath, the JasperReports server uses theJSCommonsBasicDataSourceFactory

In Tomcat-8, you must use JSCommonsBasicDataSourceFactory because of the internal tomcatchanges. If you copy the data sources to Tomcat 8 from a different Tomcat install, be sure thatthe factory setting is correct.

2. Optional: To use a different Oracle Driver class in place oftibcosoftware.jdbc.oracle.OracleDriver, replacetibcosoftware.jdbc.oracle.OracleDriver with the Driver class name of your choice.You must place it under CATALINA_HOME/webapps/jasperserver-pro/WEB-INF/lib,the required Driver JAR that contains this class.

3. Restart the Jasper Server.

Troubleshooting Error Running js-install scripts

The js-install.bat for Windows machines or js-install.sh for Unix machines creates an output log thatcaptures standard output and error output. If you encounter problems during the execution of thescript, or if you want to remember which options you chose, open the output log file to troubleshootthe problems.

Procedure

1. Open the output log file located available at js-install/buildomatic/logs/js-install-date-number.log.

2. Try to find the first error encountered by the js-install steps.



3. Go to the end of the output log.4. Scroll back through lines of error messages until you find the first error logged. Typically, this

error causes more errors later in the log.5. Finding the original error is the key to understanding the problem. However, this can be tricky

because Java stack traces in conjunction with the Spring application component framework canmake the error output quite long.

6. Incorrect settings in the default_master.properties file cause most problems, which youcan correct by editing your default_master.properties settings.Common errors are:

• Typos in the application server path.• Misspelling the database hostname or password.

7. Recreate your default_master.properties settings:a) Open the file js-install/buildomatic/default_master.properties and make

corrections.b) Save the file.c) Run the js-install script again.

The js-install script uses the current values in the default_master.properties file. Tohelp isolate errors, run the js-install scripts in test mode.


Third-party document image integration configuration

Third-party document image integrationconfiguration

Banner Administrative Pages supports integration with third-party document imaging software. Touse the integration you must manually modify the configuration files for the WAR files created whenSolution Manager deploys Banner Admin Common to enable the integration, and then redeploy theBanner Administrative Pages application.

Update the BannerAdmin.war file for third-party documentimaging integration

Update the config.xml file in the BannerAdmin.war file to enable the third-party documentimaging integration.

About this task

After you use Solution Manager to deploy Banner Admin Common, you must manually modify theconfig.xml file in the BannerAdmin.war file created by the deployment job to enable the third-party document imaging integration. You must then redeploy the BannerAdmin.war file.

Procedure

1. Log on to the Jobsub machine in the environment as the Banner Install User specified on theCredentials page in Solution Manager for the environment.

2. Change your working directory to the Banner Administrative Pages deployment configurationfiles directory for the BannerAdmin.war file.cd ban9-war-staging-directory/javaforms-93/BannerAdmin/config/BannerAdmin

In the examples in this procedure, ban9-war-staging-directory is the directory specifiedin the Banner 9 War File Staging Path field on the Machine page in Ellucian Solution Managerfor the Jobsub machine in the environment.

3. Make a backup copy of the config.xml file.cp -p config.xml config.xml-orig

4. Edit the config.xml file to enable third-party document imaging integration. Modify the lineshown below to change the value from "false" to "true".

Change <param name="IMAGE_ENABLED" value="false"/>

to <param name="IMAGE_ENABLED" value="true"/>5. Update the BannerAdmin.war file with the edited version of the config.xml file.

jar uvf ban9-war-staging-directory/javaforms-93/BannerAdmin/dist/BannerAdmin.war config.xml



Update config.properties file for the BannerAdmin.ws.war filefor third-party document imaging integration

Update the config.properties file, the configuration file for the BannerAdmin.ws.war filethat Solution Manager creates when you deploy Banner Admin Common, to provide requiredconfiguration parameters for third-party document imaging integration.

About this task

If you chose to configure Banner Administrative Pages using the external configuration files option(see Use external configuration files on page 42), you must update the third-party documentimaging integration parameters in the external config.properties file, as described in thatsection.

If you did not choose the external configuration files option, perform the procedure to manuallyupdate the config.properties file in the BannerAdmin.ws.war file that Solution Managercreated when you deployed Banner Admin Common.

Procedure

1. Log on to the Jobsub machine in the environment as the Banner Install User specified on theCredentials page in Solution Manager for the environment.

2. Change your working directory to the Banner Administrative Pages deployment configurationfiles directory for the BannerAdmin.ws.war file.cd ban9-war-staging-directory/javaforms-93/BannerAdmin/config/BannerAdmin.ws

In the examples in this procedure, ban9-war-staging-directory is the directory specified in theBanner 9 War File Staging Path field on the Machine page in Ellucian Solution Manager for theJobsub machine in the environment.

3. Make a backup copy of the config.properties file.

cd WEB-INF/classes

cp -p config.properties config.properties-orig

4. Edit the config.properties file to provide the correct values for the configuration propertiesneeded for third-party document imaging integration..a) Locate the configuration section shown below.

############################### Third party image integration##################################This parameter configures the url for third party image integration.##env.image.url = https://<your_image_server>/<application_path>####This configures any number of static parameters needed for image integration.



##parameters should be listed in the key=value format separated by &##for example DBID=Banner&SCREENID=page_nameenv.image.parameters = DBID=Banner&SCREENID=page_name

b) Update the values for the properties env.image.url and env.image.parameters inthe configuration section:

• Replace the value for env.image.url with the image application url.

For example, env.image.url =https://your_image_server/application_path

• Replace the value for env.image.parameters with the static parameters that theimage vendor provides.

For example, env.image.parameters = DBID=Banner&SCREENID=page_name

Note: The parameters for the env.image.parameters must be listed in the formatshown above, where you separate each key=value pair from the next pair with theampersand character ("&").

5. Change your working directory back to the BannerAdmin.ws.war file configuration filesdirectory.

cd ban9-war-staging-directory/javaforms-93/BannerAdmin/config/BannerAdmin.ws

6. Update the BannerAdmin.ws.war file with the edited version of the config.propertiesfile.jar uvf ban9-war-staging-directory/javaforms-93/BannerAdmin/dist/BannerAdmin.ws.war WEB-INF/classes/config.properties

Redeployment of Banner Administrative Pages with updatedconfiguration files

After you update the configuration files in the BannerAdmin.war file and, if required, in theBannerAdmin.ws.war file, for the third-party document imaging integration, you must redeploy theupdated WAR files to your Banner Administrative Pages application server.

Redeploy to a WebLogic application server

Redeploy the Banner Administrative Pages application to a WebLogic application server aftercustomizing the configuration for third-party document imaging integration.

Procedure

1. Update the BannerAdmin.ear file with the updated BannerAdmin.war file and, if required,BannerAdmin.ws.war file.



In the example, ban9-war-staging-directory is the directory specified in the Banner 9 War FileStaging Path field on the Machine page in Ellucian Solution Manager for the Jobsub machine inthe environment.

cd ban9-war-staging-directory/javaforms-93/BannerAdmin/distjar uvf BannerAdmin.ear BannerAdmin.war

Optionally, if you customized the BannerAdmin.ws.war file because you are not usingexternal configuration files:

jar uvf BannerAdmin.ear BannerAdmin.ws.war

2. Redeploy Banner Administrative Pages using one of the following methods.

• Redeploy the customized BannerAdmin.ear file with Solution Manager by re-running thedeployment job for the latest deployed version of Banner Admin Common with the BuildWar option cleared.

Note: If you use Solution Manager to redeploy Banner Admin Common after customizingthe configuration files as described above for third-party document imaging integrationyou must deploy with the Build War option cleared to preserve your customizations. Ifyou redeploy with the Build War option selected, Solution Manager will regenerate theconfiguration files based on the configuration information in Solution Manager and lose anymanual changes you made to those configuration files. It will then rebuild and redeploy theWAR and EAR files without your customizations.

• Manually redeploy it from the WebLogic console.

Redeploy to a Tomcat application server

Redeploy the Banner Administrative Pages application to a Tomcat application server aftercustomizing the configuration for third-party document imaging integration.

Procedure

1. Redeploy the customized WAR file(s) with Solution Manager by re-running the deployment jobfor the latest deployed version of Banner Admin Common with the Build War option cleared, orgo to step 2 on page 91 to manually redeploy it from the Tomcat application server.

Note: If you use Solution Manager to redeploy Banner Admin Common after customizing theconfiguration files as described above for third-party document imaging integration you mustdeploy with the Build War option cleared to preserve your customizations. If you redeploy withthe Build War option selected, Solution Manager will regenerate the configuration files basedon the configuration information in Solution Manager and lose any manual changes you madeto those configuration files. It will then rebuild and redeploy the WAR and EAR files without yourcustomizations.

2. Manually redeploy the modified BannerAdmin.war file, and the BannerAdmin.ws.war file, ifmodified.a) Stop the Tomcat instance that hosts Banner Administrative Pages.b) Change your working directory to the web applications directory for the Tomcat instance.

cd Tomcat-home/webapps



c) Delete the BannerAdmin WAR files and deployment directories.rm -rf BannerAdmin*

d) Copy the BannerAdmin.war and BannerAdmin.ws.war files from the Solution Managerdeployment staging directory to the Tomcat web applications directory.In the example below, the ban9-war-staging-directory is the directory path to the SolutionManager deployment staging directory from the perspective of the Tomcat web applicationserver.

cp -p ban9-war-staging-directory/javaforms-93/BannerAdmin/dist/BannerAdmin*.war Tomcat-home/webapps

e) Restart Tomcat.


Runner plugin integration

Runner plugin integrationBanner Administrative Pages seamlessly supports the integration of Runner Technologies.

The Banner Admin Common 9.3.13 release delivered a plugin to support Runner Technologies.Contact Runner Technologies for additional integration configuration steps.

Related informationhttp://runneredq.com/


http://runneredq.com/

installation guide - fairmont state university · oracle database supported versions of the oracle...

Documents