Returning Form & Form Data

Form Submission Modes

There are three ways to return completed form data from SPF that is set using the "formSubmissionMode" in the "config" element within the SPF Registration file: Postback ("POSTBACK"), Emailback ("EMAIL"), and Print Only ("PRINT"). SPF also supports Postback and Emailback to be used in conjunction with each other ("POSTBACK_AND_EMAIL"). Depending on your business requirements and your environment configuration, select the option that best suites your needs. You can adjust these configurations within your SPF Registration file and leverage Settings Builder when testing your initial setup.

📘

Locality Agnostic

Both US and Canadian SPF support all three form submissions modes, making it seamless to implement Canadian SPF or US SPF within your implementations.

Postback

Postback returns completed form data in JSON format along with a Base64 encoded PDF of the signed form. SPF Hosted and On-Premise clients must have a server capable of receiving the JSON data in order to receive forms through Postback.

Below is an example SPF Registration for Postback.

   "formSubmissionMode": "POSTBACK", 
   "postback": { 
       "target": { 
       "url": "http://[yourTargetURL]", 
            "authentication": { 
                "authType": "BASIC", 
                "username": "TestUsername", 
                "password": "password" 
            } 
       }, 
   "encryption": { 
       "enabled": true 
   }, 
   "trustAllCertificates": true, 
   "timeout": "30", 
   "failureNotificationEmail": "[email protected]" 
   }

Emailback

Emailback allows completed forms to be emailed from SPF to a single designated email address for your Payroll/HR Departments. 

Below is an example SPF Registration for Email Back.

        "formSubmissionMode": "EMAIL",
        "email": {
            "encryptEmail": true,
            "signEmail": false,
            "toAddress": [],
            "ccAddress": [],
            "fromAddress": "[email protected]",
            "smtpSettings": {
                "username": "emailUsername",
                "host": "[email protected]",
                "port": "0",
                "password": "emailPassword"
            },
            "pgpConfig": {
                "publicKey": "encryptPublicKey",
                "publicKeyAlias": "encryptKeyAlias"
            }
        }

Postback and Emailback

Postback and Emailback can be used in conjunction with each other when the "formSubmissionMode" is set to "POSTBACK_AND_EMAIL". In order to utilize both, send in both a postback object and an email object.

Below is an example of using both the Postback and Emailback in the SPF Registration.

"formSubmissionMode": "POSTBACK_AND_EMAIL",
   "postback": { 
       "target": { 
       "url": "http://[yourTargetURL]", 
            "authentication": { 
                "authType": "BASIC", 
                "username": "TestUsername", 
                "password": "password" 
            } 
       }, 
   "encryption": { 
       "enabled": true 
   }, 
   "trustAllCertificates": true, 
   "timeout": "30", 
   "failureNotificationEmail": "[email protected]" 
   },
   "email": {
       "encryptEmail": true,
       "signEmail": false,
       "toAddress": [],
       "ccAddress": [],
       "fromAddress": "[email protected]",
       "smtpSettings": {
           "username": "emailUsername",
           "host": "[email protected]",
           "port": "0",
           "password": "emailPassword"
       },
       "pgpConfig": {
           "publicKey": "encryptPublicKey",
           "publicKeyAlias": "encryptKeyAlias"
       }
   }

Print Only

Print Only option allows completed forms to be printed by the employee for manual submission to your Payroll/HR Departments. The Print Only option uses the native printing capability of the employee's browser and operating system.

🚧

Standalone submission mode

The Print Only option cannot be used in conjunction with the Postback or Emailback options.

Below is an example Registration Context for Print Only. To enable Print Only mode, simply set the "formSubmissionMode" element to "PRINT". No print object is needed in JSON.

"formSubmissionMode": "PRINT"

Tax Parameters

Postback data is delivered upon submission of each form based on the Postback settings specified in the SPF Registration JSON file. Once received, you will need to parse the data, separating the Base64 encoded PDF for electronic storage from the tax parameter data in JSON format. The tax parameter data can be mapped to corresponding values in your Payroll/HR systems.

📘

Remitting Forms to Jurisdictions

When a jurisdiction requires that the completed employee forms be submitted, you will need to decode the Base64 PDF that's returned in the postback. There are several free online tools that decode Base64 files. While clients can choose to save the file as a PDF directly, we recommend you retain the Base64 encoded value within your system for auditing purposes.

The Tax Parameter section within the postback data returns your employee's tax parameter data gathered by the completion of the form that's necessary for withholding tax in the jurisdiction to which the withholding form applies. With every new release of SPF, Symmetry publishes the complete tax parameter catalogs for all forms, which can be found in the Symmetry Client Support Center.

Below is an example of tax parameter data returned for the U.S. Federal W-4 and Canadian Federal TD1 forms.

  "taxParameters" : {
    "taxParameters" : [ {
      "id" : "FED.dependentsAmt",
      "value" : "2000.00",
      "valueType" : "dollarAmount"
    }, {
      "id" : "FED.otherIncome",
      "value" : "0.00",
      "valueType" : "dollarAmount"
    }, {
      "id" : "FED.deductions",
      "value" : "0.00",
      "valueType" : "dollarAmount"
    }, 
    . . .                   
    ]
  }

"taxParameters" : {
    "taxParameters" : [ {
      "id" : "CA.hasMoreThanOnePayer",
      "value" : "false",
      "valueType" : "boolean"
    }, {
      "id" : "CA.hasTotalIncomeLessThanTotalClaim",
      "value" : "false",
      "valueType" : "boolean"
    }, 
    . . . 
    } ]
  }

👍

Complete List of Tax Parameters

For a complete listing of Tax Parameters (taxParameters) used by each form, please consult the Symmetry Payroll Forms Catalogs in the Client Support Center.