User Manual

1 · Overview

Promanage RPI currently ships with two tools:

• Claim Listings — Bulk-claim Google My Business profiles from a list of Google Maps URLs. Accepts .xlsx; required columns location_link.
• Phone Number Ticketing — Bulk-raise 'Phone number pending verification' tickets on the Google support form for a list of Business Profiles. Accepts .xlsx; required columns business name, country code, phone number, business profile id, ticket id, ticket raised on.
• Address Geocoding (AI) — Resolve Area / Sub Area / City from an address or lat-lng (or both). Cache-backed — recurring lookups return instantly and quality improves with use. Accepts .xlsx; required columns address.

More tools can be added at any time without changing the platform shell.

The application has two authentication layers:

• Google OAuth sign-in — tells the application who you are. Used only for identity and to scope your job history.
• GBP browser session — a real Chrome login you do once, stored as cookies on your machine. The bot uses this session for every tool.

2 · Getting started

1. Sign in with Google. Click Sign in with Google on the landing page. You'll be returned to the dashboard.
2. Connect your Google Business account. On the dashboard, click Connect Google Business account. A Chrome window opens — sign in to Google there. The window closes automatically and the dashboard updates to show ✓ Connected.
3. Download the template. Click Download Tickets_Raising_List template. This is the spreadsheet format the application expects.

3 · Phone Number Ticketing

Submits the “Phone number pending verification” form for each row.

Input: .xlsx · Output: filled .xlsx with case IDs written back.

4 · Claim Listings

Bulk-claims Google My Business profiles by navigating to each Maps URL and walking through the claim flow.

Input: .csv · Output: the same CSV with status columns appended.

Possible status values: Business claimed successfully, Already in my account, Listing not found, Business claim option not available, Claim flow completed — verification may be pending.

5 · Running a job

1. From the dashboard, click Upload & start job with your filled spreadsheet selected.
2. The application validates the column headers. If anything is wrong, you'll see a clear error and you can fix the spreadsheet.
3. You'll be redirected to the Job detail page (URL: /jobs/<id>). You'll see a list of all rows with status pending.
4. Click Start. A Chrome window opens on your machine and begins processing row by row.
5. You can leave the browser tab open to watch live progress, or close it — the job continues running on the server. Return to it later from the History page.

6 · Reading live progress

The job detail page has three sections:

• Status bar at the top — overall job status (running, done, failed), submitted count, and failed count.
• Live progress log — scrolling stream of every step the bot takes (form load, field fills, radio clicks, submit, confirmation detection, ticket capture).
• Per-row table — one row per profile with its current status and step. Updates in real time as the job advances.

The 13 steps the bot performs for each row are:

7 · Handling failures & retries

Three layers of resilience are built in:

1. Automatic per-row retry. If a row fails (network blip, transient Google error, missing widget), the bot retries it up to two more times automatically. Backoff is 30 seconds, then 2 minutes. If the error looks like rate-limiting / CAPTCHA, the cool-down extends to 4 minutes.
2. Manual retry of failed rows. Once a job has finished, if any rows are still failed, click Retry failed. The bot reprocesses only the failed rows.
3. Auto-resume on server restart. If you stop the server (or it crashes) mid-job, the next time you start the application it picks up where it left off automatically — submitted rows are skipped, in-flight and pending rows are processed.

8 · Output file

Once at least one row has finished, the Download output button on the job page returns the filled spreadsheet:

• Ticket id column populated with the captured case ID (e.g. 1-0768000041490).
• Ticket Raised On column populated with the submission timestamp.
• Failed rows: Ticket id left blank, timestamp column shows the failure reason.

The file is saved after every row so you can download it mid-run for a snapshot of progress.

9 · History

Click History in the top nav to see every job you've ever run, with status, counts, timestamps, and links to the job detail page and the output download.

10 · Resilience & resume behaviour

Behind the scenes, the application:

• Saves per-row state to a local SQLite database after every step, so the live UI always reflects what actually happened.
• Restarts the Chrome browser every 50 rows on long jobs, which keeps memory bounded and reduces the chance of being flagged as automated.
• Detects Google’s rate-limit / CAPTCHA signals and switches to a 4-minute cool-down before retrying.
• Persists the GBP browser session after each job so the next run starts from the latest cookies.

11 · FAQ

How long does each row take?

Approximately 30–50 seconds — form load (~12 s) + fills + submit + confirmation wait + 8 s cool-down. A 100-row job typically runs in 60–90 minutes.

Will the bot get rate-limited?

Possibly on very large batches. Google’s support endpoint will start CAPTCHA-ing or showing “unusual traffic” messages after ~60–100 submissions per hour from one account. The retry layer detects this and applies a longer cool-down. If you regularly see rate-limit retries, spread the job across multiple sessions or lower your row count per run.

Can multiple users run jobs at the same time?

Yes. Each user has their own browser session and history. Different users' jobs run independently.

What if Google changes the form?

The form-structure dump in the server logs (first row of each run) shows every radio/input id and label, so the bot's targeting can be quickly updated to match. The submit logic looks for confirmation phrases like “Your email has been sent” or “For your reference, your case ID is…”; if Google rewords this, the confirmation needles in the code may need to be updated.

What data is stored where?

PostgreSQL (schema rpi on the configured server): users, jobs, job rows, conversations, tickets, geocoding cache. Azure Blob (container rpi-data): uploaded spreadsheets in uploads/, filled outputs in outputs/, email attachments in email-attachments/, tool templates in templates/. Your GBP browser session lives in the gbp_sessions table.

How do I clear my session / start fresh?

Click Re-connect on the dashboard to overwrite your stored session with a fresh one.