Docs / Admin

The investment pipeline lifecycle

Summary — Opportunities move through eight stages from submission to facilitation, closure, or hold. Each stage requires specific information sections to be completed before the opportunity can advance. Scoring and matching help prioritize which investors to engage.

Purpose — Understand how to create opportunities, complete the required information sections for each stage, advance or move back between stages, and archive completed opportunities.

Audience — Staff, reviewer, lead, and admin roles who manage investment opportunities and the pipeline workflow.

Prerequisites — You have created at least one organization in the stakeholders module (Organizations area of the workbench — a dedicated guide is planned).

Overview

An opportunity is an investment project, policy initiative, or business proposal linked to a partner organization. Opportunities flow through eight stages:

submitted → intake_review → screening → development → matchmaking → facilitation → closed / on_hold

Key concepts:

  • Stages — Eight discrete steps in the deal journey. Each has a purpose and a set of information requirements.
  • Information sections — Eight structured forms that staff fill in as they learn more about the opportunity. Each section is domain-specific to sustainable investment facilitation in the Philippines.
  • Stage gates — Rules that prevent advancement until required sections for the current and all prior stages are completed.
  • Scoring — Optional algorithmic scoring comparing opportunities against investor profiles for match ranking.
  • Priority — Manual flag (low, medium, high, critical) indicating business importance.
  • Clusters — Three sustainable development categories for taxonomy and reporting.

Screenshot: Pipeline kanban board showing opportunities in columns by stage with priority badges and score values.

The eight stages

1. submitted

First entry point. The opportunity record has been created but not yet reviewed for completeness. All new opportunities start here.

Common sources: Direct staff creation, public submission portal, contact qualification, mobile Field Mode investor intake.

Advance to: intake_review (or on_hold).

2. intake_review

First staff review. Assess basic viability, sector match, and organizational readiness. Staff add initial notes, check organization linkage, and begin filling the Risk Assessment section.

Advance to: screening, or go back to submitted if information is insufficient.

3. screening

Detailed qualification. Validate the opportunity against cluster criteria and pipeline readiness. Technology details and strategic fit are assessed here.

Required sections to complete before advancing: Technology Details, Strategic Alignment (plus all sections required by earlier stages — Investment Type, Timeline, Risk Assessment).

Advance to: development, or go back to intake_review.

4. development

Active preparation. Partnership structure, local deployment needs, and market entry path are refined. Staff work with stakeholders to finalize terms.

Required sections to complete before advancing: Deployment Requirements, Local Partnership Needs, Market Entry Conditions (plus all prior stages' sections — Investment Type, Timeline, Risk Assessment, Technology Details, Strategic Alignment).

Advance to: matchmaking, or go back to screening.

5. matchmaking

Investor search and bilateral meeting scheduling. The system scores investor profiles against the opportunity criteria. Matches are reviewed and bilateral meetings are scheduled.

No additional sections required to advance from this stage.

Actions at this stage:

  • Click "Find Investors" in the Communications tab → system scores all investor profiles and redirects to the matching page.
  • Review suggested matches sorted by score.
  • Schedule meetings via "Schedule Meeting" (links to consultation creation).

Advance to: facilitation, or go back to development.

6. facilitation

Deal closing. Investor and opportunity owner work toward commitment. Document generation, diligence, and agreement signing happen here.

No additional sections required to advance from this stage (all eight sections should already be complete from earlier stages).

Actions at this stage:

  • Schedule consultation meetings for decision-makers.
  • Link or upload agreements, policy notes, and concept notes.
  • Send documents for e-signature via the Communications tab.

Advance to: closed (deal finalized), or move to on_hold (paused), or go back to matchmaking.

7. closed

Terminal state. Deal is completed, partnership formalized, or opportunity is resolved. closed has no allowed forward transitions — it cannot be reopened through the UI.

8. on_hold

Paused. The opportunity is suspended pending an external event (for example: investor needs capital next quarter, regulatory approval is pending). Not closed, but not active.

From on_hold, the opportunity can resume to any active stage: submitted, intake_review, screening, development, matchmaking, or facilitation.

Information sections and stage gates

The eight sections

Each section is a structured form with validated fields. Sections unlock cumulatively as the opportunity progresses through stages.

SectionLetterStage UnlockedRequired to Advance FROM
Investment TypeBsubmittedsubmitted
TimelineHsubmittedsubmitted
Risk AssessmentGintake_reviewintake_review
Technology DetailsCscreeningscreening
Strategic AlignmentIscreeningscreening
Deployment RequirementsDdevelopmentdevelopment
Local Partnership NeedsEdevelopmentdevelopment
Market Entry ConditionsFdevelopmentdevelopment

Cumulative gating: The gate check is additive. To advance FROM development, all eight sections must be marked complete — not just the three new ones added at that stage.

Section field reference

SectionKey FieldsValidation
Investment TypeinvestmentPhase (pilot / feasibility / full_scale), estimatedCapex (USD), fundingGap (USD), fundingGapNotesinvestmentPhase required
TimelineentryTimeline, pilotDuration, scaleUpPlanentryTimeline and pilotDuration required, max 500 chars each
Risk AssessmentkeyRisks, mitigationStrategykeyRisks required, max 2000 chars
Technology DetailsfeedstockInput, outputProducts, technologyReadinessLevel (1–9), environmentalImpactfeedstockInput and outputProducts required
Strategic AlignmentcircularEconomySector, climateEsgContribution, phPriorityAlignmentall optional, max 500–1000 chars
Deployment RequirementslandFacilityNeeds, utilities, workforceRequirementslandFacilityNeeds required
Local Partnership NeedspartnerType, roleOfLocalPartner, equityJvPreferencepartnerType and roleOfLocalPartner required
Market Entry ConditionspreferredLocation, regulatoryRequirements, incentivesSoughtpreferredLocation required

How gating works

When staff click "Advance Stage," the system calls checkGateRequirements(opportunityId, currentStage):

  1. It computes the cumulative required sections for all stages up to and including the current one.
  2. It compares that list against the sections where completed = true.
  3. If any required section is not completed, the advance action throws an error listing the missing sections.

The UI shows the required sections for the current stage with a ✓ or ○ indicator, and a separate red box if sections from earlier stages are still missing.

Example:

submitted → requires Investment Type + Timeline → advance to intake_review ✓
intake_review → also requires Risk Assessment → advance to screening
screening → also requires Technology Details + Strategic Alignment → missing Strategic Alignment
  → Fill Strategic Alignment in Information tab → mark completed → advance to development ✓

Screenshot: "Move to Next Stage" card on the opportunity Overview tab showing section checklist with green checkmarks and amber circles.

Creating an opportunity

Path: Dashboard → Pipeline → New Opportunity

Screenshot: New Opportunity form showing Title, Sector, Cluster, Estimated Value, Priority, Org Picker, and Geo Select fields.

Steps:

  1. Title (required, max 255 characters) — E.g., "Biomass energy plant — Bukidnon".
  2. Description (optional, max 5000 characters) — Background and context.
  3. Sector (optional, free-text) — E.g., "energy", "agribusiness", "infrastructure".
  4. Cluster — Select from C1 (Smart Enabling Environment), C2 (Sustainable Investments), C3 (Energy).
  5. Estimated Value (USD) (optional, number, min 0).
  6. Priority (defaults to medium) — low, medium, high, critical.
  7. Organization — Use the org picker to link to the investor or proponent organization.
  8. Primary Contact — Filtered to contacts from the selected organization.
  9. Target Location (optional) — Cascading geographic picker (Region → Province → Municipality → Barangay).
  10. Source (optional, free-text) — E.g., "Referral", "ECCP Event".

Click Create Opportunity.

Expected result: Opportunity created at stage submitted, score: null, redirected to opportunity detail page.

Other ways opportunities are created

MethodSource field valueWhat happens
Contact qualification — click "Qualify" on a contactcontact_qualificationCreates opportunity titled "{First} {Last} — Investment Opportunity", linked to contact's org, contact marked converted.
Public submission portalpublic_submitAuto-created from submitter's form data; organization and contact pre-linked.
Mobile Field Mode (Investor Intake wizard)investor_intakeCreates contact + consultation + opportunity (if staff marked "Qualified") all at once.

Viewing opportunity detail

Path: Pipeline → Click any opportunity card

The detail page has five tabs:

TabWhat is here
OverviewBasic details (title, sector, cluster, priority, org link), an inline edit form, and the "Move to Next Stage" card.
InformationThe eight wizard sections. Click a section to open its form, fill the fields, and mark it complete.
Communications"Find Investors" and "Schedule Meeting" buttons, linked consultations, linked documents, e-signature panel, and contacts from the linked organization.
HistoryImmutable stage transition log with timestamps and any transition notes.
LocationGeographic tags (regions, provinces, municipalities, barangays) linked to this opportunity.

Advancing and moving between stages

Moving an opportunity forward

  1. Open the opportunity detail page.
  2. Click the Overview tab.
  3. Scroll to the Move to Next Stage card.
  4. Check the section checklist. Sections with ✓ are complete; sections with ○ need to be filled in the Information tab.
  5. Fill any incomplete sections in the Information tab, then mark each one complete.
  6. Return to Overview. The stage dropdown shows allowed next stages (from the transition rules).
  7. Select the target stage, add optional transition notes, and click Advance Stage.

Expected result: Stage updated, stage history entry created with timestamp and actor, audit event logged. Dashboard refreshes.

Note: The button label changes to "Advance Stage (requirements missing)" when sections are incomplete. The server will reject the action and return an error listing missing sections.

Moving an opportunity backward

Stage movement is not one-way. From the transition rules, most stages allow going back one step:

  • intake_review → submitted
  • screening → intake_review
  • development → screening
  • matchmaking → development
  • facilitation → matchmaking

Use the same "Move to Next Stage" card — the dropdown lists all allowed transitions from the current stage, both forward and backward.

Exception: closed is a terminal stage with no allowed transitions. Once an opportunity is closed, it cannot be moved to any other stage through the UI.

Moving to on_hold

Any active stage can transition to on_hold. From on_hold, the opportunity can resume to any active stage (submitted, intake_review, screening, development, matchmaking, or facilitation). Use the stage dropdown and add a note explaining the reason.

Finding investors and scheduling meetings

Finding investors

From the opportunity detail page → Communications tab → click Find Investors.

The system runs the scoring algorithm against all investor profiles using the admin-configured scoring dimensions, creates Match records with status = suggested, and redirects to /matching?opportunityId={id}.

From the matching page, staff can:

  • Review match suggestions sorted by score (highest first).
  • Approve matches (status → approved) or reject them (requires a reason).
  • See investor name, score, and match details.

Scheduling meetings

From the opportunity detail → Communications tab → click Schedule Meeting.

This opens a new consultation creation form pre-linked to the opportunity (/consultations/new?opportunityId={id}). The consultation record appears in the Communications tab once created.

Priority, clusters, and scoring

Priority

A manual flag on each opportunity indicating business urgency.

ValueIntended use
criticalExecutive visibility, time-sensitive milestone, or highest-value deals only.
highActive priority pipeline — competitive or near-close.
mediumStandard active pipeline (default).
lowExploratory or early-stage.

Set or change priority: Overview tab → Edit Details form → Priority dropdown → Save.

Priority affects alerting (the daily pipeline stall check escalates critical and high items) and match urgency. It does not override stage gate requirements.

Clusters

Three thematic categories for segmenting pipeline by strategic focus:

ValueLabelFocus
cluster_1C1 — Smart Enabling EnvironmentPolicy reforms, trade facilitation, governance.
cluster_2C2 — Sustainable InvestmentsGreen and inclusive enterprise investment, capital mobilization.
cluster_3C3 — EnergyClean energy, renewable infrastructure, grid projects.

Set cluster during creation or update it from Overview → Edit Details. Leave blank only if genuinely undetermined; reports and matching are cluster-aware from the moment a cluster is assigned.

Scoring

An optional algorithmic score (0–100) comparing an opportunity against an investor profile. Scores live on Match records (investor–opportunity pairings), not on the opportunity itself.

How scores are generated:

  1. Admin configures scoring dimensions with a matchMode (exact_in_array, array_overlap, range, exact_equal) and a weight (0.0–1.0) at Admin → Matching Config — see Matching and scoring configuration.
  2. Staff clicks "Find Investors" on the opportunity.
  3. The system scores all investor profiles and creates Match records with score values.
  4. Results appear on the matching page sorted by score descending.

The opportunity's own score field starts as null and is only populated if explicitly updated (for example, by an admin or via a future automated flow). The score shown on the pipeline card reflects this field — not the latest match scores.

Archiving opportunities

Path: Opportunity detail → Archive button (lead or admin role required)

Clicking Archive opens a confirmation dialog. On confirm:

  • is_archived set to true.
  • Opportunity disappears from default list and dashboard views.
  • Audit event logged.

Archived opportunities are not deleted. They can be found by admins querying with the archived filter. Un-archiving requires admin access at the database level — there is no UI to reverse an archive.

Roles and permissions

RoleCreateAdvance / Move StageArchiveFind InvestorsSign Docs
staff✓✓✗✓✓
reviewer✓✓✗✓✓
lead✓✓✓✓✓
admin✓✓✓✓✓
public✗✗✗✗✗

Archive requires lead or admin to prevent accidental soft-deletes.

Best practices

  1. Complete information sections progressively. Fill sections as you learn more from meetings and stakeholders. The audit trail records when each section was saved.

  2. Assign a cluster on creation. Reports and matching work best with cluster data from the start. Pick the primary cluster even for multi-cluster deals.

  3. Always link to an organization. The linked org drives contact display in the Communications tab and is required for investor matching.

  4. Use priority intentionally. Reserve critical for deals with executive visibility or near-term milestones. Use high for competitive situations; medium for normal active pipeline.

  5. Configure scoring dimensions before first matching. Admins should set up dimension weights before staff start clicking "Find Investors." Without dimensions, all investors score 0 and results are unranked.

  6. Add transition notes when moving stages or going on hold. Notes appear in the History tab and help future staff understand decisions and delays.

  7. Monitor the stall digest. The daily pipeline stall check emails assignees when opportunities exceed the SLA threshold per stage (submitted: 3 days, intake_review: 5 days, screening: 14 days, development: 30 days, matchmaking: 21 days, facilitation: 45 days). These can be overridden per stage via the workflow config in Admin → Workflows.

Warnings

closed is terminal. Once an opportunity moves to closed, no further stage transitions are allowed. Plan this transition carefully.

Stage gate errors are hard blocks. If required sections are incomplete, the server rejects the advance action. The UI shows a warning in the button label but does not prevent submission — the error will appear as a toast after the form posts.

Priority does not bypass gate requirements. Even a critical opportunity must have all required sections completed before advancing.

Archived opportunities are hidden, not deleted. They do not appear in default pipeline views. Only admins can query them. Un-archiving is not available via the UI.

Score on opportunity card reflects opportunity.score, not match scores. The opportunity's own score is null until explicitly set. Match scores live on individual Match records and are visible on the /matching page.

Troubleshooting

"Advance Stage (requirements missing)" — what does this mean?

Symptom: The button shows this label, and clicking it results in an error listing incomplete sections.

Cause: One or more sections required by the current or an earlier stage have completed = false.

Fix:

  1. Open the Information tab.
  2. Click each section that shows ○ (not completed) in the stage card.
  3. Fill all required fields (marked in the form). Required fields for each section are listed in the Section field reference table above.
  4. Click Save on each section and check the "Mark as complete" toggle.
  5. Return to Overview. If all required sections now show ✓, the button label reverts to "Advance Stage."

"Cannot advance: incomplete sections — …"

Symptom: Server returns an error after clicking Advance Stage.

Cause: Same as above — required sections incomplete. The error message lists the section keys (e.g., risk, alignment).

Fix: Same as above. Match the section key to its label using the section table: risk = Risk Assessment, alignment = Strategic Alignment, etc.

Opportunity not visible in Pipeline list

Symptom: You created an opportunity but it does not appear in the Pipeline view.

Cause: Opportunity may have been archived, or an active filter is hiding it.

Fix:

  1. Check the filter bar — clear any stage, priority, or cluster filters.
  2. If recently archived, it will not appear in default views. Contact admin to recover it.
  3. Hard-reload the page (Cmd+R / Ctrl+Shift+R) to clear client-side cache.

Score shows null on opportunity card

Symptom: The opportunity detail header shows no score or shows null.

Cause: opportunity.score is null by default. Match scores are stored on Match records, not on the opportunity itself.

Clarification: Click "Find Investors" to generate Match records with scores, then view them on the /matching page filtered to this opportunity.

"Cannot advance: Illegal stage transition"

Symptom: Server error after attempting a stage move.

Cause: The selected target stage is not in the allowed transitions for the current stage (for example, trying to jump from submitted to development).

Fix: Use the stage dropdown, which is pre-populated only with legal next stages from the current stage's transition rules. Do not manually edit form fields.

FAQ

Can I move an opportunity back to a previous stage? Yes. Most stages allow going backward one step: intake_review → submitted, screening → intake_review, development → screening, matchmaking → development, facilitation → matchmaking. The stage dropdown lists all legal options. The only exception is closed — it is terminal and cannot be reopened.

What is the difference between on_hold and closed? on_hold is a pause — the opportunity can resume to any active stage when conditions change. closed is terminal — the deal is done or permanently ended. Use on_hold for temporary blocks (waiting for capital, regulatory delay); use closed for final outcomes.

Can I create an opportunity without an organization? Yes, the organization field is optional in the schema, but the matching and CRM features will not work without it. Create the organization first in Stakeholders if it does not exist.

What does "source" mean on an opportunity? Source tracks the origin: manual (staff created directly), contact_qualification (converted from a qualified lead), investor_intake (from mobile Field Mode), or public_submit (public submission portal). Used for audit and pipeline reporting.

Can I delete an opportunity? No. Opportunities are soft-deleted only — click Archive to hide the record from lists. To restore an archived opportunity, contact admin.

Why is investmentType not on the create form? The investmentType field (free-text, max 100 characters) can be set via Edit Details on the opportunity detail page. The Investment Type wizard section (section B) captures the structured phase/capex/funding data and is the authoritative record for deal structure.

How do I know which stage an opportunity should be in? Use the Stage Requirements card as the signal: if all required sections for the current stage are complete and you have gathered enough stakeholder input, advance. General guide: spend at least 1–2 weeks per stage before moving forward.

When is the pipeline stall check run? Daily at 8 AM Manila time. If your opportunity is overdue by the SLA for its stage, you and any assigned staff will receive an email alert. Default SLAs can be overridden by admin via Admin → Workflows → pipeline-stall-check config.

Related articles