Install and Test the app Locally

After testing the Sample Quote Management app in online mode, you are now ready to set up a local environment.
This involves installing a server for the app’s frontend and another server for the proxy.
By doing so, you will start to gain a deeper understanding of the technical workings and interactions with the public API.

Prerequisites

• Install node.js

  For local development of the frontend application and the proxy, two web servers are required.
  One approach is to utilize Node.js, which offers a lightweight and efficient solution for such a setup.

  • The frontend application can be hosted on a Node.js server locally, accessible via http://127.0.0.1:4001/demo.html.
  • Similarly, the proxy can run on a separate Node.js server at http://127.0.0.1:3000.

    Later, when the proxy is deployed to a cloud service like Azure App Service, to continue testing and developing the frontend locally, modify proxyUrl in the frontend’s config.json to point to the cloud-hosted proxy URL.

  

  To install Node.js on a Windows system, follow these steps:

  1. Download Node.js Installer:
     • Go to the official Node.js download page.
     • Select the Windows Installer option.
       Choose either the 32-bit or 64-bit version based on your system.
  2. Run the Installer:
     • Once downloaded, run the .msi file to start the installation.
     • Follow the installation prompts, accepting the default settings unless you need custom configurations.
  3. Verify Installation:
     • After installation, open Command Prompt.
     • Type node -v and press Enter.

       This should display the installed version of Node.js, confirming the successful installation.

  4. Ready to Use:
     • Node.js is now installed on your Windows machine and ready for use.

• Obtain a client ID and a Subscription Key

  You must create an application within the environment.
  This will provide you with a Client ID and a Subscription Key (x-api-key), which are crucial for accessing Sage Active data.

  • Navigate to Public API / Application Key in the menu.
  • Follow the instructions at Application keys for detailed guidance.
    • You will need to choose the application type as Single Page Application.
    • Define the callback URL as the URL of your frontend.
    • Set the exact same URL for logout, as the app is Single Page Application.

  

Frontend Web Site

• Download the Frontend Web Site Zip File and Extract It

  1. Download the Zip File:
     The frontend website is stored in a zip file.
     Download the file from here: samplequotes.zip

  2. Extract the Zip File:
     After downloading, extract the contents of samplequotes.zip into a local directory.
     For example, you can extract it to C:\samplequotes.

• Running the Frontend Locally

  1. Prerequisites:
     • Node.js installed on your system.
  2. Install a Simple Server:
     • Use http-server, a simple zero-configuration command-line http server.
  3. Running the Server:
     • Navigate to your frontend’s root directory (e.g. c:\samplequotes)
     • open a Command Prompt.
     • Run the server:
     • This will serve your site at http://127.0.0.1:4001.
  4. Accessing the Frontend:
     • Open a browser and go to http://127.0.0.1:4001/demo.html.
     • Your frontend should now be accessible locally.

       Upon accessing the site, you might encounter an error message:
       Error fetching environments:TypeError: Failed to fetch.
       This is expected behavior at this stage because the frontend application is trying to communicate with the proxy server, which is not yet installed or launched.

     • Next, we will guide you through the process of locally installing and launching the proxy server to ensure the frontend can communicate with it successfully.
       This step is crucial for the full functionality of your frontend application.

Proxy Server

• Download the Proxy Server Zip File and Extract It

  1. Download the Zip File:
     The proxy server is stored in a zip file.
     Download the file from here: sampleproxy.zip

  2. Extract the Zip File:
     After downloading, extract the contents of sampleproxy.zip into a local directory.
     For example, you can extract it to C:\proxy.

• Setting Up the Local Proxy Server

  1. Installing Proxy Dependencies:
     • While Node.js is already installed, your proxy needs additional packages.
     • Open a Command Prompt in your proxy’s root directory (e.g. C:\proxy)
     • Install the necessary packages:
  2. Have a package.json:
     • Ensure you have package.json in your proxy’s root directory.
       If not, initialize your Node.js project with:
     • This will create package.json and package-lock.json, which are used to manage your project’s dependencies.
  3. Configure the .env file
     You’ll need to configure the .env file with the ClientID and Subscription Key obtained during your application creation.
     • In the .env file:
       • Place the Subscription Key value in the API_KEY_STAGE parameter.
       • Place the Client ID value in the CLIENTID_STAGE parameter.
       • Ensure that the ALLOWED_ORIGINS parameter correctly includes the domain of your frontend (e.g., http://127.0.0.1:4001).
       • For the local proxy configuration, leave the other parameters unchanged.
  4. Launching the Proxy Server:
     • Now, run your proxy server script with Node.js:
     • The script includes a port configuration to listen on port 3000 by default.

     • Once launched, the console will display: Server is running on port 3000.

       Attention

       If you need to modify the parameters in the .env file, such as in the case of a configuration error, it’s important to stop the proxy server and restart it.
       This ensures that the changes are properly applied and recognized by the system.

  5. Configuring the Frontend:
     • With the proxy server running, return to the frontend’s config.json.
     • If necessary change proxyUrl to http://127.0.0.1:3000 to direct requests to your local proxy.
     • This allows you to develop and test the frontend with the proxy in place.

Final steps

• Launching and Testing Your Application

  Now that the local proxy server is set up, it’s time to initiate the frontend application or refresh the page if it’s already running.

  • You should no longer encounter the Error fetching environments: TypeError: Failed to fetch.
    This indicates that the frontend can now successfully communicate with the proxy.
  • The application should prompt you to authenticate.
    If you’re already logged into Sage Active, it might automatically authenticate using the current Sage Active user’s cookie in your browser.
  • Additionally, the first time you access the app with the current user, a consent request will be required. Key concepts / User consents
  • Once authenticated and consent is granted, if the user is a valid Sage Active stage user, the app will function correctly, granting access to authorized organizations for the current user and offering all the functionalities identical to the online mode of the app.

  Happy usage!

  Enjoy exploring the functionalities and benefits your application offers.