Onboard and validate a broker network from a spreadsheet

When you add brokers to a valuation or listing network, each one needs to be checked before you send them work: their contact details confirmed, their coverage area reviewed, and their paperwork on file. Done by email and spreadsheet, that check is slow and hard to audit.

In this walkthrough you build a repeatable intake. You import a spreadsheet of brokers and the areas they cover. For each broker, QBO makes sure they have a login with the broker role, emails them, and puts a Broker Validation task in their worklist. When your team approves the completed task, QBO labels the broker Validated, and from then on they’re eligible for work.

Who it’s for

Power users who manage vendor and broker networks. Processors and network managers then work the validation tasks and oversee them from worklist dashboards.

Prerequisites

• Permission to create message, task, workflow, and import file templates.
• A Broker system role, with the permissions brokers need to see and complete their own tasks.
• A spreadsheet or CSV of brokers with at least these columns: Name, Email, Coverage, City, PostalCode, County, State, Radius, Latitude, and Longitude. FirstName and LastName are optional.
• The fields you want brokers to complete during validation (for example licensing, insurance, and service areas), so you can lay out the task.

Building blocks used

• Contacts: brokers, their contact details, and labels
• Security: user accounts, roles, and partner access for brokers
• Messaging: the notification email
• Forms: the validation task, its layout, and its review states
• Workflow: the steps that run for each broker
• Imports: loading brokers and coverage from a spreadsheet
• Worklists: where brokers and processors pick up the tasks

Steps

1. Create the notification message

Open Templates > Messages and add an HTML message template:

Setting	Value
Name	Broker Validation
QBO Module	Broker
Subject	Broker Validation Request
Body HTML	Please sign in to <a href="{BaseUrl}">{BaseUrl}</a> and open the new "Broker Validation" item in your worklist.

{BaseUrl} is replaced with your site’s address when the message is sent.

2. Create the validation task

Open Templates > Tasks and add a task template:

Setting	Value
Task Template	Broker Validation
Applies To	Broker
Description	Validate a broker for solicitations.

Then, from the template’s summary page:

• Use the GUI Designer to lay out the fields brokers complete. See The GUI designer.
• Use the State Diagram to route the task: the broker submits it for review, and a reviewer either approves it or sends it back for corrections. See State diagram.

3. Create the workflow

Open Templates > Workflows and create a workflow template named Broker Validation that applies to Broker. Add these steps:

Workflow step	Step type	Data Source	Action or template	Depends on
Ensure User Account	Advanced step	Operation: Broker/Search?BrokerID={//BrokerID[1]}	Person/Save?Person={Email}&ContactID={ContactID}&Active=1
Ensure Role	Advanced step	Operation: Person/Search?Person={//Email[1]}	Person/RegisterBroker?PersonID={PersonID}&BrokerID={//BrokerID[1]}	Ensure User Account
Send Message	Send a message		Template: Broker Validation	Ensure Role
Broker Validation Task	Add a task		Template: Broker Validation	Ensure Role
Label Broker	Advanced step	Broker Summary	Broker/CollectionMemberInsert?ID={//BrokerID[1]}&Collection=Validated	Broker Validation Task

What each step does:

• Ensure User Account looks up the broker and creates an active user whose login is the broker’s email, tied to the broker’s contact record.
• Ensure Role finds that user and registers them as the broker’s user: it grants them access to the broker record, and gives them the Broker role if they don’t already have it.
• Send Message and Broker Validation Task run side by side once the account is ready, so the email arrives with the task already waiting.
• Label Broker runs only when the task is complete, and adds the broker to the Validated label. QBO creates the label the first time it’s used.

Tip

Use the Validated label wherever you choose brokers for work, such as an assignment matrix or a broker search filter, so unvalidated brokers are never offered.

4. Create the import file template

Open Templates > Import Files and create a template named Broker Validation, with Applies To set to Broker and Import Engine set to BatchReader. Add these file mappings:

Source	Destination	Translation	Required	Text	Purpose
Name	Broker		Yes	No	Broker name
FirstName	FirstName		No	No	First name
LastName	LastName		No	No	Last name
Email	Email		Yes	No	Email, which becomes the login
SubscriberID	SubscriberID	Broker-Email-{Email}	No	No	Unique key, so re-importing a broker updates them instead of duplicating them
Broker Validation	Decisions_0_Template		No	Yes	Starts the Broker Validation workflow on each broker
Broker Coverage	Geography_0_Geography		No	Yes	Name of the coverage area
Coverage	Geography_0_GeographyType		Yes	No	City, PostalCode, County, State, or Driving Distance
City	Geography_0_City		Yes	No	Covered city, for City coverage
PostalCode	Geography_0_PostalCode		Yes	No	Covered ZIP Code, for PostalCode coverage
County	Geography_0_County		Yes	No	Covered county, for County coverage
State	Geography_0_State		Yes	No	State, for City, County, or State coverage
Radius	Geography_0_Radius		Yes	No	Miles, for Driving Distance coverage
Latitude	Geography_0_Latitude		Yes	No	Center point, for Driving Distance coverage
Longitude	Geography_0_Longitude		Yes	No	Center point, for Driving Distance coverage
Geography_0_SubscriberID	Geography_0_SubscriberID	Broker-Email-{Email}-{Geography_0_Geography}-{Geography_0_GeographyType}-{Geography_0_City}-{Geography_0_PostalCode}-{Geography_0_County}-{Geography_0_State}-{Geography_0_Radius}-{Geography_0_Latitude}-{Geography_0_Longitude}	No	No	Unique key for each coverage area

A Text mapping of Yes means the source is a fixed value rather than a spreadsheet column. Destinations such as Decisions_0_Template and Geography_0_City create a child record (a workflow, a coverage area) along with the broker. See Mappings.

Caution

Coverage mappings create coverage areas as children of the broker, so the coverage child collection has to be enabled for brokers in your module configuration. Check with your administrator before relying on these destinations.

5. Import brokers

Upload the spreadsheet as an import file using the Broker Validation template. Each row creates or updates a broker, adds the coverage area, and starts the workflow.

To give a broker several coverage areas, repeat their row with different Coverage, City, PostalCode, County, State, Radius, Latitude, and Longitude values. The subscriber IDs keep it to one broker with many coverage areas.

Caution

When a broker appears on more than one row, run the import on a single-threaded queue. Rows processed in parallel can each fail to find the broker and create it twice. Set the template’s Async and Queue settings to a queue that processes one item at a time. See Template settings.

6. Work and oversee the tasks

• Brokers sign in, open the task from their worklist, complete it, and submit it for review.
• Processors review submitted tasks from their worklists, approve them, or send them back for corrections.
• Managers watch the worklist dashboards for tasks that are aging or keep bouncing back, and reassign work as needed.

The result

A new broker network goes from spreadsheet to validated in one pass. Every broker has a login with the broker role and access to their own broker record and tasks. Every approval is a completed task with its history, and Validated is a label you can filter on anywhere brokers are chosen for work. Importing the same spreadsheet again updates brokers and coverage instead of duplicating them.

Next steps

• Record broker licenses and insurance certificates with expiry dates, and build a worklist that catches them before they lapse. See Licenses.
• Escalate validation reviews through a supervisor using status-based escalation.
• See how QBO supports valuations and the rest of the servicing life cycle on Mortgage servicing.