Banner 9 code customization

Policy regarding updates to Ellucian-supplied code

Updates to baseline code will only be applied when installing patches from Ellucian or an approved third-party vendor, or when instructed by Ellucian in the course of resolving a problem. Exceptions must be approved by the CIO.

Introduction

The Banner 9 platform is significantly different from previous versions, so the procedure for performing code customization is also significantly different.

Before working on a customization to Banner 9 code, it is highly recommended that you become familiar with the following documents:

To assist with management of your local Git repository clones, you may wish to download a Git GUI. A popular free option is SourceTree, which may be downloaded at https://www.sourcetreeapp.com.

Obtaining source code

Banner 9 source code is located in Gitlab (code.oakland.edu) in the ellucian-applications group. The Director of Enterprise Applications is the primary owner of this group, and other owners include members of the Database Administration team. To obtain developer access to the group, contact one of the owners.

Setting up your workstation

Once you have access to the group, you will need to clone the application's repository to your workstation. If you are already comfortable with performing development of Java or Java-based code on a Windows machine, you may skip this section; however, you will need to install and manage access to the appropriate Grails SDK version(s) on your own.

This section describes how to set up a development workstation in a Linux virtual machine, assuming your primary desktop is Windows. If you have a Mac or a Linux desktop, or you already have a Linux VM, you can skip the VM setup.

VM setup

The details of how to perform these steps are not provided; refer to relevant documentation.

  1. Install Virtual Box (download from https://www.virtualbox.org)

  2. Download latest Ubuntu LTS ISO (from https://ubuntu.com)

  3. Create an Ubuntu virtual machine according to Ellucian's development workstation specs.

Tools needed

This section describes how to install tools needed for SSB 9 development.

Homebrew

If you are a Mac user, you may wish to install Homebrew. See https://brew.sh for more information.

Curl

If curl is not installed on your system already:

  • Linux users, run: yum install curl

  • Mac users, assuming you are using Homebrew, run: brew install curl

SDKMAN

Install SDKMAN (https://sdkman.io) - this will help you to manage your Grails and Java SDK versions. To install, run: 

curl -s "https://get.sdkman.io" | bash

The installation will add some statements to the bottom of your .bashrc or .bash_profile file (or create it if it does not exist).

Grails

Once SDKMAN is installed, use it to install the Grails SDK. You may need different versions of Grails, depending on which version of Banner you are working with.

For Banner self-service products prior to September 2019, run: 

sdk install grails 2.5.0

For Banner self-service products after August 2019, run: 

sdk install grails 3.3.2

OpenJDK

To install a the most recent version of OpenJDK on your Linux server, you can run: 

yum install java-1.8.0-openjdk-devel.x86_64

If you need to manage multiple versions of OpenJDK on your desktop, you can manage them using SDKMAN. Refer to https://sdkman.io/jdks for more information.

Terminal session

Add the following to your .bashrc file, above the SDKMAN initialization section: 

export GRAILS_OPTS="-XX:MaxPermSize=4096m -Xmx4096M -server"

NOTE: you may add more memory to the GRAILS_OPTS statement if available.

Initial setup of repository clone

Clone the repository

You will need to clone the repository for the module you are working on. In this example, we will assume that you are working on Banner Student Registration SSB. To create a clone, run: 

git clone [email protected]:ellucian-applications/banner/apps/banner_student_registration_ssb_app.git

Create a local branch

If you are working on a Linux VM, you will need to create a local branch at the tag for the release you are working on before you can use SourceTree to manage it; otherwise, you may skip this step, and use SourceTree to create your local branch later. To manually create the local branch now, run the following: 

git branch oakland/test/registrationselfservice-9.15.0.1 9dab5c94
git checkout oakland/test/registrationselfservice-9.15.0.1

When you initially clone the repository, it points to Ellucian as your origin server. We need to modify it to point to Oakland's Gitlab. You can create and run a script to do this, using the following content:

{{{#!/bin/bash # # verify Git project #

if [ ! -d .git ] then

  • echo Not in a Git repository exit 1

fi

# # determine Git project # strProject= if echo pwd | grep "ellucian-applications" then

  • strProject="ellucian-applications"

fi if echo pwd | grep "banner-xe-applications" then

  • strProject="banner-xe-applications"

fi if [ -z $strProject ] then

  • echo Not in a project directory exit 2

fi

# # back up .gitmodules # if [ -f .gitmodules.orig ] then

  • cp -p .gitmodules .gitmodules.save

else

  • cp -p .gitmodules .gitmodules.orig

fi

# # edit .gitmodules # if [ -f .gitmodules ] then

fi

# # back up .git/config # if [ -f .git/config.orig ] then

  • cp -p .git/config .git/config.save

else

  • cp -p .git/config .git/config.orig

fi

# # edit .git/config # case "$strProject" in "banner-xe-applications")

"ellucian-applications")

esac }}}

Clone the submodules

Ellucian uses submodules for their reusable code. Clone them with the following command: 

git submodule update --init --recursive

Proceed

You may now use SourceTree to manage your branch. If you did not create a local branch earlier, you may do so now.

Updating the customization

In SourceTree:

  1. Open your repository.
  2. Ensure that the file status is clean (no changes that need to be committed). Stash any changes if necessary.
  3. Find and click on the tag for the release you are working on.
  4. In the graph window, right-click on the highlighted commit and select Branch...
  5. Create a local branch for this release.
  6. Open each submodule and confirm that its current commit is pointing at the correct release. We expect to see a detatched HEAD with a tag for the module and release you are working on pointing to it. If this is not the case:
    1. Find the tag for the module and release you are working on.
    2. In the graph window, right-click on the highlighted commit and select Checkout...

Copy the *.example files to files with the .groovy extension, and configure them as needed.

Check the gradle.properties or the application.properties file for the version of Grails being used. If it is not installed, install it using: 

sdk install grails x.y.z

where x.y.z is the version.

Once it is installed, run: 

sdk use grails x.y.z

If you are also using grails to manage your Java home, run: 

sdk use java x.y.z-dist

where x.y.z is the version and dist is the distribution as described at https://sdkman.io/jdks.

Oakland's only customization is to the banner-core plugin. Open that plugin in SourceTree, and create a local branch for the release you are working on.

You will need to cherry-pick changes from a previous version of the customization into your new branch by finding and clicking on that branch in the left-hand window, and then right-clicking on the highlighted line in the graph and selecting Cherry Pick... Changes will be merged if possible, but you will need to manually resolve any conflicts.

Testing the customized app

After you have made your changes, you can test them with the command: 

grails run-app

This will run the module in an embedded Tomcat instance on your workstation.

Once you are sure that the customization is working as expected, you may commit your changes to your local branch, and build the application using: 

grails war

The war file that is built will be placed into the ESM staging area for that application and version, in the $STAGING_AREA/current/web-app directory. This must be done BEFORE you use ESM to deploy the app. You can also use a preBuild.sh custom deployment script to move your custom war file from some other staging area on the jobsub server to $STAGING_AREA/current/web-app.

Potential issues

Resolving dependencies

If you are trying to reconstruct a modification from an older version of a Banner SSB app, you may find that grails will not resolve some of the dependencies, and your attempts to compile or run the customized app (described above) may hang.

Ideally, the way to get around this would be to edit the grails-app/conf/BuildConfig.groovy file in your application to add newer repositories that contain the missing dependencies. First, try the following:

  1. Edit grails-app/conf/BuildConfig.groovy
  2. Search for "repositories".

  3. Under the line that says "MavenCentral()", add the following: mavenRepo "https://repo.spring.io/ui/native/plugins-release/"

  4. Save the file
  5. Try running "grails run-app" or "grails compile" again.

If this does not help, you can try manually downloading the dependencies. To do this, use the following steps, repeating as needed:

  1. Run grails dependency-report
  2. Make note of the first dependency that you are attempting to download.
  3. Use Ctrl-C to exit the dependency report.

  4. Browse to https://repo.spring.io/ui/native/plugins-release to find the missing plugin.

  5. From there, navigate to the download page for the missing plugin. For example, if you are missing org.springframework.security:spring-security-cas:3.2.0.RC1, browse to https://repo.spring.io/ui/native/plugins-release/org/springframework/security/spring-security-cas/3.2.0.RC1

  6. Download the .jar and .pom files from the web page to the corresponding directory on your workstation. For example, if you are missing org.springframework.security:spring-security-cas:3.2.0.RC1, save the .jar and .pom files to ~/.m2/repository/org/springframework/security/spring-security-cas/3.2.0.RC1 (where ~ is the home directory on your workstation).
  7. Repeat as needed until the dependency report completes without having to download any additional plugins.

Gradle issues

Some older versions of the Banner applications may run into the error described in CR-000169071 at the Ellucian Support Center. If necessary, run the commands shown in that defect report in your terminal window and then retry the grails run-app.

DataAdminHowTo

DB_Administration