pibiDAV is a Frappe App to integrate webDAV, calDAV and cardDAV (Future) with a NextCloud Server used as (DMS) for a copy of Frappe Files uploaded and tagged to NextCloud while uploading files to Frappe.
MIT# pibiDAV
Requires a Frappe server instance (refer to https://github.com/frappe/frappe), and has dependencies on CalDAV (refer to https://github.com/python-caldav/caldav) and iCalendar (refer to https://github.com/collective/icalendar). It also uses a tweaked code of pyocclient but this is embedded already in pibiDAV.
PibiDAV has been tested on Frappe/ERPNext version-13 only.
From the frappe-bench folder, execute
$ bench get-app pibidav https://github.com/pibico/pibidav.git
$ bench install-app pibidav
If you are using a multi-tenant environment, use the following command
$ bench --site site_name install-app pibidav
Once is installed, be aware that you will need to set developer_mode = 1 on your site_config.json file. Also it is a must to have SSL active in both servers Frappe and NextCloud with specific certificates (wildcard .domain.com certificates are not valid for this integration). Letsencrypt Certificates are valid for both servers. This integration app is prepared for including specific and custom doctypes to upload its attachments to NextCloud at the same time than to Frappe. But for that purpose, custom fields (for Frappe Core Doctypes) or new fields in custom doctypes, are needed. These custom fields are always to be named as nc_enable, nc_folder and attachment_item, as it will be explained in next paragraphs. Also a custom script (client script) will be needed for making active the new frappe.ui.component dialog based on vue.js and called frappe.ui.pibiDocs where to draw the NextCloud Tree and select the destination NextCloud node to upload the files.
PibiCo works on NextCloud making the Main Company Folders Superestructure as a shared folder from this NextCloud SuperUser that should be a System Manager on Frappe also. Let's explain with some pictures.
This Folder Superstructure has children at different levels and are shared with different groups or users also at different level, thus giving access to these folders and below (both user internal to Company or External such as Customers or Suppliers).
At this point, let's go to Frappe Server and once logged-in as System Manager or Administrator we'll go to module pibiDAV on side menu, and on Settings Card we'll choose NextCloud Settings.
Once there, we'll activate the NextCloud Backup Enable checkbox and fill the credentials of the NextCloud SuperUser in the input fields.
We can check that our credentials are correct clicking on NC commands button on upper right side of the screen.
Now, automatic uploading of frappe backup is enabled and will be uploaded to the destination folder as given in the backups details section. Frappe Backups files are renamed on NextCloud to files beginning by a number that is the weekday of the backup files, as shown in the picture. So, we will have always the last backup and also all the ancient backups for this weekday as versions in NextCloud, as shown in the picture
It's time now of telling to Frappe which doctypes will be integrated to upload its attachments to NextCloud once they are uploaded in Frappe. This is done on the same NextCloud Settings, but on Settings Section, choosing the Frappe Doctype in the table and also giving the DocFields in that DocType that will be used to Tag Automatically the Files on Frappe and On NextCloud as well. We will choose the Sales Invoice Doctype as an example for this configuration. In this case, we will tag the files with the name, the customer and the tax_id from the customer, but whichever field in the doctype, even custom fields are valid.
To get the permissions from NextCloud into Frappe we will fill the User NextCloud Credentials on Frappe User Settings. We'll go through the user settings and will select the Role NextCloud User first.
After that we will go at the bottom of de User Settings Form to provide the NextCloud User Credentials. In this example is the System Manager or Administrator having the SuperUser NextCloud Credentials for having access to the full NextCloud Folder SuperStructure.
For CalDAV integration we will provide also othe url for the User Calendars, in the way https://domain.com/remote.php/dav/principals/ (do not forget the / at the end).
Having active the developer mode in the instance, we can go to the Customization Side Menu and create new custom fields and Client Scripts as needed to fulfill the NextCloud Integration with the selected DocTypes. In case of a custom app, this is also valid but these docfields and script will be incluced in the DocTypes and js code of our custom app.
This is our first needed custom field. In case of our Selection (Sales Invoice), the nc_enable docfield is a Check docfield to include at the beginning of the doctype form.
The second needed custom field is the Folder Destination Node selected from the NextCloud Folder Structure to upload the attachments from the Sales Invoice in this case. The nc_folder docfield is a Text type field and Read Only for filling it with very long routes (paths from the root node).
First we will create a doctype Files List of type Section Break to separate the table from the rest of the fields and located on the very bottom of the current doctype form.
The last needed docfield is a child table to get a register with the attachments uploaded from Frappe to NextCloud in the Sales Invoice Doctype, with its shared links (both internal and external links) and with a link to the Frappe File DocType where all data from NextCloud are also registered for further use. The attachment_item docfield is a Table type field pointing to childtable Attachment Item in the options property. We will locate the table at the very bottom of the Sales Invoice doctype after the last docfield.
Now it's time of the frontend logic for the Sales Invoice form. For that purpose we will create a client script on the form with the following code:
// Copyright (c) 2022, pibiCo and contributors
// For license information, please see license.txt
frappe.ui.form.on('Sales Invoice', {
refresh(frm) {
if (!frm.doc.nc_enable) {
frm.set_value("nc_folder", "");
frm.refresh_field("nc_folder");
}
},
nc_enable(frm) {
if (frm.doc.nc_enable) {
frm.set_value("nc_enable", 1);
frm.refresh_field("nc_enable");
frm.save();
new frappe.ui.pibiDocs();
}
}
});
It's time now to try the integration of the NextCloud Folder Structure from Frappe to choose the NC Destination Folder of our uploaded files (except website urls).
We will go to a Sales Invoice after saving as draft. As default the NC Enable Check is unchecked. While keeping so, the attachments to the Sales Invoice will no be uploaded to NextCloud. Thus, the user has the flexibility to decide whether a file is uploaded to NextCloud or not, and files can be uploaded to different folders just unchecking and checking again and selecting a new Destination Folder each time the nc_enable check is selected. It can be very usual that our invoices can be stored inside a Customer Folder in our NextCloud Instance under the year of the Invoice, as in the picture.
When we select the NextCloud Destination Folder in the dialog, this folder path will be filled in our text nc_folder custom field.
While we keep this destination folder, all the attachments uploaded to the Sales Invoice will be also uploaded to NextCloud to this folder. Let's create the pdf from the Sales Invoice, signed electronically outside Frappe and uploaded again as attachment in Frappe/ERPNext
We have uploaded the attachment to Frappe/ERPNext as shown in the picture
Let's Check if it has been also uploaded to NextCloud on the PBC > Customer > Client > Invoices > 2022 as selected.
Looking for details we see the pdf file Sales Invoice uploaded in NextCloud Destination, but also has been created a shared public Link, tagged with customer, tax_id, doctype and name as we defined in the Settings. Voilà, first integration achieved. Let's check the File uploaded to Frappe, it has all metadata from NextCloud as well, and also has some frappe tags also automatically filled on the upload.
Another possible integration is through a Folder Set Doctype Tree integrated in pibiDav. Folder Set is a Doctype for making Folder Structures taken as templates for recreating them in the NextCloud Instance from a destination folder as root. Let's see in action, once we have the template folder set created in Frappe. We can select the root folder and enable the nc_enable check and select the destination folder in NextCloud where to recreate this structure, renaming the folders in NextCloud upon its creation.
We select the destination folder in NextCloud browsing in the dialog.
And once selected the destination folder, on the tree we click on button Recreate to perform the copy of folders from Frappe to NextCloud.
The result is seen on the image for a new Client Structure called CUSTOMER as abbreviation and Customer Name Details as Description for the Folder.
This portion is explained in pibiCal (refer to https://github.com/pibico/pibical/tree/version-13) The code from pibiCal has been integrated into pibiDav to achieve the syncronization between Frappe and NextCloud CalDAV Server.