Settings Builder

Settings Builder is a tool available to Hosted and On-Premise SPF clients that allows you to generate a prototype of the SPF Registration JSON file and customizations within SPF and receive a successful Postback response using Symmetry's database of test (fake) employee data. The tool bypasses your interface and communicates with Symmetry Payroll Forms, which allows you to declaratively author your SPF Registration JSON file and troubleshoot.

Access Settings Builder

Settings Builder can be accessed at the following URL:
https://spf.symmetry.com/spf/utility/settings-builder?profile=yourProfileKey

Country Designation

Clients who license both US and Canadian SPF will be prompted to select the country designation for the specific testing scenario. Upon selecting the desired country, the correct settings builder tabs and test data will render.

There are several tabs within Settings Builder that step through the process of creating your SPF Registration JSON and submitting the data to SPF in a variety of ways. Symmetry clients can read an overview on the SPF Registration with our Client Support Center and review the complete list of elements within SPF and how to set them. In the sections below, we'll cover the features of each tab and the data points within.

U.S. implementation of Settings Builder

U.S. implementation of Settings Builder

Canadian implementation of Settings Builder

Canadian implementation of Settings Builder


Employee data

The Employee tab within Settings Builder is where relevant employee data, including federal values, are set. Additionally, you can also specify a pin the employee must set in order to complete his/her forms.

By default, Settings Builder draws from a list of test data and any data point can be changed.

📘

Canadian SPF

For clients who license both US and Canadian SPF, you will designate the employees country of residence within the Employee section in Settings Builder. This allows SPF to know what type of address data to display within the interface.

Employee

Corresponds to the "employee" element. Clients can see the breakdown of this object here.

Federal Values

For U.S. implementations only

Corresponds to the "federalValues" element and contains the JSON elements listed in the table below. While the "federalValues" element is optional, Symmetry highly encourages clients include federal values in their SPF Registration because several states use the Federal W-4 for their state withholding form and this data is used within certain flows.

PIN

Corresponds to the "pin" element and contains the JSON elements listed in the table below. This is an optional element.


Employer information

For U.S. implementations only

The Employer information tab captures data pertaining to the employer and the work location and this data is used to populate employer data on withholding forms.

Employer

Corresponds to the "employer" element and contains the JSON elements listed in the table below. This is a required element.

Employer Address

Corresponds to the "address" element and contains the JSON elements listed in the table below. This is a required element.


Resident address

The resident address tab within Settings Builder contains a list of test address data that are used for basic testing of the SPF Registration.

An employee can only have one primary resident address; therefore, only one address can be selected at a time within the resident address tab. The address selected in this tab will populate the "address" element within the "employee" element in the SPF Registration file. The "employee.address" element is required.


Work addresses tab

Similar to the resident address tab within Settings Builder, the work address(s) tab contains a list of test addresses that are used to test the SPF Registration.

An employee can have one or more work locations; therefore, one or more addresses can be selected at a time within the work address(es) tab. The address (or addresses) selected in this tab will populate the "workAddresses" element in the SPF Registration . The "workAddresses" element is optional and can contain multiple "address" elements.


Nexus and Lock in Letters

For US SPF Implementations Only

The nexus and lock in letters tab contains the configuration necessary to specify resident states where nexus exists and if an employee has an IRS, or local jurisdiction, lock in letter on file.


Application Settings

The application settings tab is where you can refine the behavior of SPF. Settings Builder draws from a preset list of settings, and allows you to set the interface (Guided Mode versus Choose Mode), define form delivery (for example, postback, emailback, and print only), change presentation property elements, update language of standard text/buttons, adjust webservice configuration, and more.


Submit (generated)

As you complete the inputs (for example, home and work addresses, employer information, and more) across the tabs within Settings Builder, the submit (generated) tab compiles the JSON SPF Registration necessary to successfully submit the data and display the correct forms to employees.

From the submit (generated) tab, you can submit the generated SPF Registration using the one-step registration or two-step registration process. Read more about the registration endpoints here.


Submit (custom)

The submit (custom) tab allows users to paste in your JSON SPF Registration file and submit to SPF using the one-step or two-step registration process. This "blank page" is most helpful when you're troubleshooting an existing SPF Registration file.


Translate XML to JSON

The final tab in Settings Builder is applicable to clients who onboarded to SPF prior to June 2023. Prior to the current JSON object model, SPF used XML across the application. This tab allows clients to paste in their Registration Context XML and Settings Builder will transform the file into JSON so you can successfully submit the data to SPF.


Jump to top