As someone who knows of a Black-Owned Business, or the owner of a Black-Owned Business
I want to Register a New Business but to also be guided as to whether the Business already exists, and be offered the ability to submit updates to the Business.
So I can avoid duplicating work or submitting multiple entries for the same Business.
Background
At React Rally we announced the newest version of our API, which is now public-facing:
All submissions are funneled into a new entry into the production AirTable with the field "Approved" set to false, such that someone on our staff might review the submission, make any necessary changes and Approve it. Once that's done, the API application automatically synchronizes all of the AirTable data into its database.
There currently is no easy way to signal to the user that a business's name may already exist in our database, and in some instances, a user may want to send-in multiple revisions. While the API does support the ability to search a business by name via the "search" parameter on /api/v1/businesses, it's also not being surfaced to end-users on the web site, so it's very difficult for them to tell whether a business already exists in our system.
New Possibilities
As part of the latest API release, we now have a dedicated AirTable base designed to ingest new listings or desired updates to existing listings. The system knows to make the appropriate correlations on "updates".
It is essentially a clone of the main AirTable Base, with a number of extra fields dedicated to the Editorial Lifecycle Process, including:
Editorial Status:
Received
Under Review
Approved
Rejected
Processed
Editorial Feedback
Operation:
INSERT
UPDATE
Request ID
tracks identifier of the request in the Developer Portal's "My Editorial Queue"
Business AirTable ID
For UPDATE operations only, the identifier of the record in the Main AirTable Base
Developer ID
The ID of the Developer Portal account which initiated the request
Business ID
For UPDATE operations only, the identifier for the Business on the API Application
When a Developer initiates a POST or a PATCH operation as specified in the API Doc, a new entry will be automatically added into this AirTable base, and the developer will be able to track the progress of their submission in their "My Editorial Queue" in the Portal.
Desired Solutions
With these new capabilities, we should be able to offer to the end-user a "guided experience" to their submission. There could be any number of ways to execute it from a UI standpoint but at its core we should consider:
Acceptance Criteria
[ ] Offering the ability to search for a business by name to see whether it exists.
[ ] If one or more businesses are found, show them to the user, and make them confirm that they indeed still want to add this new listing, or just stop there
[ ] Create a new business
[ ] Look for helpful Error Messages and Suggestions coming in the API responses when creating a new business
Possible API Error Messages coming-back from the API when Submitting a New Business
Exception: if there already is an editorial operation under review for a given business name
Exception: if one or more businesses exist with the same name, and the matching businesses are shown in HATEOAS style in a "links" property
Exception: on missing required minimal fields:
businessName
description
Exception on either isPhysicalLocation or isOnlineOnly not having been set
if isPhysicalLocation, Exception if missing any of these fields:
streetAddress, city, state, zip, latitude, longitude
if isOnlineOnly, Exception on missing site
Enhancing the Existing New Business Submission Form
Within the scope of this experience, we're not yet concerning ourselves with updating an existing business.
Create a new .env variable called EDITORIAL_API_KEY
if results do come-back, present the user with a list of results and try to link each business to their individual profile, by leveraging what @mbifulco is working on here
offer a [x] checkbox indicating "The business I'm entering is not among the above list"
if no results were found, of they clicked the above checkbox, then un-hide the rest of the existing form and let the user fill out the form as it current exists
To reduce our dependency on AirTable you might pull the list of categories from:
ownerEmail: if "I am the owner" was checked in the form
businessName
category
description
phone
either one of these fields set to true: isPhysicalLocation or isOnlineOnly , the other one set to false
isPhysicalLocation: true | false
isOnlineOnly: true | false
streetAddress
city
state
zip
serviceArea
site
the API will throw a descriptive error if the URL does not start with either https:// or http://
isAdult : true | false
inNeed: true | false
donationLink
the API will throw a descriptive error if the URL does not start with either https:// or http://
story
if a 409 response is returned, meaning "conflict", a JSON object will be returned with an Exception property whose value is a message friendly for the end-user. Consider rendering this message.
User Story
As someone who knows of a Black-Owned Business, or the owner of a Black-Owned Business I want to Register a New Business but to also be guided as to whether the Business already exists, and be offered the ability to submit updates to the Business. So I can avoid duplicating work or submitting multiple entries for the same Business.
Background
At React Rally we announced the newest version of our API, which is now public-facing:
https://api.rebuildblackbusiness.com/
It introduced two new endpoints:
Current Situation
We recently greatly improved our "New Business" "Registration" form which can be found off of the Listings Page: https://www.rebuildblackbusiness.com/businesses/
All submissions are funneled into a new entry into the production AirTable with the field "Approved" set to false, such that someone on our staff might review the submission, make any necessary changes and Approve it. Once that's done, the API application automatically synchronizes all of the AirTable data into its database.
This is our current Prod AirTable: https://airtable.com/tblz9khS4nskrHYMF/viwYkK4LF8DPuUaYO?blocks=hide
Current Situation: Some Drawbacks
There currently is no easy way to signal to the user that a business's name may already exist in our database, and in some instances, a user may want to send-in multiple revisions. While the API does support the ability to search a business by name via the "search" parameter on /api/v1/businesses, it's also not being surfaced to end-users on the web site, so it's very difficult for them to tell whether a business already exists in our system.
New Possibilities
As part of the latest API release, we now have a dedicated AirTable base designed to ingest new listings or desired updates to existing listings. The system knows to make the appropriate correlations on "updates".
Here is our Editorial Pipeline Base: https://airtable.com/tblXIjeThMr3lvs45/viwmTJ1MSxCyoIEge?blocks=hide
It is essentially a clone of the main AirTable Base, with a number of extra fields dedicated to the Editorial Lifecycle Process, including:
When a Developer initiates a POST or a PATCH operation as specified in the API Doc, a new entry will be automatically added into this AirTable base, and the developer will be able to track the progress of their submission in their "My Editorial Queue" in the Portal.
Desired Solutions
With these new capabilities, we should be able to offer to the end-user a "guided experience" to their submission. There could be any number of ways to execute it from a UI standpoint but at its core we should consider:
Acceptance Criteria
Possible API Error Messages coming-back from the API when Submitting a New Business
Enhancing the Existing New Business Submission Form
Within the scope of this experience, we're not yet concerning ourselves with updating an existing business.