Documents in SharePoint¶
Language: English · Italiano · Français · Deutsch Manual index: README
Contracts, drawings, progress reports, quotes and delivery notes belong to a job, but they do not belong in the database. ProjectIQ keeps them in SharePoint, with the standard Dataverse document management: each Project, Purchase Order and Supplier Document gets its own SharePoint folder, opened from the record. Files keep SharePoint versioning, co-authoring in Office, search and sharing; ProjectIQ only stores where the folder is.
This manual is for everybody who works with project documents (part 1) and for the administrators who connect ProjectIQ to SharePoint (part 2).
How it works¶
flowchart LR
subgraph DV[ProjectIQ - Dataverse]
P[Project<br/>Purchase Order<br/>Supplier Document] -->|Regarding| L[Document location<br/>record folder]
L --> LL[Document location<br/>library]
LL --> S[SharePoint site]
end
subgraph SP[SharePoint site]
LIB[Library op365_project<br/>op365_purchaseorder<br/>op365_supplierdocument] --> F[One folder per record]
end
S -.-> LIB
L -.-> F
U[User in the app<br/>Related > Documents] --> F
A[Portfolio Agent<br/>Project documents] --> F| Table | SharePoint library | Folder |
|---|---|---|
| Project | op365_project |
One per project, named after the project and its id |
| Purchase Order | op365_purchaseorder |
One per order |
| Supplier Document | op365_supplierdocument |
One per document (for example the scanned DURC with its attachments) |
The folder is created the first time someone opens Documents on the record. Dataverse saves a document location that links the record to the folder; the agent and the app find the folder through it. A project created in Copilot from a document already has its folder, with the document in it (see Portfolio Agent).
Part 1: working with documents¶
Opening the documents of a record¶
- Open the project (or purchase order, or supplier document).
- Select Related → Documents. The first time, ProjectIQ creates the SharePoint folder of the record.
- The grid lists the files of the folder: Upload, New (Word, Excel, PowerPoint, OneNote), Open in SharePoint, Delete, Check Out / Check In and Edit Properties work directly on SharePoint.
| Command | What it does |
|---|---|
| Upload | Uploads one or more files into the folder (or a subfolder) |
| New | Creates an Office document in the folder and opens it in the browser |
| Open Location / Open in SharePoint | Opens the folder in SharePoint, for subfolders, sharing, versions and bulk moves |
| Document Location → Add Location | Links another existing SharePoint folder to the record (for example a folder in a Teams team) |
Who sees which files¶
- To see the Documents tab you need the ProjectIQ role (see Administration): OP365 User can create the folder of the records they can open and read every document location.
- SharePoint permissions decide which files you see. ProjectIQ does not copy its project sharing to SharePoint: give the project team access to the site (or to a library or folder) in SharePoint.
ProjectIQ columns¶
Every file added to the folder of a record gets the data of that record in SharePoint columns, within a few minutes, without anybody typing them. You can sort, filter and group the library by them, and Microsoft Search and Copilot use them to find "the documents of project PRJ-000123" or "the files of supplier Rossi" even when the text of the file does not say so.
| Column | Project | Purchase Order | Supplier Document |
|---|---|---|---|
| ProjectIQ Record Type | Project | Purchase Order | Supplier Document |
| Project Code | Code of the project | Code of the project of the order | – |
| Project Name | Name of the project | Name of the project of the order | – |
| Customer | Customer of the project | Customer of the project of the order | – |
| Project Manager | Project manager | Project manager of the project of the order | – |
| PO Number | – | Number of the order (PO-#####) | – |
| Supplier | – | Supplier of the order | Supplier of the document |
- The values are those of the record when the file is added: renaming a project or changing its customer does not update the files already there.
- Files outside a record folder (in the root of the library, or in a folder added with Add Location) are not tagged.
- The columns can be edited like any other SharePoint column; ProjectIQ does not overwrite them. ProjectIQ Record Id (hidden from the forms) keeps the record the file belongs to.
Documents in Copilot¶
In the Portfolio Agent ask "show the documents of PRJ-000123": the card lists the files and subfolders of the project folder, most recent first, with a link to each file and to the folder. When a SharePoint knowledge source is set, you can also ask what a document says (see Portfolio Agent).
Supplier documents¶
A Supplier Document (DURC, certification, insurance) has a File column, used by the supplier portal. When the buyer approves a document, the flow File approved supplier documents moves that file into the SharePoint folder of the record and empties the column, so the approved documents are all in SharePoint (see below). The SharePoint folder also holds the other files that go with the document (renewals, correspondence). Expiry dates and supplier compliance keep working on the Supplier Document fields as before.
Part 2: set up (administrators)¶
Done once per environment, by the Power Platform administrator with a SharePoint administrator.
flowchart TD
A[1. SharePoint site for the documents<br/>e.g. /sites/ProjectIQDocuments] --> B[2. Register the site in ProjectIQ<br/>Document Management Settings]
B --> C[3. Libraries created for<br/>Project, Purchase Order, Supplier Document]
C --> D[4. Give the project team<br/>access to the site]
D --> E[5. Users open Related > Documents]| Step | Who | What |
|---|---|---|
| 1 | SharePoint admin | Create a SharePoint team or communication site for the documents, in the same Microsoft 365 tenant as the environment |
| 2 | Power Platform admin | In the app open Settings (gear) → Advanced Settings → Document Management → Document Management Settings, select Project, Purchase Order and Supplier Document, enter the site URL, select Next and Finish. The libraries are created on the site. To add a table later, run the wizard again and select it as well: the missing library is created |
| 3 | Power Platform admin | Alternative to step 2 for scripted environments: SHAREPOINT_SITE_URL=<site URL> python3 tools/dataverse/documents.py registers the site as the default site; the libraries are then created when the first record of each table opens Documents; if a library is still missing, use step 2 |
| 4 | SharePoint admin | Give the people who use ProjectIQ at least Edit (or Read) on the site |
| 5 | Each user | Open Related → Documents on a record |
Server-based SharePoint integration is on by default in Dataverse online; if Document Management Settings reports it is off, enable it from Advanced Settings → Document Management → Enable Server-Based SharePoint Integration.
Document management on the three tables, and the document location and SharePoint site privileges of the OP365 User and OP365 Administrator roles, are part of the ProjectIQ solution: an update of the solution brings them. The SharePoint site is a setting of each environment and is not in the solution.
ProjectIQ columns on the files¶
The ProjectIQ columns are filled by three cloud flows of the solution, one per library: - Tag project documents - Tag purchase order documents - Tag supplier documents
The flows check the library every 3 minutes and use two connection references: - op365_sharepoint (SharePoint), which must belong to a dedicated user with Edit on the site; - op365_dataverse.
| Step | Who | What |
|---|---|---|
| 1 | SharePoint admin | The three libraries must exist (see Part 2). With the CLI for Microsoft 365 (npm i -g @pnp/cli-microsoft365, then m365 login) signed in as a site owner, run SHAREPOINT_SITE_URL=<site URL> python3 tools/sharepoint/document_metadata.py, with the URL registered in Document Management Settings. The script adds the missing columns to the three libraries and to their default view (ok), leaves the existing ones (skip) and prints the three ids; it can be run again |
| 2 | Power Platform admin | Set the environment variables SharePoint Site URL (op365_SharePointSiteUrl), Project Library Id, Purchase Order Library Id and Supplier Document Library Id with the site URL and the printed ids (in Test through the deployment: secrets OP365_SHAREPOINT_SITE_URL, OP365_PROJECT_LIBRARY_ID, OP365_PURCHASE_ORDER_LIBRARY_ID and OP365_SUPPLIER_DOCUMENT_LIBRARY_ID of the GitHub environment test, see dev-environment) |
| 3 | Power Platform admin | Create the SharePoint connection with the dedicated user in the environment itself, Test included: a connection is not part of the solution and does not come from Dev. Share it with the application user of the deployment (Can use). In Dev link it to op365_sharepoint. In Test do not link it by hand: put its id (in the URL of the connection page) in the secret OP365_SHAREPOINT_CONNECTION_ID and run deploy-test, which links the reference; changing the reference or the flows by hand in Test adds an unmanaged layer over the managed solution. Then turn the three flows on (Solutions → ProjectIQ → Cloud flows) |
| 4 | SharePoint admin | Optional, for the files that were already there: run step 1 again with --backfill and the PAC_* variables of the environment |
The flows are imported off: after an update of the solution check that they are still on.
Approved supplier documents in SharePoint¶
The flow File approved supplier documents starts when a supplier document becomes Approved (Approve in the app). If the document has a file in its File column, the flow:
1. finds the SharePoint folder of the record, or registers a new one (<description>_<record id>) in the op365_supplierdocument library;
2. creates the file in that folder with its original name (the Tag supplier documents flow then fills its ProjectIQ columns);
3. writes the link to the file in SharePoint URL (under File on the form, read-only and shown only once it is filled: click it to open the file);
4. removes the file from the File column. On the portal the supplier then sees Filed by your customer instead of the file.
Documents filed before SharePoint URL existed get the link to their SharePoint folder (the file name is no longer known) the first time deploy-test runs after the update.
It uses the same op365_dataverse and op365_sharepoint connection references and the SharePoint Site URL variable; the op365_supplierdocument library must exist in SharePoint and the site must be the default site of Document Management Settings (Part 2, step 2); if Dataverse has no location for the library yet, the flow registers it under that site. If the copy fails, the file stays in the File column: check the run history and run the flow again from the failed run (Resubmit), without approving again.
Messages you may see¶
| Message | Meaning and solution |
|---|---|
| No Documents under Related, or a message that document management is not configured | The site is not registered (see Part 2, step 2), or the ProjectIQ app does not contain the SharePoint Document and Document Location tables: run tools/dataverse/app.py or add the tables in the app designer and publish |
| The Documents grid says you have no permission on the location | Your SharePoint account has no access to the site or folder: ask the SharePoint administrator (step 4) |
| Access denied when the folder is created | You cannot write in the library: ask for Edit on the site |
| Card: "No document folder yet" | Nobody has opened Documents on the project: open the project in ProjectIQ and select Related → Documents |
| Card: "You have no access to the SharePoint folder of this project." | As above: SharePoint access to the site is missing |
document_metadata.py: Error: File Not Found. |
The library does not exist on the site: run Document Management Settings again and select its table (Part 2, step 2), then run the script again |
document_metadata.py: A duplicate field name "…" was found. |
The library has a column with the same id but another internal name, created by an earlier version of the script: if the column is empty, delete it from the library settings and run the script again |
| The ProjectIQ columns of a new file stay empty | The flow of the library is off or its run failed: check the flow run history; the connection of op365_sharepoint must be valid and its user must have Edit on the site |