Aller au contenu principal

Webforms server setup

Overview​

This guide walks you through setting up the mXrap Webforms Server, which enables field teams to submit inspection reports and data collected offline through a web-based interface. The setup process covers basic installation, testing, and optional advanced configuration to run the server as a Windows service.

Prerequisites​

Before starting, ensure you have:

  • Access to the mXrap root folder (typically located on a network share)
  • Windows machine with appropriate permissions to install software and manage services
  • Administrator privileges on the machine where you're installing the server
  • Network connectivity to the mXrap root folder location

Basic Setup​

Step 1: Download and Install mXrap Webforms Server​

  1. Download the latest mXrap-Webforms-latest.msi installer file from Downloads

  2. Run the .msi file to begin installation

  1. Choose your installation scope:
    • Current user only (default): Installs to %LocalAppData%
    • All users: Recommended if you plan to run as a service - installs to Program Files

Step 2: Ensure Root Folder Access​

Verify that you have access to the mXrap root folder. This folder typically resides on a network share and contains all the webforms data and configuration.

Step 3: Run the mXrap Webforms Server Program​

  1. Open the Start Menu and search for mXrap Webforms Server

  1. Click to launch the program

  2. The program window should open, initially showing an empty server list

Step 4: Add Root Folder to Server List​

  1. Click Settings in the menu bar

  2. Select Edit Common Settings

  1. Under the Add Root to Server List section, click Choose from Disk

  2. Navigate to and select your mXrap root folder

  3. Click OK to confirm

Step 5: Configure Custom Hostname (Optional)​

If your site uses a custom hostname:

  1. Go to Settings → Edit Common Settings

  2. In the Custom Hostname section, click Set Hostname

  1. Enter your hostname and password settings (contact support if you need these details)

  2. For the CIDR pattern, you can typically use Auto-Detect to automatically identify the correct network interface

Step 6: Verify Server Status​

  1. Close the settings dialog if it's still open

  2. You should now see your root folder listed on the main screen

  3. The server will start up (this may take a moment) and the status will change to Running

  4. Once running, you'll see URLs for each network interface on your machine

  1. Click one of the URLs to open it in your browser and verify:
    • The server is running correctly
    • The root folder is properly selected
    • The webforms apps are installed and visible
Example of a sucessfully running webform server
Example of a sucessfully running webform server

Testing​

Step 7: Test the Inspections Webform​

  1. Click on the Inspections link from the webforms app list

  2. If a popup appears indicating a new version is available, click OK to update

  3. The inspections webform should load successfully

Example Inspections form ready for input
Example Inspections form ready for input

Step 8: Submit a Test Report​

To verify that report submission is working:

  1. In the Data Collected By field, enter: test

  2. In the Report Title/Summary field, enter: test

  3. Scroll down to the bottom of the form

  4. Click Close Report Details

  5. If a popup warns about mandatory fields, click Yes to proceed

  6. If a second screen appears with a Submit Report button, click it

  7. The webpage should return to the original screen and show a message confirming successful submission.

Sucessfully saved report
Sucessfully saved report
  1. Verify that the status shows "0 reports pending" in the top-left corner

Running as a Service​

This section is optional and recommended only if you want the webforms server to:

  • Run on a dedicated server
  • Start automatically when the machine boots
  • Run continuously without user login
  • Be managed through Windows Services

Prerequisites for Service Setup​

Before proceeding with service setup, ensure:

  • The basic setup is working correctly
  • You have administrator privileges on the machine
  • You understand Windows Services management
  • The mXrap Webforms Server is currently not running (close it before proceeding)

Step 1: Download WinSW​

WinSW is a wrapper program that allows running other applications as Windows services.

  1. Download WinSW from: https://github.com/winsw/winsw/releases/latest

  2. Choose the appropriate version:

    • WinSW.x64.exe - For 64-bit Windows (recommended)
    • .NET variants - Smaller, but require .NET runtime installed

  3. Create a directory for the service files (e.g., D:\webforms-service\)

  4. Place the downloaded executable in this directory

  5. Rename it to: webforms-sw.exe

Step 2: Configure Service Wrapper​

  1. Download the Webforms Service Wrapper Configuration file

  2. Extract it into the same directory as webforms-sw.exe

  3. You should now have: D:\webforms-service\webforms-sw.xml

Step 3: Update Configuration File​

The webforms-sw.xml file contains default values that need to be customised for your site:

  1. Open the mXrap Webforms Server program
  2. Click Show server messages to enable message logging
  3. Scroll to the top of the message window and find: ******** Starting Program ********
  4. The lines following Command line used: show the values you need
  5. Edit webforms-sw.xml and update these entries:
EntryData needed
<executable>Path to mXrap Webforms Server executable (if installed for current user only)
-Dapp.ssl.key.passwordSSL key password
-Dapp.server.locationRoot folder server location
-Dapp.json.locationJSON data location
-Dapp.files.locationFiles location
-Dapp.register.custom.hostname.prefixCustom hostname prefix (if applicable)
-Dapp.register.custom.hostname.server.saltHostname salt (if applicable)
-Dapp.register.custom.hostname.cidrCIDR pattern (if applicable)
-Dserver.ssl.key-storeSSL keystore path (if installed for current user only)
<workingdirectory>Should be the directory containing webforms-sw.exe

Step 4: Verify Path Formats​

If your root folder is on a network share, ensure paths are in the correct format:

  • app.server.location: Use file:// format

    • Example: file://server/root_folder/webforms/instance/server/

  • app.json.location and app.files.location: Use UNC paths

    • Example: \\server\root_folder\webforms\instance\json\

Step 5: Install the Service​

  1. Important: Ensure the mXrap Webforms Server program is not running
  2. Open Command Prompt and navigate to the directory containing webforms-sw.exe
  3. Run the installation command: 
    webforms-sw.exe install
  4. The service should now be installed and visible in Windows Services
  5. You can manage it through:
    • Windows Services app - Right-click to start/stop
    • Command line: 
      webforms-sw.exe start
      webforms-sw.exe stop

Log Files​

Log files are created in the same directory as webforms-sw.exe:

  • webforms-sw.out.log - Standard output
  • webforms-sw.err.log - Error messages
  • webforms-sw.wrapper.log - Wrapper-specific messages

Step 6: Configure Service Credentials​

If the root folder is on a network share requiring authentication:

  1. Log in as the local user account that will run the service
  2. Open Credential Manager
  3. Click Add a Windows Credential
  4. Enter:
    • Internet or network address: Server address
    • Username: Network credentials
    • Password: Network password
  5. Click OK
  6. Open Windows Services (services.msc)
  7. Right-click on mXrap Webforms Server → Properties
  8. Go to the Log On tab
  9. Select This account and enter the service user credentials
  10. Click Apply → OK
  11. If the service is running, stop it and restart it for changes to take effect

Step 7: Verify Service Installation​

  1. Check the log files in the service directory:
    • Look in webforms-sw.out.log for: "OK, I'm ready now!"
    • Check webforms-sw.err.log for any error messages
  2. Open the inspections webform in your browser
  3. Verify the status shows:
    • "submit now" - Ready to submit reports
    • "READY FOR OFFLINE" - Offline capability enabled

Troubleshooting​

Webpage is Inaccessible​

Symptoms: Cannot access the webforms server URL in your browser

Diagnostic Steps:

  1. Verify the mXrap Webforms Server program is running (check the main window)
  2. Check network connectivity to the machine hosting the server
  3. Verify the root folder path is correctly configured in the server settings
  4. Check Windows Firewall settings - the server may need port access
  5. Try accessing from a different machine on the network
  6. Check the server messages window for any error messages

Resolution: If the issue persists, please email and ask to schedule a meeting so we can diagnose the issue.

Web Apps Not Visible​

Symptoms: The webforms app list is empty or shows no applications

Causes: The root folder doesn't have webforms apps installed

Resolution Steps:

  1. Perform a default backup of the root folder
  2. email and request the desired apps to be added to your root folder
  3. Provide details about which apps you need (e.g., Inspections)

Inspections Webform Loading Issues​

Symptoms: The inspections webform doesn't load or displays errors

Diagnostic Steps:

  1. Verify you're using a supported browser:
    • Chrome (latest version)
    • Firefox (latest version)
    • Edge (Chromium-based, version 79+)
  2. Clear your browser cache and cookies
  3. Try accessing from a different browser
  4. Check the browser console for JavaScript errors (F12 → Console tab)
  5. Verify the server is showing "Running" status

Resolution: If the issue persists, please email and ask to schedule a meeting so we can diagnose the issue.

Test Report Submission Failed​

Symptoms: Test report doesn't submit or returns an error

Diagnostic Steps:

  1. Verify the form is fully loaded before submitting
  2. Check that all mandatory fields are completed
  3. Verify network connectivity to the server
  4. Check the browser console for error messages
  5. Try submitting from a different machine
  6. Verify the root folder has write permissions

Resolution: If the issue persists, please email and ask to schedule a meeting so we can diagnose the issue.

Service Installation Issues​

Symptoms: Service fails to install or start, or shows errors

Diagnostic Steps:

  1. Check webforms-sw.err.log for specific error messages
  2. Check webforms-sw.wrapper.log for wrapper-related errors
  3. Verify the mXrap Webforms Server program is not running
  4. Verify the XML configuration file has correct paths
  5. Ensure the service user has access to the root folder
  6. Check that the .exe and .xml files have matching names
  7. Verify the working directory path is correct

Common Issues​

Port already in use​

Another instance of the server is running. Stop the mXrap Webforms Server program.

Path not found​

Verify all paths in the XML file are correct and accessible

Access denied​

Ensure the service user has credentials stored in Credential Manager for network shares

Network path issues​

For network shares, use file:// and UNC paths as specified in Step 4

If the issue persists, send the following files to ):

  • webforms-sw.err.log
  • webforms-sw.wrapper.log
  • webforms-sw.xml (configuration file)

Next Steps​

Once your webforms server is successfully set up and tested:

  1. Communicate access details to your field teams with the webforms server URL
  2. Train users on how to access and use the inspections webform
  3. Monitor submissions regularly to ensure reports are being submitted successfully
  4. Set up backups for your root folder to protect webforms data
  5. Plan for maintenance - schedule regular updates and backups
Dernière mise à jour le