NexusAPI
      Back to home
      1. Help Center
      2. Products
      3. NexusAPI

      Nexus API Upgrade

      This article provides a brief description of how to upgrade to the latest version of the NexusAPI

      Introduction

      This document details the upgrade process of the environment and Nexus API. Nexus API can be used alone or as the backbone of Nexus View. Nexus View is a modern and responsive web application CIS interface allowing the CSR to easily access and manage CSM data including Account information, Transactions, Billing and Service Orders. All data used in this document are CSM sample data.

      These installation instructions are valid for the latest release package of Nexus API.

      Requirements for Nexus API & Keycloak

      CSM

      • CSM Release 2021 R1 or later.

      SQL

      • Company database and NexusApi database compatibility mode needs to be minimum 130 (SQL Server 2016).
      • SQL Server running on a static port (i.e., 1433).
      • Database and Database credentials: see the How To document.
      • SQL CONNECTION ISSUE: If there are problems connecting to database, make sure SQL server is set up correctly in SQL Server Configuration Manager. For example, if SQL server running on Port 1433, verify port set to 1433 in SQL Server Network Configurations, Protocols for xxx -> TCP/IP. Under the IP Addresses tab, for IPAll, set TCP Port to 1433.

      System Requirements

      • System requirements for Keycloak can be found at (https://www.keycloak.org/docs/16.1/server_installation/index.html#installing-the-software)
      • Requirements for Improved Search are in the Nexus API Vx.x.x Search Installation document. Recommendation: Install Improved Search and Nexus API on separate application server and SQL Server installed on its own database server.
      • Java (latest version) and JAVA_HOME environment variable set or OpenJDK version 16 and set "JAVA_HOME" and "JRE_HOME”.
      • Crystal Reports (If using) Requires:
      • Installation server requires access to the internet to install additional modules not included in installation package (Needed for NPM modules)

      Additional Notes

      • Downloaded files may need to be “unblocked”.
      • CSM Address Styles USA, Canada and Free Form Extended are currently supported. Nexus View performs address validation and is fully supported for US addresses.
      • SSRS bill print PDFs for prior statements are supported via URL links to a SSRS Server.
      • Crystal Reports PDFs for prior statements is supported via PDFs returned via a file stream.
      • To run the PowerShell scripts, you may have to bypass the execution policy (“powershell –ExecutionPolicy Bypass”). Note: This has to be done each time you open an Admin Powershell.

      Before you begin

      Before you begin any upgrade, it is recommended to take a backup of existing Nexus API/View, including the company and existing NEXUS_API database. You may need to reference the configuration files during the upgrade process.

      Environment Setup

      When running commands in a terminal, open as “Run as Administrator”. When you see ”May need to reboot the machine”, you may simply have to close the PowerShell window and open a new one as an Administrator.

      Downloads

      Do not install the files yet, the scripts or steps will provide instructions. As such, you will need to know where the downloaded file is located later in the process.

      If you are running NodeJS 12.18.3, you can skip this step

      1. Download Node.JS (64-Bit): https://nodejs.org/dist/v12.18.3/node-v12.18.3-x64.msi
      • Version 3.0.0 of Nexus API requires Node.JS v12.18.3

      If you are running Keycloak 16.1.1, you can skip this step

      1. Keycloak

      If you are running Improved Search 7.17.2, you can skip this step

      1. Improved Search

      Extracting Install Package

      Recommendation: If you plan to use the same structure, you will be instructed to backup and delete the existing folders in API Step 1. Not recommended to simply “overwrite” files.

      The .zip provided contains multiple folders.  Extract into a temporary folder. You will be instructed to move these folders and files to the desired in API Step 2. For example:

      Preparing for Upgrade:

      From an Administrator PowerShell window, run the following scripts:

      cd <temporary path>\installUtils\Upgrade, for example: cd c:\temp\InstallUtils\Upgrade\

      1. Run script:
        ./upgrade-1-prepare.ps1

      CAUTION: If you have other applications running using NodeJS, they will be displayed in a list asking to stop all. If you are in a production environment, DO NOT PROCEED.

      Node Upgrade

      If you are already running NodeJS 12.18.3, skip this section.

      1. Node installation:
      2. Select Next.
      3. Accept the Licence Agreement terms and select Next.
      4. Select folder and select Next.

      Remember this path for later in the process.

      1. Check Automatically install the necessary…
      2. Optional: custom installation setup. Select Next when done.
      3. Select Install.
      4. Select Finish to complete installation.
      5. After finishing NodeJS install, you will be directed to complete the additional components from Step 5. if selected.
      6. When finished, node and npm version should be displayed.

      Keycloak – Upgrade

      If you are already running Keycloak 16.1.1, skip this section.

      If not, see the Keycloak Install\Upgrade document for instructions.

      Redis Server

      In v2.4.0, Nexus API can now be set up to send a password to the Redis Server (recommended).

      If you already have a password configured, skip this section.

      To configure your existing Redis Server to expect a password:

      1. In C:\Program Files\Redis\, open redis.windows-service.conf and redis.windows.conf.
      • Update Line 386: Remove comment (#) and update to desired password. You will require this password in the Nexus API setup.
      1. Restart the Redis Windows Service:
      • Restart the Redis: From the Windows Services App, Find Redis in the list, right-click and Restart or select the Restart button.
      1. Enter the newly created password into <path>\installUtils\global\userConfig.json and Save.

      API Setup

      Recommendation: If you plan to use the same structure, backup and delete the existing folders and then extract the package. Not recommended to simply “overwrite” files.

      1. If you are using the same folder structure, you may now backup and delete the existing folders. Nexus API/View is installed in documentation, installUtils, nexus_api and nexus_view
      2. Copy all the extracted folders/files from your temporary folder to the folder you wish to run Nexus API/View from.
      3. Open <path>\installUtils\global\userConfig.json and edit for your environment. Descriptions of each parameter are listed in the User Config Descriptions document.

      From an Administrator PowerShell window, run the following scripts:

      1. cd <path>\installUtils\Upgrade
      2. Run script: ./upgrade-2-api-setup.ps1 (this will create new or overwrite existing configuration files)
      3. During the process, you will be asked for Major and Minor version of CSM.
      4. Enter the CSM Major version (Example of the above version, enter 5 for 2021 R2). Enter the CSM build version (Example of above version, enter 0 for build).

      Then press Enter to continue to build the patch file.

      1. A patch file will be created in the “InstallUtil\sql” folder with required patch stored procedures. The name of the patch file will be: “NexusApiPatchUntil” + _<csmVersionNumber>.sql

      All the separate stored procedures will be copied to “patches” folder

      Excluded stored procedures will be copied to “patch\other” folder.

      1. In SQL, execute <path>\installUtils\SQL\InstallCsmApiDatabaseComponents_.sql against COMPANY database.
      2. In SQL, execute <installUtils>/SQL/Initialize.sql against Nexus_Api database.
      3. Run postInitialize.sql against the company database.
      4. In SQL, execute the patch file created in Step 8. If you chose to skip the creation of this file, all CSM patches can be found in <path>/installUtils/sql/patches.
      5. If Search has not already been installed, see Nexus API V3.0.0 Search Installation document.

      At this point, the API has been upgraded. You can access via Postman. The API documentation can be found under "<path>\installUtils\documentation \apidoc-public\".

      How To

      See the How To document for instructions on Changing your Password, Registering your Software, Creating User Permission Roles and more.

      Configuration

      See the Configuration document to view the steps to configure required and optional components of Nexus API, such as Create New User, Nexus View settings, etc.

      Version History

      Revision

      Description

      Date

      1.0

      Initial Draft

      June 28, 2019

      2.2

      API Upgrade

      November 3, 2020

      2.4.0

      API upgrade changes

      November 30, 2021

      2.5.0

      Improved Search installation steps

      April 28, 2022

      3.0.0

      Updated URLs for Keycloak 16.1.1

      November 9, 2022

      3.2.0

      Added NexusApi database components creation

      March 1, 2023

      3.2.0

      Added Chocolatey install

      June 19, 2023