Introduction
Purpose
Linemaster’s purpose for this customization was to reduce shipping errors that occur before product shipment. We often ran into problems where the customer’s address was never validated which then caused late shipments and frustration. Linemaster decided it would be best to find problems with addresses and validate them immediately before they become an issue at the end of the road.
What is the Customization?
The customization gives you the ability to validate addresses in Syteline through UPS’s web service. It consists of a global script that is designed to modular and can be used just about any form that has an address. By using the customization you will be able to know if the address is valid, invalid, or ambiguous. The user is also given the option to format the address to UPS standards.
It is important to know that validating addresses with UPS does not increase the speed of delivery. However, having a valid address will reduce errors which could prevent shipment delays.
How Does the Customization Work?
The core of the customization utilizes UPS’s API for street-level validation. By using the Mongoose Framework we are able to use VB.NET as global scripts that make HTTP requests to UPS’s API. The global script handles the request and the response from UPS to validate parameters that have been passed in by the Syteline form.
Limitations
Unfortunately UPS has some limitations with its API:
- UPS only validates addresses located in the United States and Puerto Rico.
- UPS does not validate suites/apartments/floors/etc.
Installation
>Download<
Requirements
- On-premise Syteline v9.01.01 or higher
- Microsoft SQL Server 2012 or higher
- Backup of forms being modified
- UPS Developer kit access
Program Components
IDOs
- LSC_UPSAddrValidations
Projects
- LSC
Tables & Views
- LSC_UPSAddrValidation_mst (table)
- LSC_UPSAddrValidation (view)
Global Scripts
- LSC_UPSAddressValidationForms
- LSC_AddressValidationParameters
Forms
- LSC_AddressValidationParameters
Installation Procedure
Before starting installation have your UPS developer’s kit username, password, and API key ready. You can view instructions in the link provided in the ‘Requirements’ section of this documentation. It is crucial that this procedure is followed in order.
- Close any instances of Syteline.
- In the SQL Scripts folder, run ‘TABLE_LSC_UPSAddrValidation_mst.sql’ then ‘VIEW_LSC_UPSAddrValidation.sql’ against your application database.
- Open ‘INSERT_LSC_UPSAddrValidation_mst.sql’ in a text editor. Replace ‘USERNAMEHERE’, ‘PASSWORDHERE’, and ‘APIKEYHERE’ with your actual credentials.
- Run the edited ‘INSERT_LSC_UPSAddrValidation_mst.sql’ against your application database.
- On your utility server run ‘App Metadata Transport’ and import ‘LSC_UPSAddrValidation.xml’ from your IDOs folder. Select the configuration and only import selected IDOs. There are no replication documents to import. Finish the wizard. You now have the IDO and the IDO’s project in your Syteline configuration.
- In the Forms folder, run ‘FGO_LSC_AddressValidationParameters.sql’ against your forms database.
- Run ‘LIC_LSC_AddressValidationParameters.sql’ against your application database. You now have the required forms in Syteline.
- Open Syteline and unload global objects (Ctrl+U)
- Enter design mode (Ctrl+E) and navigate Edit -> Script. Click the ‘New’ button, name your script ‘LSC_UPSAddressValidation’ with Visual Basic as the language. Copy the contents from ‘LSC_UPSAddressValidation.vb’ in your Global Script folder and replace all the text in the Script editor. Click OK > Done.
- Sign out of Syteline, save the script modifications.
Implementation Procedure
Now that we have the customization in Syteline we are now able add this customization on forms that have address fields. I recommend starting with ‘Customer Ship-Tos’ or ‘Customers’ form.
- Enter design mode on the desired form.
- Add a button onto the form. Name and style the button.
- Add an event handler to the button with the following settings:
- Type: Run Script
- Parameters: Add all text from the EventParameters.txt file in the Event Handlers folder.
- Click OK on the Event Handler Properties and Event Handlers windows.
- Regenerate the form by pressing Ctrl+G.
- Close the form and reopen.
- Test!
Event Handler Parameters Explained
The global script requires 15 parameters to be passed in. The text in the EventParameters.txt file will work on most vendor version forms, but if any component names differ than you will have to make adjustments. It is important to know that the parameter list is zero-based. Below is a table of the parameters:
Parameter # | Default Value | Value Meaning |
0 | C(Addr1_Edit) | Component value for the first address line |
1 | C(Addr2_Edit) | Component value for the second address line |
2 | C(Addr3_Edit) | Component value for the third address line |
3 | C(Addr4_Edit) | Component value for the fourth address line |
4 | C(CityEdit) | Component value for the city |
5 | C(StateEdit) | Component value for the state |
6 | C(ZipEdit) | Component value for the zip code |
7 | C(CountryEdit) | Component value for the country |
8 | Addr_1Edit | Component name for the first address line |
9 | Addr_2Edit | Component name for the second address line |
10 | Addr_3Edit | Component name for the third address line |
11 | Addr_4Edit | Component name for the fourth address line |
12 | CityEdit | Component name for the city field |
13 | StateEdit | Component name for the state field |
14 | ZipEdit | Component name for the zip code field |
Rollback Procedure
Follow this procedure to remove the customization from your Syteline environment.
- In Syteline, open the form ‘LSC_AddressValidationParameters’ in design mode. In the menu bar, Form > Definitions > Delete…
- Open the ‘IDOs’ form and check out the ‘LSC_UPSAddrValidations’ IDO. Delete the IDO and save.
- Open the ‘IDO Projects’ form, delete the ‘LSC’ project and save.
- Close Syteline.
- Delete the ‘LSC_UPSAddrValidation_mst’ table and ‘LSC_UPSAddrValidation’ view from your application database.
- Run the production form backups you have taken of the form you chose to customize against your forms database.
- Open Syteline and unload global objects (Ctrl+U)
Using the Customization
It is ultimately up to you where the customization is used. Once the customization is added to a form you simply click the validate button when there is an address record available on the form. You will receive a prompt indicating the validity of the address. If formatting is available you will prompt the option to. See the ‘Validation Prompt Examples’ section for more details on the prompts.
LSC_AddressValidationParameters form
This form is added from the customization. The purpose of this form is to allow you to change your UPS developer account’s username, password, and API key as needed. Once you save the record it will be stored in your table. After installation, you will be able to see the username, password, and API key that you set in ‘INSERT_LSC_UPSAddrValidation_mst.sql’.
This form is required by the global script as it extracts information from this form to send the request to UPS. The form has two additional fields named ‘XMLTemplate Header’ and ‘XMLTemplate Body’ which holds the barebones template for the UPS request. The global script populates the template’s XML tags with the parameter values on the form we are running the script from before sending to UPS.
Validation Prompt Examples
Valid Address Prompt
There are two types of valid address prompts: one with the option to format the text to UPS standards and other is a prompt to let you know the address is valid. You will only be given the option to format the address if the component fields are enabled or not read-only.
Invalid Address Prompt
If UPS is unable to validate an address you will receive a prompt. Addresses will not be formatted in invalid responses.
Ambiguous Address Prompt
If the address is ambiguous you will receive a prompt. This happens when the address may have been worded differently than what UPS was expecting. Although the address may be deliverable, it does not mean that the address is validated through UPS. The prompt will let you know which fields were not consistent with UPS’ database.
When this message appears you don’t necessarily have to do anything with it. All it is trying to tell you is that the following fields (in this case, the address line and Zip Code) are the only part of the address that came back questionable, according to UPS. The address will not be formatted in ambiguous responses.
Resources
UPS Standard Address Guideline – Useful for knowing the specification of the UPS standard on addresses.