Business Rules

This section is for documenting business rules that are defined by the city and SME. This section can be further organized into subpages as more information is added to it.

Short Form Application

Geocoding and Boundary Matching

The geocoding and boundary matching process is a two-step process that is applied to some addresses entered into short form applications. During the process of a user filling out a short form application, the Angular app will put some addresses the user enters through the geocoding and boundary matching process. The actual geocoding and boundary matching is done in the Rails app. It returns the resultant data to the Angular app. The data contains address geocoding information, and information on whether the address matches - i.e., falls within - a given geographical boundary for the purposes of qualifying for certain preferences. The Angular app then adds both the geocoding and boundary matching information to the application.

Note on the purpose of geocoding: Although the geocoding information is only used as a means to an end within in the DAHLIA app, in order to do the boundary matching process, that geocoding data is valuable in and of itself to the city. That's why we include it on the short form application data that is sent to and saved in Salesforce. Here's an unofficial comment from the city briefly describing some things that they use geocoding data for:

Yes, we do use the geocoding data for other purposes, most generally determine other geographic data (neighborhood, supervisor district) used for reporting in our CAPER, Annual Report, request to the BoS, etc. Also, the xy coordates are also retained as a check/validation of the NRHP process, as they can be used to review if someone eligibility status was determined correctly if necessary.

In the Rails app

Rules for entire process:

• Primary applicant addresses and household member addresses should be put through the geocoding and boundary matching process.
• Alternate contact addresses should not be put through the geocoding and boundary matching process at all.
• If any kind of error occurs during the geocoding and boundary matching process and the actual result of the boundary matching process cannot be determined, the process should return a nil value for the boundary_match.

Rules for step #1, geocoding:

• All primary applicant addresses and household member addresses should go through the process, which is being geocoded.
• If an address cannot be geocoded, e.g. because it is blank or invalid, that will be indicated by the geocoder returning an empty list of candidates. An address that cannot be geocoded should not go through the boundary matching process. Its boundary_match value should be set to nil.

Rules for step #2, boundary matching:

• If the application listing has neither the ADHP preference nor the NRHP preference, then the address should not be put through the boundary matching process after it is geocoded. Its boundary_match value should be set to nil.
• If the listing has the ADHP preference, it should be put through the boundary matching process. The boundary matching process should use the string ADHP as the project ID. The boundary match value should be either true if the address is a match or false if the address is not a match.
• If the listing has the NRHP preference, it should be put through the boundary matching process. If it does not have the ADHP preference as well, then the boundary matching process should use the string ADHP as the project ID. The boundary match value should be either true if the address is a match or false if the address is not a match.
• A production listing is supposed to never have both the ADHP and the NRHP preference, so there is no business rule around how to boundary match for such a listing. In practice, given the current implementation, if a listing ever happened to have both preferences, the implementation would prioritize the ADHP preference and use the string ADHP as the project ID in boundary matching. The NRHP preference and the listing project ID would effectively be ignored and not used in boundary matching.
• If an error occurs during the boundary matching process, it should return nil as the match value.

In the Angular app

Map for how to set the application member's preferenceAddressMatch value based on the boundary_match value returned by the Rails app:

• boundary_match: true: set preferenceAddressMatch to "Matched"
• boundary_match: false: set preferenceAddressMatch to "Not Matched"
• boundary_match: null: set preferenceAddressMatch to ""
• Rails app returns error response: set preferenceAddressMatch to ""