Using the client project portal

The client project portal is a page on your ERPNext site where you can follow your projects, see where the hours are going, and add tasks, comments and files without leaving the browser. This document is written for a client who has been given access, with a section at the end for the admin who grants access and installs the app.

The portal ships with the open source ERPNext TaskView app. The team side of the same app, with timers and hour budgets, is covered in Timers, Timesheets, and Hour Budgets.

Sign in

Open the /projects page on your ERP site, for example https://erp.example.com/projects, and sign in with the account you were given. If you open the page while signed out, you are sent to the login page first and brought back to /projects afterwards.

Older links such as /project and /projects?project=PROJ-0001 still work. They redirect to the new portal.

The left sidebar lists your projects. Below them, an Account section holds the other portal pages your site has enabled (orders, invoices, issues and so on). The menu at the top of the sidebar has My account and Log out.

What you can see

Which projects appear

You see a project when any one of these is true:

• Your Contact is linked to the project's customer.

• You are listed under Customer Portal Users on that customer.

• You are listed under Users on the project itself.

Cancelled projects are not listed. If a project name is wrong or belongs to someone else, the portal answers "You do not have access to this project" in both cases, so nobody can probe for projects they were not given.

The project list

/projects shows one card per project, newest activity first. Each card has the project title, its status, an hours meter and a count of tasks in each column: Open, Working, Pending Review and Completed.

The project overview

Click a project to open its Overview tab. It has three parts:

• Tasks: the four counts above. Click one to jump to the board.

• Phases: each top-level group task, with "X of Y tasks done" and its own hours meter. Click a phase to see only its tasks.

• Recent activity: the latest comments, files, status changes, time entries and new tasks, newest first.

Reading the hours meter

A meter reads like 12.5 / 20 h. It turns amber at 80% of the budget and red once the hours logged go over it. Hover over it for the remaining or overage in hours.

• A task's budget is its Expected Time. If a task has none, the portal adds up its subtasks.

• A project's budget is its Budgeted Hours. If that is blank, the portal adds up the top-level tasks.

• Logged hours are live. They include draft timesheets, submitted timesheets, running timers, and everything logged on subtasks.

Work with hours logged but no budget shows the hours alone, such as 12 h.

Tasks as a list or a board

The Tasks tab has a List and a Board switch. The choice is kept in the address bar (?view=board), so you can bookmark or share the link.

• List: an indented tree, phases first with their tasks beneath. Each row shows comment and file counts, the due date, an hours meter and a status badge.

• Board: four columns, Open, Working, Pending Review and Completed. Phases are not cards; only tasks are.

Use the phase drop-down and the search box (it matches title or task ID) to narrow what you see. Cancelled tasks and internal task templates are never shown.

A task past its due date, or one ERPNext has marked Overdue, gets a red Overdue badge. On the board, a task that ERPNext has marked Overdue sits in Open, or in Working if hours have been logged on it. Any other late task stays in the column for its own status.

The page refreshes itself every minute while it is visible, and again when you return to the browser window.

The task drawer

Click any task to open its drawer. The ID in the header and the breadcrumb show where the task sits under its phase. The drawer holds:

• Status, due date and assignees.

• Hours meter, when the task has a budget.

• Description, as written by the team.

• Time logged: a table of date, who, the work done and hours, with a running total. A Not billed badge marks time that will not be invoiced, and In progress marks a timer that is running now. The log covers the task and all of its subtasks.

• Comments: the whole conversation on the task, including anything the team wrote in ERPNext. Replies from the team carry a Team badge.

• Files: everything attached to the task.

Press Esc to close the drawer.

What you can do

Add a task

Click New task at the top of the project. Give it a title, and optionally a phase, a priority (Low, Medium, High or Urgent) and a description. New tasks start as Open and go to the end of the phase.

You can only add tasks under an open phase, and not at all once the project is Completed or Cancelled. In that case the New task button is hidden.

Comment

Open a task, type in the editor at the bottom of the drawer and click Comment. Your comment is visible to everyone with access to the project, including the team.

The editor keeps formatting to the basics: two heading levels, bold, italic, strikethrough, bulleted and numbered lists, links, quotes and code blocks. Images cannot be pasted into a comment or description. Attach them as files instead.

Attach files

Click Attach file in the drawer. Files are stored privately and are only downloadable by people who can open that task. The portal accepts JPG, PNG, GIF, PDF, TXT, CSV, Word and Excel files (and their OpenDocument equivalents), and MP4 or MOV video, up to 25 MB per file (your site's own limit still applies on top of that). PowerPoint files and WebP images are refused. Images show a thumbnail. PDFs and images open in the browser; other types download.

Move a task between statuses

Drag a card to another column on the board, or use the Status drop-down in the drawer. Moving a task to Completed records the date and who did it; moving it back clears that. Phases cannot be moved, since they follow their tasks.

Who the team notifies

When you add a task, comment, attach a file or move a task, the team gets a Client Portal notification in ERPNext, and an email depending on each person's notification settings. The people notified are, in order of preference:

1. The people assigned to the task.

2. If nobody is, the people assigned to its parent task (its phase, for a top-level task).

3. If nobody is, the project team: the project owner, anyone assigned to the project, the project's users, and staff assigned to its open tasks.

Only enabled staff accounts are notified, and never the person who made the change. Staff who work through the portal themselves do not trigger notifications.

For admins: give a customer access

Three things must be true: the person has a login, the login is tied to the right customer or project, and the project belongs to that customer.

1. Create the user. Add a User for the client with the Customer role and the user type Website User. The portal menu entry is restricted to the Customer role.

2. Link them to the customer, using either of these:

   • Link a Contact to the project's Customer, with the person's email on the Contact (or the Contact's User field). The email is matched without regard to case.

   • Or add the user to the Customer Portal Users table on the Customer.

3. Set the project's Customer so the project falls under that link.

To give one person access to a single project without tying them to the customer, add them to the Users table on that project instead.

Customers hold no permissions on the Project or Task documents themselves. Every portal call is checked against the rules above first, and only then does it read or write on the customer's behalf. This is why a customer can comment on a task without being able to open the task in the desk.

Previewing as staff

Staff (System Users) can open /projects too. They see the projects their normal ERPNext permissions allow, and anything they change is saved with those permissions. The account menu has an Open desk entry. Use it to check what a client will see, but keep in mind that staff see more than a client does.

After installing or upgrading

Run these from the bench directory (see Bench Operations for the day-to-day bench commands). The portal's page and files are produced by the app's build, so build the assets after installing or updating the app, or /projects has nothing to show:

bench get-app https://github.com/Avunu/erpnext_taskview
bench --site <SITE_NAME> install-app erpnext_taskview
bench build --app erpnext_taskview

Install it after ERPNext. The portal page at /projects replaces ERPNext's own /projects page, and Frappe resolves website pages across the installed apps in reverse install order.

What a fresh install does

Installing the app creates the Client Portal notification type, adds a Projects entry for the Customer role to the portal menu, and redirects the old /project list to /projects. New users get Client Portal emails by default.

It does not run the app's one-time set-up patch. Frappe marks every patch of a newly installed app as already done, and bench migrate does not run it afterwards. The patch only runs on a site that had the app before the patch existed. On a fresh site, finish these by hand as a System Manager:

1. Opt existing users in to the emails. Open the Client Portal record under Notification Type and choose Actions, Enable Email Notifications for All Users. Without this, only users created from now on get the emails; everyone else can turn them on in their own Notification Settings.

2. Hide ERPNext's old Projects menu row. In Portal Settings, open the Portal Menu table and untick Enabled on the row whose route is /project. Until you do, the standard portal pages list two Projects entries.

3. Send customers to their projects after login. In Portal Settings, set Default Portal Home to /projects.

4. Remove a stale redirect, if you have one. If Website Settings, Route Redirects has a row from projects to project, delete it, because it would send customers back to the old list.

Upgrading

Update the app the way you update any Frappe app, then migrate and rebuild:

bench --site <SITE_NAME> migrate
bench build --app erpnext_taskview

bench migrate re-creates the Client Portal notification type if it is missing and applies the app's schema changes. It is what runs the set-up patch on a site that predates it, but it is not a substitute for the four steps above on a site where the app was installed fresh.

What we did not verify

• Email delivery for the notifications depends on your site's outgoing email setup and each user's notification settings, which we did not test.

• The 25 MB limit shown above is the portal's own check. The real limit on your site is whatever your site is configured to allow.

• The install steps come from reading the app's code and the source of Frappe 16 and ERPNext 16, not from a fresh install on a test site. After a major upgrade, check that a fresh install still leaves the four steps above to you.