Agriculture Project Fund Control User Walkthrough

This walkthrough shows how a farm manager can run three coffee farms using project-funded controls in Pinkapple ERP.

The example story is a managed coffee portfolio where the operator receives money from different funders, manages each farm as a project, records field work, pays workers or group leaders, posts accounting entries, and reports how each funder's money was used.

The same flow applies to managed plantations, grant-funded agriculture programs, estate farms, contract farms, and other services that need project/WBS fund control.

Before You Start

Confirm these setup items exist before recording or testing:

Setup Item	Owning Module	What It Is Used For
Agriculture service and capability packs	Platform Admin -> Companies -> Manage Services	Enables Agriculture pages and seed packs for the tenant.
Parties	Parties	Holds funders, workers, group leaders, supervisors, buyers, and suppliers.
Projects and WBS	Projects & WBS	Holds project scope, farm cost structure, funding, obligations, and fund reports.
Farms	Agriculture -> Setup -> Farms	Holds the agriculture farm identity and farm partitions.
Payment channels	Payments / Financial Setup	Used when fund receipts and worker payments are settled.
Chart of accounts and posting rules	Accounting / GL	Used when receipts, payments, and settlements post to GL.
Document transaction types	Document Transactions -> Setup	Defines the business meaning of documents such as funding agreements, receipts, work orders, and obligations.

Document numbers are generated by the backend from the selected document type. Users should not type document numbers. Use External Reference for bank slips, paper forms, supplier references, field notebooks, or imported references.

Plain-English Document Types

Document Transaction forms can feel heavy because they are one shared engine used for many business documents. The selected Document Type gives the form its meaning.

Form / Document	Plain Meaning	Accounting Meaning
Funding Source / Project Funding Agreement	A funder has approved or committed money for a project.	Commitment or authorization. It is not yet cash received.
Fund Receipt	Money has actually been received from a funder, bank, cash office, wallet, or other channel.	Money-in event. This should support cash/bank/clearing and project fund position.
Work Order	Work is planned for a farm or WBS node.	No payment yet. It creates operational control.
Field Activity Report	Work was done and evidence was captured.	Can support costing, stock, inspection, or obligation creation.
Worker Attendance	A worker group or individuals attended work.	Source evidence for labor obligation and payout.
Payment Obligation	The tenant owes someone because approved work, attendance, supply, or service happened.	Payable/commitment before payment execution.
Payment Batch	The actual payout run for approved obligations.	Payment execution and GL posting.
Cross-Funding Request	One project/fund temporarily supports another.	Creates due-from and due-to exposure until settled.
Cross-Funding Settlement	The borrowed project/fund is repaid or cleared.	Closes due-from and due-to exposure.

Demo Projects And Farms

Use three projects so the recording shows real fund separation and cross-project controls.

Demo Project	Farm	Funder	Budget	Project Start	Project End
Julita Coffee Farm - Mityana Block A	Mityana Coffee Farm A	Aston Brown	UGX 120,000,000	2025-09-01	2026-12-31
Julita Coffee Farm - Mpigi Block B	Mpigi Coffee Farm B	Grace Nakkazi	UGX 150,000,000	2025-09-01	2026-12-31
Julita Coffee Farm - Mubende Block C	Mubende Coffee Farm C	Moses Ochieng	UGX 180,000,000	2025-09-01	2026-12-31

Suggested WBS nodes for each project:

WBS Node	Purpose
Field Labour	Weeding, pruning, mulching, manure application, harvest preparation.
Inputs And Fertilizer	Manure, seedlings, fertilizer, farm chemicals, protective materials.
Supervision And Transport	Supervisor visits, field transport, fuel, tools movement.
Harvest And Intake	Harvesting, weighing, intake, grading, and storage movement.

End-To-End Flow

Use this exact order for the project fund-control demo:

1. Create or confirm parties.
2. Create projects and WBS nodes.
3. Create farms and partitions.
4. Register funding sources.
5. Record fund receipts.
6. Plan field work.
7. Record attendance or activity evidence.
8. Create payment obligations.
9. Create and execute payment batch.
10. Verify GL and reports.
11. Close the project when work and funding are fully reconciled.

Step 1: Create Or Confirm Parties

Open Parties and create or confirm the people and organizations used in the demo.

Party	Party Type	Role In Demo
Aston Brown	Individual	Project funder and possible group leader payee.
Grace Nakkazi	Individual	Project funder and possible group leader payee.
Moses Ochieng	Individual	Project funder and possible group leader payee.
Amina Nakato	Individual	Supervisor or worker group leader.
Peter Okello	Individual	Supervisor, supplier, or field lead.

Expected result:

• Each party has a readable name and business reference.
• The UI should not expose internal party IDs to the user.
• If a party is linked as a project funder, the system can assign or infer the Project Funder role for that relationship.

Next action:

• Use these parties as project owners, funders, group leaders, supervisors, or payment payees in later steps.

Step 2: Create The Projects

Open Projects & WBS -> Project Control.

Create one project per farm.

Field	Mityana Block A	Mpigi Block B	Mubende Block C
Project Name	Julita Coffee Farm - Mityana Block A	Julita Coffee Farm - Mpigi Block B	Julita Coffee Farm - Mubende Block C
Project Type	Managed Farm / Contract	Managed Farm / Contract	Managed Farm / Contract
Owner / Funder Party	Aston Brown	Grace Nakkazi	Moses Ochieng
Business Unit	Head Office or Agriculture Head Office	Head Office or Agriculture Head Office	Head Office or Agriculture Head Office
Currency	UGX	UGX	UGX
Budget Amount	120000000	150000000	180000000
Fund Restriction	RESTRICTED	RESTRICTED	RESTRICTED
Start Date	2025-09-01	2025-09-01	2025-09-01
End Date	2026-12-31	2026-12-31	2026-12-31

Expected result:

• Project code is generated by the backend.
• The project detail view shows the project name, status, approval state, owner/funder display, budget, dates, and linked WBS controls.
• The project becomes the top-level control point for funding, spending, GL context, and reports.

Next action:

• Add WBS nodes and budgets for each project.

Step 3: Add WBS Nodes And Budget Lines

Open the project detail page, then use the WBS and budget controls.

Create these WBS nodes for each project:

WBS Node	Mityana Budget	Mpigi Budget	Mubende Budget
Field Labour	45000000	55000000	65000000
Inputs And Fertilizer	35000000	45000000	55000000
Supervision And Transport	20000000	25000000	30000000
Harvest And Intake	20000000	25000000	30000000

Expected result:

• Every project has clear spending lanes.
• Later work orders, attendance sheets, obligations, and payments can point to the correct WBS node.

Next action:

• Create the farm record and bind it to the project.

Step 4: Create Farms And Farm Partitions

Open Agriculture -> Setup -> Farms.

Create three farms.

Field	Mityana	Mpigi	Mubende
Farm Name	Mityana Coffee Farm A	Mpigi Coffee Farm B	Mubende Coffee Farm C
Farm Type	Coffee Plantation	Coffee Plantation	Coffee Plantation
Primary Crop	Coffee	Coffee	Coffee
Acreage	100	150	200
District / Region	Mityana	Mpigi	Mubende
Linked Project	Julita Coffee Farm - Mityana Block A	Julita Coffee Farm - Mpigi Block B	Julita Coffee Farm - Mubende Block C
Operational Location	Link if available	Link if available	Link if available
Status	ACTIVE	ACTIVE	ACTIVE

Create sample partitions for each farm:

Farm	Partition	Size	Purpose
Mityana Coffee Farm A	Block A1	40 acres	Mature coffee, flowering stage.
Mityana Coffee Farm A	Block A2	35 acres	Mature coffee, weeding and manure.
Mityana Coffee Farm A	Nursery A3	25 acres	Seedlings and replacement stock.
Mpigi Coffee Farm B	Block B1	60 acres	Mature coffee, flowering stage.
Mpigi Coffee Farm B	Block B2	55 acres	Pruning and manure.
Mpigi Coffee Farm B	Block B3	35 acres	Young coffee.
Mubende Coffee Farm C	Block C1	80 acres	Mature coffee, flowering stage.
Mubende Coffee Farm C	Block C2	70 acres	Field maintenance.
Mubende Coffee Farm C	Block C3	50 acres	Harvest preparation.

Expected result:

• Farms are business entities, not just physical locations.
• Farm partitions can carry crop, block, acreage, and project context.
• Operational locations can still be linked for geography, stock storage, or branch structure.

Next action:

• Register each funder's project funding source.

Step 5: Register Funding Sources

Open Projects & WBS -> Operations -> Fund Control -> Funding Sources.

Click Register Funding Source.

Use one funding source per project.

Field	Mityana	Mpigi	Mubende
Document Type	Project Funding Agreement	Project Funding Agreement	Project Funding Agreement
Business Unit	Agriculture Head Office	Agriculture Head Office	Agriculture Head Office
Document Date	2025-09-01	2025-09-01	2025-09-01
Counterparty	Aston Brown	Grace Nakkazi	Moses Ochieng
External Reference	FUND-ASTON-2025-001	FUND-GRACE-2025-001	FUND-MOSES-2025-001
Currency	UGX	UGX	UGX
Project	Mityana Block A project	Mpigi Block B project	Mubende Block C project
WBS / Work Package	Leave blank or select top-level project	Leave blank or select top-level project	Leave blank or select top-level project
Funding Source	Leave blank on the source document	Leave blank on the source document	Leave blank on the source document
Line Description	Approved managed coffee farm funding	Approved managed coffee farm funding	Approved managed coffee farm funding
Line Amount	120000000	150000000	180000000

Do not enter Document Number. It should be generated.

Expected result:

• A funding agreement/source document exists.
• It proves that spending is authorized up to the agreed amount.
• It does not prove that cash has been received yet.

Next action:

• Record actual money received using a Fund Receipt.

Step 6: Record Fund Receipts

Open Projects & WBS -> Operations -> Fund Control -> Fund Receipts.

Click Record Fund Receipt.

Use two receipts per project to show timed deposits.

Field	Mityana Receipt 1	Mityana Receipt 2	Mpigi Receipt 1	Mpigi Receipt 2	Mubende Receipt 1	Mubende Receipt 2
Document Type	Project Fund Receipt	Project Fund Receipt	Project Fund Receipt	Project Fund Receipt	Project Fund Receipt	Project Fund Receipt
Document Date	2025-09-05	2026-01-15	2025-09-10	2026-02-01	2025-09-12	2026-02-10
Counterparty	Aston Brown	Aston Brown	Grace Nakkazi	Grace Nakkazi	Moses Ochieng	Moses Ochieng
External Reference	BANK-ASTON-001	BANK-ASTON-002	BANK-GRACE-001	BANK-GRACE-002	BANK-MOSES-001	BANK-MOSES-002
Currency	UGX	UGX	UGX	UGX	UGX	UGX
Project	Mityana Block A	Mityana Block A	Mpigi Block B	Mpigi Block B	Mubende Block C	Mubende Block C
Funding Source	Mityana funding agreement	Mityana funding agreement	Mpigi funding agreement	Mpigi funding agreement	Mubende funding agreement	Mubende funding agreement
Line Amount	70000000	50000000	90000000	60000000	100000000	80000000
Notes	Initial project deposit	Second managed farm deposit	Initial project deposit	Second managed farm deposit	Initial project deposit	Second managed farm deposit

Expected result:

• Fund receipts create the actual received-funds side of the project position.
• After approval and posting, GL should show money-in effects according to the tenant posting rules.
• Project fund reports should show available project funds.

Next action:

• Start planning and recording farm work.

Step 7: Create Field Work Orders

Open Agriculture -> Operations -> Field Operations -> Work Orders.

Create one work order per farm for coffee flowering-stage maintenance.

Field	Mityana	Mpigi	Mubende
Document Type	Agriculture Field Work Order	Agriculture Field Work Order	Agriculture Field Work Order
Document Date	2026-08-10	2026-08-10	2026-08-10
Project	Mityana Block A	Mpigi Block B	Mubende Block C
Farm	Mityana Coffee Farm A	Mpigi Coffee Farm B	Mubende Coffee Farm C
Farm Partition	Block A1	Block B1	Block C1
WBS / Work Package	Field Labour	Field Labour	Field Labour
Activity	Weeding and manure application	Weeding and pruning	Weeding and flowering-stage cleanup
Supervisor	Amina Nakato	Peter Okello	Amina Nakato
Worker Group	Coffee Field Crew 1	Coffee Field Crew 2	Coffee Field Crew 3
Planned Start	2026-08-12	2026-08-13	2026-08-14
Planned End	2026-08-14	2026-08-15	2026-08-16
Estimated Cost	1610000	1670000	1730000

Expected result:

• Work is planned before payments are made.
• The project, WBS, farm, and partition context is already attached before evidence capture.

Next action:

• Record the actual attendance and activity evidence.

Step 8: Record Worker Attendance

Open Agriculture -> Operations -> Field Operations -> Worker Attendance.

Use group-leader payout for the shortest recording. Use direct-worker payout when you want to show that the system can split approved attendance into individual worker payments.

Field	Mityana	Mpigi	Mubende
Document Type	Agriculture Worker Attendance Sheet	Agriculture Worker Attendance Sheet	Agriculture Worker Attendance Sheet
Source Work Order	Mityana work order	Mpigi work order	Mubende work order
Project	Mityana Block A	Mpigi Block B	Mubende Block C
Farm	Mityana Coffee Farm A	Mpigi Coffee Farm B	Mubende Coffee Farm C
WBS / Work Package	Field Labour	Field Labour	Field Labour
Attendance Date	2026-08-12	2026-08-13	2026-08-14
Worker Group	Coffee Field Crew 1	Coffee Field Crew 2	Coffee Field Crew 3
Group Leader / Payee	Aston Brown	Grace Nakkazi	Moses Ochieng
Supervisor	Amina Nakato	Peter Okello	Amina Nakato
Payout Mode	GROUP_LEADER	GROUP_LEADER	GROUP_LEADER
Worker Count	10	10	10
Rate / Day	161000	167000	173000
Total Amount	1610000	1670000	1730000
Evidence	Attendance sheet, field photo, GPS if available	Attendance sheet, field photo, GPS if available	Attendance sheet, field photo, GPS if available

Expected result:

• Approved attendance becomes evidence for a labor payment obligation.
• Group membership role metadata should prove who was worker, group leader, or supervisor for that group at the time of approval.
• The group-leader path pays one approved leader on behalf of the group.
• The direct-worker path carries the worker group, group leader role, supervisor role, and worker party context into the source documents before payment batching.

Important:

• Individual-worker split payout should create one obligation or one payment line per worker, depending on the selected policy.
• The direct-worker live smoke currently uses JAW-DIRECT-22180210031035 and obligations JOBL-DIR-1-180210031035 through JOBL-DIR-3-180210031035.

Next action:

• Create payment obligations from the approved attendance sheets.

Step 9: Create Payment Obligations

Open either:

• Agriculture -> Operations -> Finance Orchestration -> Spending Requests, for agriculture source context.
• Projects & WBS -> Operations -> Fund Control -> Payment Obligations, for project-owned fund control.

Use payment obligations to say, “this person or group must now be paid from this project fund.”

Field	Mityana	Mpigi	Mubende
Document Type	Agriculture Payment Obligation Request	Agriculture Payment Obligation Request	Agriculture Payment Obligation Request
Source Document	Mityana worker attendance	Mpigi worker attendance	Mubende worker attendance
Project	Mityana Block A	Mpigi Block B	Mubende Block C
WBS / Work Package	Field Labour	Field Labour	Field Labour
Funding Source	Mityana funding agreement or receipt	Mpigi funding agreement or receipt	Mubende funding agreement or receipt
Payee	Aston Brown	Grace Nakkazi	Moses Ochieng
Payment Mode	Group leader on behalf	Group leader on behalf	Group leader on behalf
Amount	1610000	1670000	1730000
Due Date	2026-08-20	2026-08-20	2026-08-20
Cost Category	Field Labour	Field Labour	Field Labour
Notes	Worker group payout for approved attendance	Worker group payout for approved attendance	Worker group payout for approved attendance

Expected result:

• The obligation is approved before payment execution.
• The system should reject duplicate or over-amount payment lines from the same obligation.
• The project fund position should show committed spending.

Next action:

• Generate a payment batch from approved obligations.

Step 10: Create And Execute Payment Batch

Open Payments -> Bulk Payments.

Create a batch for approved obligations.

Field	Value
Batch Number	Generated or use external reference if required
Batch Mode	SETTLE_OBLIGATIONS
Business Unit	Agriculture Head Office
Payment Channel	Cash or configured internal payment channel
Currency	UGX
Batch Date	2026-08-20
Notes	Coffee field worker payouts from approved project obligations

Add approved obligations as lines.

Line	Source Obligation	Payee	Amount	Expected Payment Pattern
1	Mityana obligation	Aston Brown	1610000	Group leader paid on behalf of workers.
2	Mpigi obligation	Grace Nakkazi	1670000	Group leader paid on behalf of workers.
3	Mubende obligation	Moses Ochieng	1730000	Group leader paid on behalf of workers.

Expected result after validation:

• Lines inherit source obligation, project, WBS, funding source, and payee context.
• Duplicate source lines should be rejected.
• Amounts above remaining obligation balance should be rejected.

Expected result after approval and execution:

• Batch status moves to successful execution.
• Payment transactions are created for settled internal/cash lines.
• GL batch is created or linked according to posting rules.
• Project utilization reports show paid spending.

Live proof currently available:

• JPB-20260820-02 is approved and successful.
• Lines 44-48 created payment transactions 136-140.
• Those payment transactions are OUTBOUND, DISBURSEMENT, SETTLED, and were created by settle_internal_batch_line.
• This proves the group-leader/payee-style obligation-backed internal settlement path.
• SMOKE-PB-DIRECT-22180210031035 is approved and successful.
• Direct-worker lines 49-51 created payment transactions 143-145.
• Those direct-worker transactions paid Amina Nalubega, Samuel Kato, and Grace Nansubuga individually.
• The direct-worker batch inherited project PRJ-000007, WBS WBS-000015, funding receipt JFR-01-01, and source obligations JOBL-DIR-1-180210031035 through JOBL-DIR-3-180210031035.
• This proves the individual worker payout path from approved attendance evidence to payment transactions.

Current gap:

• JPB-20260820-01 is GL-posted and successful, but its line-level payment_transaction_id values are blank. Do not use it as proof of payment-transaction creation.
• Mixed payout still needs a separate scenario-specific smoke if the recording must show some workers paid directly and others through a group leader in the same batch.

Step 11: Verify GL

Open Accounting / GL and find the payment batch GL reference.

For the current live proof, use:

Item	Value
Group-Leader Payment Batch	JPB-20260820-02
Group-Leader Payment Batch ID	44
Group-Leader GL Batch	BATCH-202608000276
Group-Leader GL Batch ID	2706
Group-Leader Payment Transactions	136, 137, 138, 139, 140
Direct-Worker Payment Batch	SMOKE-PB-DIRECT-22180210031035
Direct-Worker Payment Batch ID	45
Direct-Worker GL Batch	BATCH-202608000296
Direct-Worker GL Batch ID	2736
Direct-Worker Payment Transactions	143, 144, 145

Expected result:

• Payment execution has accounting impact.
• The GL batch references the payment batch.
• The project/funding reports reconcile with the posted payment data.

Next action:

• Run project fund reports.

Step 12: Run Reports

Open Reporting -> Run Reports.

Use the Projects & WBS report group.

Report	What To Show
Project Fund Position	Funding source, fund receipt, available balance, committed obligations, paid utilization.
Project Fund Utilization	Work, obligation, payment batch, GL status, and amount used by project/WBS.
Project Cross-Funding Exposure	Open due-from/due-to exposures and settlements between projects or funds.

Filter examples:

Filter	Example
From Date	2025-09-01
To Date	2026-08-31
Currency	UGX
Project	Select one of the three demo projects
Funding Document	Select the funding agreement or receipt if needed
Status	OPEN, SETTLED, POSTED, or APPROVED where the report supports it

Expected result:

• Reports show user-facing document numbers and party names, not internal IDs.
• Drilldowns should open dialogs or in-report views, not route away unexpectedly.
• Fund position and utilization should match the payment and GL story.

Step 13: Optional Cross-Project Funding Demo

Use this only if the recording needs cross-funding.

Scenario:

• Mityana Block A temporarily funds a labor obligation for Mpigi Block B.
• Mpigi later receives money and settles the exposure back to Mityana.

Open Projects & WBS -> Operations -> Fund Control -> Cross-Funding Requests.

Field	Value
Source Project	Julita Coffee Farm - Mityana Block A
Source Funding Document	Mityana funding receipt
Target Project	Julita Coffee Farm - Mpigi Block B
Target WBS	Field Labour
Amount	5000000
Reason	Temporary support for field labor before second deposit clears.
Expected Settlement Date	2026-09-15

Expected result:

• Cross-funding creates an exposure, not free spending.
• GL should carry due-from and due-to accounts if posting rules are configured.
• The exposure remains open until a cross-funding settlement is approved and posted.

Next action:

• Use Cross-Funding Settlements to clear the exposure after the target project receives money.

Step 14: Finish Or Close The Project

Before closing a project, verify:

Check	Expected State
Funding agreements	Approved and reconciled.
Fund receipts	Approved and posted where applicable.
Work orders	Completed or cancelled.
Field activity reports	Approved and linked to evidence.
Worker attendance	Approved and either paid or explicitly not payable.
Obligations	Paid, cancelled, or carried forward with approval.
Payment batches	Successful, failed with resolution, or cancelled.
Cross-funding exposure	Settled or formally outstanding.
GL	Posted batches reconcile to payment and receipt records.
Reports	Fund position, utilization, and exposure explain remaining balances.

Expected result:

• The project can be closed without hiding unpaid workers, missing fund receipts, or unresolved cross-funding.

Recording Order

Use this screen order for a clean user recording:

1. Dashboard agriculture card.
2. Agriculture -> Setup -> Farms: show the three farms and partitions.
3. Projects & WBS -> Project Control: show the three projects and one project detail.
4. Projects & WBS -> Fund Control -> Funding Sources: create or show funding agreement.
5. Projects & WBS -> Fund Control -> Fund Receipts: create or show actual received money.
6. Agriculture -> Operations -> Field Operations: show work order and attendance.
7. Projects & WBS -> Fund Control -> Payment Obligations: show approved obligation.
8. Payments -> Bulk Payments: show JPB-20260820-02.
9. GL: show BATCH-202608000276.
10. Reporting -> Projects & WBS: run fund position and utilization.
11. Optional: show cross-funding exposure and settlement.

Payment Pattern Notes

Use these talking points when explaining worker payouts:

Pattern	Meaning	Current Proof Level
Group leader paid on behalf	One payment line goes to the group leader, backed by an attendance sheet listing workers.	Proven in the current live obligation/payment/GL path.
Individual worker payout	One line per worker or one obligation split into worker-level lines.	Proven through SMOKE-PB-DIRECT-22180210031035, payment transactions 143-145, and GL batch BATCH-202608000296.
Mixed payout	Some workers paid directly, some through a leader, and suppliers paid separately.	Supported by shared payment batch design; needs scenario-specific smoke.
Supplier/service payout	Activity report or service document creates an obligation to a supplier.	Supported by obligation-backed payment path.

The important discipline is that the payment batch should not be the first record. Work, attendance, or service evidence should be approved first. Then the obligation is created. Then payment execution happens from the approved obligation.

Common Mistakes To Avoid

Mistake	Correct Approach
Typing document numbers manually.	Let the backend generate them from the document type.
Treating a funding agreement as cash received.	Record a separate fund receipt when money actually arrives.
Paying workers directly from a work order.	Approve attendance or activity evidence, create an obligation, then pay from the obligation.
Using Agriculture as a second project/payment/reporting module.	Use Agriculture for source workflows and context; use Projects, Payments, Reporting, and GL as owning primitives.
Showing internal IDs to users.	Use party names, project codes, farm codes, document numbers, payment batch numbers, and GL batch numbers.
Recording a farm only as a location.	Create a farm entity and optionally link it to operational location and project.