Being a big advocate of learning by doing, I decided to teach myself ASP.NET and ASP.NET Web Services by writing a simple application. This article walks through the process of designing a simple ASP.NET Web Service to address a business need.
A Disclaimer or Two
Disclaimer #1 - The information provided in this article and computer code has been gathered from publicly available sources, including the United States Social Security Administration Website. I make no warranties, express or implied, as to the accuracy of this information.
Disclaimer #2 - SSN information is highly confidential. It should not be transmitted electronically in a non-secure format. This application is for educational purposes only.
Using the code
To use the Web Service, just add a Web Reference to it in your Project. After you've added the Web reference, you can use it just like any other class:
Dim MyValidator As New SsnValid.SsnValidator
Dim MyResults As SsnValid.SsnResult = MyValidator.ValidateSsn(txtSsn.Text)
SsnValidator is the main class for the Web Service. It contains the public function
.ValidateSsn() which performs the actual validation of the format of your SSN. The results are returned as an
SsnResult structure. The
SsnResult structure has four values:
State which are explained in greater detail further down.
Step 1: Begin at the Beginning
My first step in designing this Web Service was to define the business problem. For this example, I decided to validate the structure of Social Security Numbers (SSN's). I began by researching the subject thoroughly on the Social Security Administration Website. The SSA provides quite a lot of information for employers to use in determining the validity of SSN's.
Step 2: Define the Rules
I used the information available on the SSA website to determine the rules for SSN validity. This information includes:
- All SSN's are exactly 9 digits long, and are in the format "xxx-xx-xxxx" or "xxxxxxxxx", where "x" is a numeric digit (0 through 9). In either form the first three digits are referred to as the "Area Number", the middle two digits are the "Group Code" and the final four digits are the "Serial Number".
- The first three digits ("Area Number") indicate the geographic location.
- The Area Number "666" (for obvious reasons) will never be used.
- The Area Number "000" will never be assigned.
- All numbers between "900" and "999" will not be assigned. Various government agencies have used Area Numbers "900" through "999" for internal management purposes; but for our purposes, these are considered invalid.
- The middle two digits ("Group Code") are dependent on the Area Number. This number indicates the highest group of numbers assigned to an area. The assignment of these numbers, however, is strange (see below). The "High" Group Codes are updated monthly and can be viewed here.
Group Codes are assigned according to the following pattern:
- For each Area Number, odd numbered Group Codes between 01 and 09 are assigned first.
- Next, even numbers between 10 and 98 are assigned.
- When the 98 Group is used up, we drop back and use up the even numbers between 02 and 08.
- Finally, we use up all the odd numbers between 11 and 99.
As an example, for Area Number "277" (an Ohio code), the High Group Code is currently "08". This means that all odd numbers between 01 and 09, all even numbers between 10 and 98, and all even numbers between 02 and 06 are used up. New SSN's assigned from this area will have the format: 277-08-xxxx.
- The last four digits ("Serial Number") of a SSN will never be "0000". It will always be a number between "0001" and "9999". Serial Numbers are assigned in sequential order from "0001" to "9999".
- There are some complete SSN's that will never be issued by the SSA. Some of these SSN's were used in media campaigns or otherwise misused. One example is the number "078-05-1120" which was used by the E.H. Ferree Company in an advertising campaign, circa 1938. Over 40,000 people have claimed this number as their own since then so the SSA invalidated it.
Step 3: Anticipated Results
Now we decide what information we want to return. Based on the information available via the SSA website, I've decided on four fields:
Code: A numeric return code which will be easy for an application to decipher.
Result: The return code is in human-readable format.
Comment: A comment field which can give more detail regarding the return code.
State: The State/Geographic location responsible for issuing the SSN.
Step 4: Implementation
The implementation of the Web Service is simple in nature, and the code is well-documented. I won’t go too deeply into it, other than to provide a simplified flowchart of the logic for the
I’ve created an Access Database called Ssn.mdb which must be located in the project’s \bin directory. It contains information updated from the SSA website, effective 2/1/2004.
Points of Interest
For me, the greatest point of interest was implementing the convoluted logic the government uses when assigning new SSN's. It made for some interesting development. Overall, I was pleasantly surprised at how easy it was to create a Web Service using ASP.NET. Originally I designed this Web Service to run against a SQL Server database, but downgraded it to Access to make this demonstration more portable. If there's enough interest, I can post the SQL Server/MSDE-capable version at a later date.
- Version 1.0