Skip to main content
Symmetry Payroll Forms (SPF) On-Premise runs as a Java web application (spf.war) that you deploy in your own servlet container, such as Tomcat. You control the server, and you’re responsible for installation, deployment, and maintenance. This guide walks a new on-premise client through downloading the application, deploying it, configuring settings.json, and verifying a live installation. For a comparison of API, Hosted, and On-Premise delivery, see Implementation types.

​
Before you begin

You’ll need login credentials for the Download Center to complete this guide. If you don’t have them, contact your Symmetry Account Manager or reach out through the Client Support Center. Confirm your server meets the minimum specifications before you start:
  • Java 8+
  • A Servlet 3.1+ container, such as Tomcat 8.5+, Jetty 9.4+, or WildFly 10+
  • 4GB of memory and 1GB of disk space (SPF + Tomcat + Java + space for logs)
  • Courier, Courier-Bold, and ZapfDingbats fonts (or an appropriate substitute) installed on the server
See Updating Symmetry Payroll Forms for the full list of minimum and suggested system requirements, including font substitutes.

On-Premise Settings

Full reference for every element in your settings.json file.

Settings Builder

Prototype and troubleshoot your SPF Registration without touching your own application.

​
Step 1: Download the installation files

Log into the Download Center and download the following:

​
Step 2: Set up SPF_HOME

1

Unzip and rename

Unzip SPF_HOME example.zip and rename the folder from SPF_HOME example to SPF_HOME. Copy it to your chosen installation directory. Inside, you’ll find one subfolder, app-data, used for storing application settings and multistate library configuration files.
2

Set the system environment variable

Create a system environment variable named SPF_HOME and set its value to the path of the SPF_HOME folder.
3

Set folder permissions

The application requires read/write access to all folders and subfolders within SPF_HOME.

​
Step 3: Deploy the application

1

Place `spf.war` in your servlet container

Copy spf.war into the webapps folder of your servlet container.
Do not rename spf.war. The application has internal dependencies that rely on this exact filename.
2

Set minimum memory

Set the maximum available memory for your Java servlet container/JVM to at least 4GB. Symmetry suggests 16GB for production environments.
3

Start your servlet container

Start (or restart) your servlet container to deploy the application.
Using Tomcat 10? You’ll need an extra step, since Tomcat 10 switched to the Jakarta servlet implementation, which is incompatible with SPF. See Using Tomcat for the workaround.

​
Step 4: Configure settings.json

The settings.json file in your SPF_HOME directory controls SPF’s behavior: form modes, postback, address normalization, presentation, and more. Settings apply to all sessions after the application initializes, and Symmetry provides a default file in SPF_HOME example.zip. At minimum, review and configure:
  • config.formSubmissionMode: set to "POSTBACK" or "PRINT"
  • config.postback.target.url: required if formSubmissionMode is "POSTBACK"; the endpoint where SPF sends the completed form data
  • config.webservice.apiKey: your Symmetry-provided API key for the Symmetry Location Service (SLS)
  • config.webservice.enabled: set to true to enable address normalization and geocoding
See On-Premise Settings for the full reference of available elements, and the SPF Schema & Complete List of SPF Elements for every element available in the SPF Registration itself.
Any setting defined in settings.json can be overridden per session by passing the same JSON element with a different value in the SPF Registration.

​
Step 5: Configure SSL and cookies

If you are terminating SSL at a load balancer or proxy, or embedding SPF in an iframe, you’ll need additional server configuration before going live.

SameSite cookies

Required if embedding SPF in an iframe. Configure your servlet container to use secure, HTTP-only cookies.

SSL/TLS termination

Required if decrypting HTTPS at the load balancer level. Configure x-forwarded-* headers.
SPF does not recommend using iframes due to third-party cookie restrictions in Safari, iOS, and Chrome. See Third-party cookie restrictions and iframes before proceeding with an iframe implementation.

​
Step 6: Verify the installation

Once your server is running, test the installation by navigating to:
Select Test web service on the test page. A successful result confirms that the SPF_HOME environment variable is set, spf.war is found, and the application has read/write permissions. Once the test page passes, verify the full registration flow using Settings Builder at:
Settings Builder lets you generate a prototype SPF Registration, submit it to SPF, and receive a real Postback response, without needing to build your own integration first.

​
Step 7: Set up logging (optional)

SPF can write transaction logs to a directory of your choice. To enable logging, create a system environment variable named SPF_LOG_LOCATION and set its value to your desired log directory.
See Logging for full setup instructions, log naming conventions, and retention configuration.

​
Next steps

On-premise settings

Full reference for every settings.json element.

Core concepts overview

The model behind every SPF integration: forms, determination, and outputs.
More references: