On-Premises or Self-Hosted

  • On-Premises Pre-Installation Requirements

    There are several steps to bringing your ReadyWorks instance into full Production. In general, these steps include:

    1. Hardware and Server Software Installation.
    2. Network Configuration.
    3. ReadyWorks Platform Installation and Testing.
    4. Configuration of Single Sign-On.
    5. Establishing Extract, Transform, Load (ETL) connections between your internal systems and ReadyWorks.
    6. Mapping the ETL data into the ReadyWorks front-end.
    7. Installation of customized scripts for Reports, Charts, Views, Forms and Self-Service Portals.
    8. Configuring the platform based on your specific process as defined in the Process Decomposition meetings with your Senior Technical Program Manager.

    This document covers the first item in the above list.

     

    Target Audience

    Within this guide, you will find the hardware and software prerequisites needed before a typical ReadyWorks installation. This guide is targeted toward system and network administrators with sufficient rights to stand-up a new server and make network configuration changes, as necessary. In addition, data needed to make connections between ReadyWorks, and other online data sources is included to help speed the process to a Production State. Traditionally these steps are handled independently without ReadyWorks involvement.

     

    Implementation Planning

    Prior to starting work on the Hardware and Software deployment, most customers will have had to accomplish the following:

    • Gain approval to establish a new Server/VM for the ReadyWorks instance.
    • Determine the backup strategy for the ReadyWorks instance.
    • Determine any antivirus requirements for the new ReadyWorks instance.
    • Identify where a development ReadyWorks instance will reside.
    • Gain approval for necessary network changes required for the ReadyWorks instance to communicate throughout the network.
    • Ensure end-users can reach the Server for the use of Self-Service Portal pages.
    • Please confirm how many databases/sources of data outside of ReadyWorks which will provide data?
    • For later Single Sign-On purposes, does your organization use LDAP or SAML authentication?       
      • If SAML authentication, who is the identify provider?

     

    SERVER PREPARATION

    ReadyWorks consists of two components: Web Application Server and Database Server. For most environments, both ReadyWorks components are installed on a single server as an appliance. However, we can split the database server from the web server if desired.

    Hardware Requirements

    Please verify that your servers meet the requirements described below regarding Hardware and Software. 

     

     

    Component Requirement
    Chassis Virtual or Physical                   
    Memory

    16GB RAM minimum

    (32 GB RAM recommended)
    Processors

    4 Cores minimum

    (8 Cores recommended)
    Hard Disk

    200GB OS Partition minimum

    300GB Data partition minimum

     

    Software Requirements

    Minimum operating system, software, and additional requirements for the ReadyWorks Server.

    Component Min. Version
    Operating System Microsoft Windows Server 2012 R2 or greater               
    PowerShell

    5.0 or greater

    (PS 3.0 standard on Windows Server 2012 R2)
    Additional

    Domain joined.

    Internet access during installation     
    Browser

    Microsoft Edge (recommended)

     

     

    Software Downloads

    In preparation for the forthcoming ReadyWorks install, please download these packages and have them available on the fully configured server:

    • ReadyWorks Server
    • Notepad++
    • My SQL Workbench

     

    Please note that Notepad++ and MySQL Workbench will be removed at the end of the upcoming installation process.

     

    NETWORK CONFIGURATION CHANGES

    Network and firewall changes are required to fully support the client, administrative, and management features of ReadyWorks.

    DNS Configuration Changes

    To assure easy access to ReadyWorks for end users, create a CNAME record in DNS. A simple and easy to remember name similar to the example below will suffice:

    readyworks.yourcompany.com

    Note: yourcompany.com should be replaced with your fully qualified domain name (FQDN).

    Firewall Changes

    Depending on your internal firewall configuration, the following firewall rules may need to be configured on either the ReadyWorks Server or firewall appliance.

     

    Note: All firewall changes and network configurations are performed by customer employees, in accordance with security guidelines of your organization.

    Service Port                          Protocol            Source                              Target
    HTTP 80 TCP

    ReadyWorks User

    Workstation

     

    		 ReadyWorks Server

    SMTP

    (mail routing)

    		 25 TCP

    ReadyWorks

    Server

     

    		 SMTP Relay

    HTTPS

    (if applicable)

    		 443 TCP

    ReadyWorks User

    Workstation

     

    		 ReadyWorks Server
    SSO

    Based on your SSO solution additional ports may be required. 

    See your ReadyWorks SSO installation documentation for specifics. 

     
    ETL Connectors

    The configuration is dependent upon the system ReadyWorks is trying to access. Please ensure there is access between the ReadyWorks server and the online data sources where data to be extracted resides.

     

     

     

     

     

    Additional Outbound Email Configuration Settings

    These values will be provided to you by your messaging administrator. ReadyWorks will work with you to establish this configuration when the server is installed.

    Service Value
    Mail Server Host Name The URL of your messaging server
    Default Outbound Email Account The email account from which triggered communications (TCOMMs) will be sent to end users to coordinate their activities.
    Username (when authentication is required) Username as determined by authentication to your SMTP server.              
    Password (when authentication is required) Password as determined by authentication to your SMTP server.

     

    Note: All email configuration settings will be input and managed by customer employees. ReadyWorks will not have direct access to these settings.

     

     

    Extract, Transform and Load Connector Requirements

    Data Sources

    Using our ETL Module, we will configure scripts to run periodically that extracts relevant information from online data sources into ReadyWorks Staging Tables. Each connection Once the Staging Tables are populated, a series of Data Mapping Scripts will be constructed to transform and normalize the data. The normalized data will then be loaded into Asset Schema Tables that are used by the front-end ReadyWorks application for the management and orchestration of assets within your environment.

    To begin this work on the extraction scripts, please gather a list of all Data Sources where information to populate ReadyWorks will be found.

     

    Service Accounts

    To gain access to your sources of data, ReadyWorks leverages Service Accounts for login to gain access to the underlying data. Service accounts run automated business processes (like ETL) and are used by ReadyWorks, not a person once in production. A single service account may be used on multiple platforms.

    Please obtain service accounts with rights to authenticate to each platform that will provide data to the ReadyWorks platform. Also ensure that any unique requirements are identified, such as password less accounts, Kubernetes APIs, etc. Also, see notes below.

    Note 1: These service accounts need local rights on the ReadyWorks server to execute programs (e.g., to run automatic overnight data syncs)

     Note 2: Please note that all service account credentials will be solely held, controlled, and input by our Customer's employees. Only our customer's employees will have direct access to these service accounts. ReadyWorks provides guidance and support throughout this process.

     

    Data Definition for the Data Extraction

    To gain access to the data in corresponding systems, additional information is needed to interpret the data and provide context to the fields we pull. We need the following information for that context:

    • Confirmation of REST APIs on all online data sources (unless shared network folders as a data source).
    • URL for each online data source. 
    • Any other specifications helpful to extract data by upload from a shared folder.
    • Please provide the proper SSL Certificate.
    • SMTP server settings and the appropriate SMTP account from which ReadyWorks mail will be sent.
    • Please ensure the following abilities o Ability to execute the RW Install EXE on the server.
      • Ability to run PowerShell scripts for the ETL Connectors on the server.
      • Ability to access other install files that are delivered via an agreed upon method to the server, prior to the installation.

     

    Note: All data extraction and access to APIs will be actions performed by Customer or Partner employees. ReadyWorks provides guidance and support but cannot have direct access to credentials or the data sources themselves.

    See more
  • Upgrading ReadyWorks in On-Premises or Self-Hosted Environments
     
    Upgrading ReadyWorks to the latest version ensures you have access to new features, improvements, and security enhancements. This guide provides detailed instructions for ReadyWorks administrators with server access to perform an upgrade in on-premises or self-hosted environments.
     
    Note: Before proceeding, please review the latest Release Notes to understand the changes in the new version. 

    Prerequisites

    • Administrator Access: Ensure you have server-level administrative privileges.
    • Backup Tools: MySQL Workbench or a similar database management tool.
    • Web Browser: Use Chrome or Edge for certain steps; Internet Explorer may not be compatible.
    • Latest ReadyWorks Package: Obtain the new version’s ZIP file from the official source or your ReadyWorks account manager.

    Upgrade Steps

    1. Confirm Current Version and Remove Database Views

    1. Log into the ReadyWorks Front End:

      • Open your web browser and navigate to the ReadyWorks login page.
      • Enter your administrator credentials.

    2. Navigate to Configuration Options:

      • Go to the top menu and select Configuration.
      • Click on Options.

    3. Remove Existing Database Views:

      • Click on Remove Views.
        • Note: This step drops existing database views to prevent conflicts during the schema update.

    2. Backup the www Directory

    1. Access the Server:

      • Log into the server where ReadyWorks is installed.

    2. Locate the www Folder:

      • Navigate to the ReadyWorks installation directory, typically found at C:\ReadyWorks\www or a custom installation path.

    3. Create a Backup:

      • Copy the entire www folder.
      • Paste it in the same directory or a safe backup location.
      • Rename the copied folder to include the current version number, e.g., www_0603.

    3. Backup the ReadyWorks Database

    1. Open MySQL Workbench:

      • Launch MySQL Workbench or your preferred database management tool.

    2. Create a Self-Contained Backup:

      • Connect to the ReadyWorks database.
      • Select the database and choose the option to export it.
      • Save the backup as a self-contained file.
        • Note: This backup is precautionary and may not be used during the upgrade.

    3. Handle Export Dump Errors (If Any):

      • If you encounter export dump errors, refer to the [process to resolve export errors] (insert link or reference to the process here).

    4. Log Out of the ReadyWorks Front End

    • Ensure that all users are logged out to prevent data inconsistencies.
    • Close all browser sessions connected to ReadyWorks.

    5. Prepare the New Version Files

    1. Extract the New Version ZIP File:

      • Locate the downloaded ZIP file of the new ReadyWorks version.
      • Right-click the ZIP file and select Extract All.
      • Choose a temporary location for the extracted files.

    2. Verify Extracted Files:

      • Ensure all files and folders have been extracted successfully.

    6. Update the www Directory with New Files

    1. Delete Old Files:

      • Navigate back to the original www folder (C:\ReadyWorks\www).
      • Delete all contents within the www folder.
        • Warning: Ensure you have completed the backup in Step 2 before deleting.

    2. Copy New Files:

      • From the extracted new version folder, select all files and folders.
      • Copy and paste them into the now-empty www folder.

    7. Restore Configuration Files

    1. Copy Configuration Files from Backup:

      • From your backed-up www folder (www_0603), locate:
        • database.php
        • client_config.php

    2. Paste Configuration Files into New www Folder:

      • Copy these two files into the new www directory.
      • Overwrite any existing files if prompted.
        • Note: The existing edit_me database and config files in the new version can remain unchanged.

    8. Update the Database Schema

    1. Edit the client_config.php File:

      • Open client_config.php from the new www folder in a text editor (e.g., Notepad++).

    2. Change Schema Update Flag:

      • Locate line 22, which should read: 
        $update_schema = "False";
      • Change the value to "True" so it reads: 
        $update_schema = "True";
      • Save and close the file.

    9. Refresh the Front End to Apply Schema Updates

    1. Open the ReadyWorks Login Page:

      • In your web browser, navigate to the ReadyWorks URL.

    2. Trigger Schema Update:

      • Refresh the page.
      • The system will detect the schema update flag and begin updating the database schema.
        • Note: This process may take several minutes. Do not close the browser during the update.

    10. Log In and Confirm New Version

    1. Log Back into ReadyWorks:

      • Use your administrator credentials to log in.

    2. Verify the Version:

      • Navigate to Configuration > About or a similar section that displays version information.
      • Confirm that the displayed version matches the new version number.

    11. Recreate Database Views

    1. Remove Old Views Again:

      • Go to Configuration > Options.
      • Click on Remove Views.

    2. Create New Views:

      • Still in Options, click on Create Views.
        • Note: Use Chrome or Edge browsers for this step, as Internet Explorer may not be compatible.

    12. Verify System Functionality

    1. Check Custom Reports:

      • Navigate to the Reports section.
      • Ensure all custom reports are accessible and displaying data correctly.

    2. Confirm Environment Name and Logo:

      • Verify that the environment name and logo are correctly displayed on the dashboard and login page.

    3. Test Attachments:

      • Access any files or attachments within the system to confirm they are working.

    4. Review Cron Jobs:

      • Go to Admin Options > Cron Jobs.
      • Ensure scheduled tasks are listed and configured correctly.

    5. Check ETL Processes:

      • Navigate to the ETL module.
      • Verify that all ETL processes are online and functioning.

    13. Confirm Schema Update Flag Reset

    1. Reopen client_config.php:

      • Open the file from the www directory.

    2. Verify Schema Update Flag:

      • Ensure line 22 has automatically reverted to: 
        $update_schema = "False";
      • Note: The system resets this flag after successfully updating the schema to prevent unintended future updates.

    14. Send Latest Release Notes to Stakeholders

    • Download the Release Notes:

      • Access the latest Release Notes from [Placeholder for Release Notes Link].

    • Review Changes and Updates:

      • Familiarize yourself with new features, bug fixes, and any deprecated functionalities.

    • Distribute to Relevant Parties:

      • Share the Release Notes with your team, users, or stakeholders to inform them of the updates.
    Additional Information

    • Handling Export Dump Errors:

      • If you encountered errors during the database backup, refer to the specific troubleshooting guide or contact ReadyWorks support.

    • Post-Upgrade Monitoring:

      • Keep an eye on system performance and logs for any anomalies.
      • Encourage users to report any issues they experience.

    • Support:

      • For assistance, contact ReadyWorks support through your designated support channel.
    Conclusion

    You have successfully upgraded ReadyWorks to the latest version in your on-premises or self-hosted environment. Regularly updating your system ensures optimal performance, security, and access to new features that enhance your organization’s operational efficiency.

    Disclaimer: Always ensure you have adequate backups before performing system upgrades. This guide assumes that you have the necessary administrative privileges and familiarity with ReadyWorks system administration.

    See more