Ellucian Solution Manager Using Custom Scripting Gary Kendall

Ellucian Solution Manager: Using Custom Scripting Gary Kendall, Virginia Tech Tuesday, October 13 2020 3: 00 p. m. CDT Session 2. 5

Introduction Are there common tasks you need to perform before or after executing a set of Banner upgrades in ESM? Do you need to execute special tasks before, during or after a specific upgrade but worry you might forget? And wouldn’t it be nice to have a better, easier way to handle them? COHESION SUMMIT 2

Agenda 1 What Can ESM Custom Scripting Do For You? 2 How It Works 3 NEW - Custom Scripting for Deployments 4 Tips, Tricks and Troubleshooting 5 Resources 6 Summary / Q&A COHESION SUMMIT 3

Ellucian Solution Manager: Using Custom Scripting What Can ESM Custom Scripting Do For You? COHESION SUMMIT 4

What Is ESM Custom Scripting? ESM provides several hooks before, during and after upgrade job execution where custom shell scripts can be executed automatically • Useful for automating common steps you may be performing manually when running upgrades • Automate tasks/actions related to a specific upgrade If you can run it in a shell script… COHESION SUMMIT 5

Custom Shell Script Entry Points for Upgrades Jenkins BMUI Upgrade-Specific Before Upgrade Before ALL Upgrades Before Each Upgrade After gostage After Compiles COHESION SUMMIT After Each Upgrade After All Upgrades Loop for EACH upgrade 6

Examples COHESION SUMMIT 7

Beginning of ESM Upgrade Job Before the first upgrade package is executed Before ALL Upgrades • Enable database restricted session • Enable autoextend on tablespace data files • Display invalid database objects count • For install schema users: • Save users’ passwords, default roles and profiles • Grant DBA default role • Set common temporary install password COHESION SUMMIT 8

Before Each Upgrade Before each upgrade scheduled in the ESM upgrade job Before Each Upgrade • Edit login. sql script (tablespace changes) • Edit Java program shell scripts (local jobsub mods) COHESION SUMMIT 9

Before a Specific Upgrade Before a specific upgrade is executed Before Upgrade • General 8. 10. 4 – update files with local site-specific seed keys • Batch. Security. java • gurjbif. jar COHESION SUMMIT 10

During a Specific Upgrade – After gostage After During upgrade execution after gostage has completed gostage • Financial Aid 8. 33 – run rfixdlog 2. sql bugfix script • DB Upgrade 9. 7 – apply paper fix to GLBEXTR trigger COHESION SUMMIT 11

During a Specific Upgrade – After Code Compilation After the Pro*C / Pro*COBOL code compilation step(s) After Compiles • General 8. 10. 4 – Recompile new version of Batch. Security. java with updated seed keys COHESION SUMMIT 12

After Each Upgrade Has Executed After each upgrade scheduled in the ESM job After Each Upgrade • Move logs to instance specific ‘hold’ directories • Execute Banner 9/XE menu rebuild procedure COHESION SUMMIT 13

End of ESM Upgrade Job After All Upgrades At end of ESM upgrade job • Disable autoextend on tablespace data files • Restore install schema users’ passwords, default roles and profiles • Revoke DBA default role from install schema users • Display invalid database objects count This script will always be executed if it exists COHESION SUMMIT 14

Ellucian Solution Manager: Using Custom Scripting How It Works COHESION SUMMIT 15

Custom Scripting Execution ESM uses Jenkins to execute selected upgrades 1. ESM generates upgrade job shell script and submits to Jenkins 2. Jenkins agent executes ESM job shell script (main. sh) • Stages upgrade package(s) • Checks for existence of prebmui. sh / prebmui. cmd – if exists it is executed • Executes BMUI (bmui. jar) to run selected upgrade(s) • Checks for existence of postbmui. sh / postbmui. cmd – if exists it is executed postbmui. [sh|cmd] is always executed at end of ESM upgrade job if it exists regardless of job success/failure COHESION SUMMIT 16

The Banner Multi-Upgrade Installer • Executed in ESM-generated Jenkins job from main. sh • Executes selected upgrades/patches in ESM • BMUI instruction sets control upgrade installation steps • Always updated whenever Get New Releases is executed in ESM Different versions of BMUI – matched to installed version of ESM • BMUI executes custom upgrade scripts before/during/after upgrades COHESION SUMMIT 17

Custom Scripting Entry Points BMUI checks for existence of other custom scripts at various points during upgrade job pre_upgrade. shl Executes before each upgrade Example – General 8. 10. 4 gen 81004 u. trz pre_[upgrade_file_name]. shl Executes before specific upgrade post_db_[upgrade_file_name]. shl Executes after database steps in specific upgrade COHESION SUMMIT 18

Custom Scripting Entry Points BMUI checks for existence of other custom scripts at various points during upgrade job pre_upgrade. shl Executes before each upgrade Example – General 8. 10. 4 gen 81004 u. trz pre_gen 81004 u. shl Executes before specific upgrade post_db_gen 81004 u. shl Executes after database steps in specific upgrade COHESION SUMMIT 19

Custom Scripting Entry Points BMUI checks for existence of other custom scripts at various points during upgrade job post_code_[upgrade_file_name]. shl Executes after code compile steps in specific upgrade post_upgrade. shl Executes after each upgrade COHESION SUMMIT 20

Custom Scripting Entry Points BMUI checks for existence of other custom scripts at various points during upgrade job post_code_gen 81004 u. shl Executes after code compile steps in specific upgrade post_upgrade. shl Executes after each upgrade COHESION SUMMIT 21

ESM Upgrade Execution Jenkins Stage Upgrade Packages START Yes prebmui. sh ? Yes Execute prebmui. sh No postbmui. sh ? BMUI Execute postbmui. sh No Yes RC=0 ? No COHESION SUMMIT END 22

ESM Upgrade Execution BMUI START pre_upgrade. shl pre_gen 81004 u. shl Upgrade Instructions post_db_gen 81004 u. shl post_code_gen 81004 u. shl post_upgrade. shl COHESION SUMMIT END 23

Example – DB Upgrade 9. 15 / Ethos API DB 9. 12 Custom scripts in $BANNER_HOME/upgrades/bmui_custom Custom scripts to execute: prebmui. sh pre_upgrade. shl postbmui. sh COHESION SUMMIT 24

Example – DB Upgrade 9. 15 / Ethos API DB 9. 12 Execution Control main. sh bmui. jar Start prebmui. sh pre_upgrade. shl DB Upgrade 9. 15 post_upgrade. shl pre_upgrade. shl Ethos API DB 9. 12 post_upgrade. shl postbmui. sh COHESION SUMMIT End 25

Danger Will Robinson! A non-zero return code in any custom shell script (other than postbmui. sh) will cause ESM to immediately abort the upgrade job in progress The postbmui. sh script will still be executed at the end of the upgrade job regardless of any previous errors including custom shell script errors COHESION SUMMIT 26

Ellucian Solution Manager: Using Custom Scripting for Deployments COHESION SUMMIT 27

Custom Scripting Execution - Deployments There are 3 types of ESM deployments • Banner 9 applications • Banner Admin pages • Banner Access Management application Custom scripting hooks are available in both build and deployment steps of ESM deployment jobs COHESION SUMMIT 28

Custom Scripting Execution - Deployments Build - Banner 9 applications • pre. Build. sh – make changes to application content in staging area before build • post. Build. sh - make changes to WAR file after build • Access to environment variables – see ESM 1. 16 User Guide pp. 95 -99 COHESION SUMMIT 29

Custom Scripting Execution - Deployments Build - Banner admin pages / Banner Access Management application • pre. Build. sh – make changes to application content in staging area before build; runs before ESM applies Environmentspecific configuration • Access to environment variables Staging Locations Template configuration files $APPSTAGE/deliver/config Delivered WAR files $APPSTAGE/deliver Delivered JAR files to include in the deployment WAR files $APPSTAGE/ext COHESION SUMMIT 30

Custom Scripting Execution - Deployments Build - Banner admin pages / Banner Access Management application • post. Build. sh - make changes to WAR file after build • Access to environment variables Staging Locations Configuration files used to create deployment WAR and EAR files $APPSTAGE/config $APPSTAGE/ear Deployment WAR and EAR files $APPSTAGE/dist COHESION SUMMIT 31

Custom Scripting Execution - Deployments Deploy – For all deployment types • pre. Deploy. sh – run pre-deployment actions on application servers • post. Deploy. sh – run post-deployment actions on application servers • Access to environment variables – see ESM 1. 16 User Guide pp. 95 -99 • Custom deploy scripts can run for all application server deployments or targeted to a specific application server Ø App server-specific script(s) take precedence over common scripts COHESION SUMMIT 32

ESM Build/Deploy Execution Jenkins Stage Deployment Files START Yes Common pre. Build. sh ? No Execute Yes Common post. Build. sh ? Build No Execute 1 COHESION SUMMIT 33

ESM Build/Deploy Execution Jenkins 1 App. Server Yes pre. Deploy. sh ? No Execute Yes Common pre. Deploy. sh ? Yes App. Server post. Deploy. sh ? Deploy No Execute Yes Common post. Deploy. sh ? No No COHESION SUMMIT END 34

Ellucian Solution Manager: Using Custom Scripting Tips, Tricks and Troubleshooting COHESION SUMMIT 35

How To Set Up Custom Scripts for Execution • Store your custom shell scripts in specified directory locations • Follow specified naming conventions • Use symbolic links to custom scripts if desired Be sure to add and/or remove custom scripts as needed to match your planned upgrades in ESM! COHESION SUMMIT 36

Custom Scripting Directory Locations For upgrades $BANNER_HOME/upgrades/bmui_custom For deployments to specific application server for an application $Ban 9 War. File. Staging. Path/deploy. Scripts/[App. Name]/[App. Server] For deployments to all application servers for an application $Ban 9 War. File. Staging. Path/deploy. Scripts/[App. Name] COHESION SUMMIT 37

Custom Shell Script Tips • Use bash shell (#!/bin/bash) • Always set explicit return code value on exit • In postbmui. sh test $BMUI_STATUS for success/failure of upgrade(s) • Use Oracle Wallet to secure database user credentials • Test custom scripting to avoid unexpected exceptions COHESION SUMMIT 38

Manually Pre-Stage Upgrades How can I stage changes that need to be made to an upgrade package before installing the upgrade? Use wget to download upgrade package from ESM local repository /[ESMdir]/admin. App/Banner. Upgrade. Repository/Upgrade. Artifacts COHESION SUMMIT 39

Example using wget Options –nv no-verbose – print basic status and error messages -O output-document – write download to specified file #!/bin/bash UPGRADE_PKG=’gen 81004 u. trz’ export WGETRC=/path/to/your/. wgetrc cd /path/to/your/staging/directory wget -nv -O ${UPGRADE_PKG} http: //esm: 8081/admin/scripts/download. From. Esm? download. Type=UPGRADE&file. Path=${UPGRADE_PKG} COHESION SUMMIT 40

Jenkins and BMUI Processes banner 95540 banner 42955 banner 42957 banner 43402 1 0 May 25 ? 95540 0 09: 17 ? 42955 0 09: 17 ? 42957 88 09: 17 ? 95540 42955 42957 43402 06: 34: 38 /apps/local/jdk 1. 8/bin/java -jar agent. jar http: //[host]/computer/DEVL_BMUI_AGENT/slave-agent. jnlp -secret ****** 00: 00 /bin/sh -xe /tmp/hudson 2466125301510285665. sh 00: 00 /bin/bash. /main. sh 00: 03: 18 /apps/local/jdk 1. 8/bin/java -jar bmui. jar path inst/ prop. File inst/install. properties agent. jar hudson 2466125301510285665. sh main. sh bmui. jar COHESION SUMMIT 41

How to Kill a Running ESM Job If an upgrade job hangs we want to kill it gracefully Which process do we terminate? banner 95540 banner 42955 banner 42957 banner 43402 1 0 May 25 ? 95540 0 09: 17 ? 42955 0 09: 17 ? 42957 88 09: 17 ? 06: 34: 38 /apps/local/jdk 1. 8/bin/java -jar agent. jar http: //[host]/computer/DEVL_BMUI_AGENT/slave-agent. jnlp -secret ****** 00: 00 /bin/sh -xe /tmp/hudson 2466125301510285665. sh 00: 00 /bin/bash. /main. sh 00: 03: 18 /apps/local/jdk 1. 8/bin/java -jar bmui. jar path inst/ prop. File inst/install. properties Control returns to main. sh allowing postbmui. sh to execute COHESION SUMMIT 42

Ellucian Solution Manager: Using Custom Scripting Resources COHESION SUMMIT 43

Modification Shell Scripts Custom scripting examples can be obtained from Google Drive at http: //bit. ly/vt-esm-scripting https: //drive. google. com/drive/folders/10 ZMNJ 2 QEa 443 Bo. PTKs. Xcnsx 0 Si 920 DZS? usp=sharing Download file Custom_Scripting. zip COHESION SUMMIT 44

User Group Forums Ellucian e. Communities Banner General and Technical forum bannerdba Listserv Hosted by University of Tennessee at Martin Send your email address to bannerdba-join@mailman. utm. edu COHESION SUMMIT 45

Ellucian Solution Manager: Using Custom Scripting Summary / Q&A COHESION SUMMIT 46

Summary • Multiple points available to execute custom scripts • Jenkins (ESM) job shell scripts and BMUI look for custom scripts • Follow file name syntax especially for upgrade-specific and deployment-specific scripts • Store in designated locations (upgrade vs. deployment scripts) • Terminate hung BMUI process gracefully for ‘clean’ ESM job exit • How can you use ESM custom scripting to install upgrades more efficiently? COHESION SUMMIT 47

“Loading new software into new computers and using it for the first time was like playing Russian roulette. It demanded and got a lot of respect. ” Gene Kranz Questions

Ellucian Solution Manager: Using Custom Scripting Gary Kendall gary. kendall@vt. edu Session 2. 5