Settings builder - Symmetry Docs

Settings Builder is a tool available to Hosted and On-Premise SPF clients that allows clients to generate a prototype of the SPF Registration and customizations within SPF and receive a successful Postback response. The tool bypasses your solution and communicates with Symmetry Payroll Forms, thus allowing you to troubleshoot any issues/configuration settings to determine the root cause.

Access settings builder

Settings Builder can be accessed via the following URL:

SPF Hosted: https://spf.symmetry.com/spf/utility/settings-builder?profile=[y0urPr0fileKey] - copy this URL into your browser and replace [y0urPr0fileKey] with your profile key.
SPF On-Premise: https://[yourservername]:[yourserverport]/spf/utility/settings-builder - copy this URL into your browser and replace [yourservername] and [yourserverport] with your server name and port.

Most users of Symmetry Payroll Forms send the traffic through port 8080 for HTTPS. There are several tabs within Settings Builder that step through the process of creating your SPF Registration and submitting the data to SPF in a variety of ways. Refer to the SPF Registration Overview for the full list of elements within SPF and how to set them.

Employee tab

The Employee tab within Settings Builder is where relevant Employee Information is set. By default, Settings Builder draws from a list of fake employee data for testing and any element can be changed. The Employee tab is divided into the sections below that correspond with JSON elements that are part of the SPF Registration and contain data used by Symmetry Payroll Forms to populate employee data on withholding forms. Employee section Corresponds to the "employee" JSON element and contains the JSON elements listed in the following table:

Element	Data type & enforcement	Description
`"firstName"`	String. Required.	Employee’s First Name. Length must be greater than 0.
`"middleInitial"`	String. Optional.	Employee’s Middle Initial.
`"lastName"`	String. Required.	Employee’s Last Name. Length must be greater than 0.
`"socialSecurityNumber"`	String. Required.	Employee’s Social Security Number. Must be exactly 9 digits. All non-numeric characters will be automatically removed before validation (for example, 123-45-6789 will be validated as 123456789). For SPF U.S. only.
`"socialInsuranceNumber"`	String. Required.	For Canadian SPF only.
`"socialInsuranceNumberExpiryDate"`	String. Required.	For Canadian SPF only.
`"uniqueIdentifier"`	String. Required.	Unique identifier for the employee. Most frequently used to house an employee’s ID Number but, can be anything (e.g. an HRIS record reference). Length must be greater than 0.
`"country"`	String. Optional.	Employee’s Country of Residence

Federal Values section For SPF U.S. implementations only Corresponds to the "federalValues" JSON element and contains the JSON elements listed in the table below. The "federalValues" JSON element is optional, but 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. This currently applies to the CO101, NM101, ND104, and UT101 state withholding forms.

Element	Type and Enforcement	Description
`"filingStatus"`	enum. Required.	Employee’s federal filing status, required whenever `federalValues` is provided. The allowed value depends on `isExempt` and `isNonResidentAlien`: must be `NOT_APPLICABLE` if `isExempt` is true, must be `SINGLE_OR_MARRIED_FILING_SEPARATELY` if `isNonResidentAlien` is true, otherwise any value other than `NOT_APPLICABLE` (`SINGLE_OR_MARRIED_FILING_SEPARATELY`, `MARRIED_FILING_JOINTLY`, or `HEAD_OF_HOUSEHOLD`).
`"isExempt"`	Boolean. Required.	Flag denoting if the employee is exempt from federal withholding. Nonresident aliens may not claim exempt.
`"additionalWithholding"`	Integer. Optional.	Additional dollar amount the employee wishes to be applied to their federal withholding. Must be greater than or equal to 0 if `federalValues.isExempt` is false. Will convert to 0 if `federalValues.isExempt` is true.
`"isNonResidentAlien"`	Boolean. Optional.	Whether the employee is a Nonresident Alien working within the United States or its Territories. Must be false if `federalValues.isExempt` is true.

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

Element	Type and Enforcement	Description
`"pinMessage"`	String. Optional.	Message displayed to user when entering their PIN
`"pinvalue"`	String. Optional.	PIN number employee must enter prior to submitting a completed form.

Employer information tab

The Employer tab within Settings Builder is where relevant Employer information is set. By default and similar to the Employee tab, Settings Builder draws from a list of fake employer/company data for testing and any element can be changed. The Employer Information Tab contains data used by Symmetry Payroll Forms to populate employer data on withholding forms where they are relevant. SPF U.S. Employer section Corresponds to the "employer" JSON element and contains the JSON elements listed in the table below. This is a required element.

Element	Type and Enforcement	Description
`"name"`	String. Optional.	Company name of employer.
`"federalEIN"`	String. Optional.	Employer’s Federal Employer Information Number. Must be exactly 9 digits.
`"contactPerson"`	String. Optional.	The name of the person within the company whom the taxing authority may contact in the event of questions. Value is populated on some forms.
`"telephoneNumber"`	String. Optional.	The phone number of the company’s contact person (`contactPerson`). Must be null, empty, or exactly 10 digits. All non-numeric characters will be automatically removed before validation (for example, “555-555-5555” will be validated as “5555555555”).
`"firstDateOfEmployment"`	String. Optional.	The employee’s first date of employment

SPF Canada Employer section Corresponds to the "employer" JSON element and contains the JSON elements listed in the table below. This element is optional for SPF Canada.

Element	Type and Enforcement	Description
`"name"`	String. Optional.	Company name of employer.
`"federalEIN"`	String. Optional.	Employer’s Federal Employer Information Number. Must be exactly 9 digits.
`"contactPerson"`	String. Optional.	The name of the person within the company whom the taxing authority may contact in the event of questions. Value is populated on some forms.
`"telephoneNumber"`	String. Optional.	The phone number of the company’s contact person (`contactPerson`). Must be null, empty, or exactly 10 digits. All non-numeric characters will be automatically removed before validation (for example, “555-555-5555” will be validated as “5555555555”).
`"faxNumber"`	String. Optional.	The fax number for the employer or contact person.
`"firstDateOfEmployment"`	String. Optional.	The employee’s first date of employment

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

Element	Type and Enforcement	Description
`"streetAddress1"`	String. Required.	Civic number and street name of the employee’s physical resident address. Cannot be null or empty.
`"streetAddress2"`	String. Optional.	Apartment, floor, unit number, or other address designation that is part of the employee’s physical home address.
`"city"`	String. Required.	City of the employee’s physical resident address. Cannot be null or empty.
`"state"`	enum	State or territory of the employee’s physical resident address. For SPF U.S. only.
`"zipCode"`	String.	ZIP code of the employee’s physical resident address. Must be exactly 5 or exactly 9 digits. All non-numeric characters will be automatically removed before validation (for example, 85260-2662 will be validated as 852602662).

Resident address tab

The Resident Address tab within Settings Builder contains a list of addresses that can be found in the SPF_HOME\app-data\db folder in a file called addresses.json. These preconfigured addresses may be used for basic testing of the SPF Registration to set an employee’s resident and work location(s). 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. The "employee.address" element is required.

Work addresses tab

Similar to the Resident Address tab within Settings Builder, the Work Addresses tab contains a list of addresses that can be found in the SPF_HOME\app-data\db folder in a file called addresses.json. These preconfigured addresses may be used for basic testing of the SPF Registration to set an employee’s work location(s). One or more addresses can be selected at a time within the Work Addresses 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 tab

For SPF U.S. 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. At times, the Internal Revenue Service (IRS) may give an employer an order to withhold taxes at a minimum rate. The "lockInLetters" element provides a mechanism to prevent employees from changing certain state or federal withholding forms. Use "lockInLetters" to provide a single state abbreviation or a comma-separated list of states where the employee has a Lock in Letter on file. For a Federal lock-in letter, use the value "FEDERAL". Lock in Letters do not apply to the Canadian implementation of SPF.

Element	Type and Enforcement	Description
`"nexus"`	array	Defines where a company has a business presence and therefore which states’ withholding forms should be considered. For SPF U.S. only.
`"lockInLetters"`	array	Specifies any jurisdictions where the employee has a Lock in Letter on file with the IRS. For SPF U.S. only.

Application settings tab

The Application Settings tab within Settings Builder defines how Symmetry Payroll Forms itself functions. By default, Settings Builder draws from a preset list of settings, as well as the contents of your settings.json file (refer to the settings.json overview for additional information). Within the Application Settings tab, clients can define their Symmetry Location Service (SLS) call, Postback information, re-order the Federal W-4 survey options, adjust nexus, as well as change the look and feel of the application and how forms are displayed and returned.

Submit (generated) tab

The Submit (generated) tab within Settings Builder automatically generates the SPF Registration based on the data you’ve entered/selected from the Employee, Employer Information, Resident Address, Nexus & Lock In Letters, Work Addresses and Application Setting tabs. Adjusting the inputs on these tabs changes the data defined in the SPF Registration, which is then submitted and SPF determines the forms to be returned. From the Submit (generated) tab, clients can submit the generated SPF Registration to SPF in one of three ways:

Submit: generates the URL with valid token that is used for iFrame Mode.
Submit One Step: directs client to the Employee Withholding Resource Center where Guide Mode and Choose Mode options are available.
Submit to Helper: directs client to the Helper pages that display the submitted employee and employer data prior to navigating to the Employee Withholding Resource Center.

Submit (custom) tab

The Submit (custom) tab within Settings Builder is where clients can write and populate your own SPF Registration. This is a useful tool to help troubleshoot issues within your solution and allows clients to copy and paste in an SPF Registration file and submit the data to SPF. Data can be submitted to SPF in the same three ways from the Submit (custom) tab as the Submit (generated) tab above.

​Access settings builder

​Employee tab

​Employer information tab

​Resident address tab

​Work addresses tab

​Nexus and lock in letters tab

​Application settings tab

​Submit (generated) tab

​Submit (custom) tab