Gravity Forms Nextcloud Premium Add-on Setup Guide

The Gravity Forms Nextcloud Premium Add-on sends the files that visitors upload through Gravity Forms, and optionally the PDFs that are made from an entry, to your own Nextcloud or ownCloud server. It talks to the server over WebDAV with a user name and an app password: it creates the folders, uploads each file, asks the server to confirm that the file arrived with the right size, and can ask for a public share link. Nothing goes through GravityExtra or any other third party.

This guide explains the setup, every option, what happens when something fails, and what the add-on does and does not do.

What you need

• WordPress 6.5 or newer and PHP 7.4 or newer.
• Gravity Forms 2.9 or newer. The add-on is tested with Gravity Forms 3.1.2 on PHP 8.3 and Gravity Forms 2.9.8 on PHP 7.4.
• A Nextcloud or ownCloud server that your WordPress site can reach over https, and an account on it with an app password.
• Optional: a PDF plugin for Gravity Forms if you want to send generated PDFs. The add-on reads the PDF templates of the Gravity PDF plugin, and any other PDF tool can add files through a filter.

If Gravity Forms is missing or older than 2.9, the add-on shows a notice in the WordPress admin and does nothing else.

Install and connect

1. Install and activate the add-on like any plugin, after Gravity Forms.
2. Open Forms → Settings → Nextcloud and enter your license key.
3. In your Nextcloud or ownCloud open Personal settings → Security, type a name for a new app password such as the name of your website, and press create. Copy the password that is shown.
4. Back in WordPress, in the section Nextcloud or ownCloud server, choose the server type, enter the server address, your user name and the app password, and save.
5. Press Test connection. The add-on asks your server for the top folder of the account. Nothing is created or uploaded by the test.

Server type and address

The server address is what you type in the browser to open your cloud, for example https://cloud.yourcompany.com or https://yourcompany.com/nextcloud when it lives in a sub folder. Only https addresses are accepted, without a user name, a query or spaces. The add-on adds the WebDAV path for the files of the account itself: /remote.php/dav/files/ followed by your user name, which is the path both Nextcloud and ownCloud use.

Choose Other WebDAV server if you use another WebDAV service. The address is then the WebDAV folder itself, and the add-on does not ask for share links because that part belongs to the Nextcloud and ownCloud sharing interface.

How the app password is kept

The app password is stored encrypted in the WordPress database, with a key that is derived from your site’s secret keys in wp-config.php. It is never shown again after you save it: the field stays empty, a line under it tells you that a password is saved, and leaving the field empty keeps the saved one. To remove it, tick Delete the stored app password when I save. Use an app password rather than your normal password: you can revoke it in your cloud at any time without changing anything else, and it works when two-factor sign-in is on.

If you prefer to keep the credentials out of the database altogether, define the constants GFNEXTCLOUD_URL, GFNEXTCLOUD_USERNAME and GFNEXTCLOUD_PASSWORD in wp-config.php, and optionally GFNEXTCLOUD_TYPE. They win over the settings screen. If you change the secret keys of your site, the saved app password can no longer be read and you type it again.

Largest file to send

The setting Largest file to send (MB) is 50 by default and can be raised to 200. A file is sent in one request, so keep the value below the upload limits of your PHP and of your cloud server. A file that is bigger stays on your WordPress server and the entry gets a note that says so.

Create a feed

The add-on works with Gravity Forms feeds, so every form can have one or several Nextcloud feeds. Open the form, go to Settings → Nextcloud and add a feed. The feed list asks for the server settings first when they are not saved yet.

Which files

Tick the File Upload fields to send. Single and multiple file fields both work. A feed can have a condition, as every Gravity Forms feed can: for example send the files only when a drop-down says Customer. If the Gravity PDF plugin is active, its templates for the form are listed as Generated PDFs to send; the add-on makes the PDF for the entry and sends it like any other file. Other PDF tools can add files with the filter described below.

Where they go on your server

• Folder on the server: a path inside the files of the account, with tokens {form_id}, {form_slug}, {field_id}, {entry_id}, {Y}, {m} and {d}. The default is Gravity Forms/{form_slug}/{Y}/{m}. Letters, digits, space, dot, dash, underscore and brackets only; anything else is replaced and dot-dot paths are dropped. Missing folders are created one level at a time.
• File names on the server: the original name plus a short random ending (the safe default), the original name only (a short ending is added only when that name is already taken), or a random name that hides the original. A file that is already on the server is never replaced.

Public share links

Turn on Create a public share link and the add-on asks your server, through the Nextcloud and ownCloud sharing interface, for a read-only public link to each file. You can set the number of days after which the link expires; empty or 0 means it does not expire. Anyone who has the link can read the file, so use it for files that may be shared that way, and remember that your server administrator can switch public links off. If the server refuses the link, the file is still stored and the note tells you why.

The entry and your WordPress server

• Store the share link in the entry (needs the share link, default off): the value of the file field becomes the public link, in the same form as before (a single link or a list). The entries list, the entry screen, exports, notifications and every other add-on then show the link. Off: the entry keeps the link to your WordPress server and the cloud links are available through the Nextcloud box, the notes and the merge tags.
• Delete the local copy (needs the stored share link, default off): the file is removed from your WordPress server, but only after the cloud confirmed that it holds a file of the right size and the entry already has the public link. A file that failed to upload, or whose link could not be created, is never removed.

What a visitor and you will see

The visitor fills in the form and sends it as always. The upload happens while the form is processed, before the notifications are sent, so a large file adds a little time to the submission. If your server is slow or down, the visitor still sees the confirmation: the file stays on your WordPress server and the entry gets a note.

For every file the add-on makes the folders, sends the file, and then asks the server about the file it just wrote. If the size on the server is not the size that was sent, the file is deleted again from the cloud, kept locally and reported. On the entry screen a box named Nextcloud lists every file with its size and a link, and a note says Nextcloud: 1 file sent and checked. or lists the files that were not sent and why.

The link in the box is the public share link when there is one. Otherwise it is a link to the folder in the Files app of your cloud, which needs a sign-in.

Send files again

The Send files again button on the entry screen runs the active feeds of the form once more for that entry. Files that were already sent are skipped, so pressing it twice never uploads a file twice. Use it after you fixed a wrong password or after an outage, and to send the files of entries that were submitted before the add-on was installed.

Merge tags and developer functions

• {nextcloud_url}: the first link of the entry. {nextcloud_urls}: all links, separated by a comma and a space. The link is the public share link when one was made, else the link to the folder.
• {nextcloud_url_3} and {nextcloud_urls_3}: the same for the field with the id 3. Generated PDFs are listed under field 0 and appear in the tags without a field id.
• gfnextcloud_get_files( $entry_id ) returns the saved records of an entry: path, name, size, file id, share link and folder link. gfnextcloud_get_urls( $entry_id, $field_id ) returns the links.
• gfnextcloud_extra_files: a filter that lets another plugin add files to a feed. Return a list of items with a unique source, a name, an absolute path of a local file and optionally temp set to true to have the file removed after it was sent.
• gfnextcloud_target_folder: a filter to change the folder of one file. gfnextcloud_allow_http: a filter, or the constant GFNEXTCLOUD_ALLOW_HTTP, for a server on a trusted local network that has no https. Passwords then travel unencrypted, so use it only on a network you control.

How the upload works

The add-on uses the WebDAV interface of the files of the account. MKCOL creates each folder level (an answer that says the folder exists is fine), PUT uploads the file with a SHA-256 checksum header that the server verifies, the modified time of the file, and a condition that refuses to replace an existing file. PROPFIND then reads the size of the new file, and the add-on compares it with what it sent. The public link, when asked for, is one call to the sharing interface with the read-only permission. All requests use https with certificate checking, never follow redirects, and send the user name and app password in a Basic authentication header.

Privacy and security

• Files go from your WordPress server to your cloud over https. Nothing is sent to GravityExtra or to anyone else.
• Only files inside the Gravity Forms upload folder, and the PDFs and filter files that are made for the entry, are sent. The real path of each file is checked before it is read.
• The app password is encrypted at rest, is never shown again, and never appears in notes, logs or error texts. Only people who may edit Gravity Forms settings can test the connection, and only people who may edit entries can press Send files again; both use a nonce.
• Error texts from your server are cleaned to plain text and cut short before they are saved in a note.
• Public links give read access to anyone who has the link. Use an expiry date for sensitive files.

Troubleshooting

• Nothing is sent: check the license, that the server settings are saved, that the feed is active and its condition is met, and that the feed has a File Upload field ticked.
• HTTP 401: the user name or the app password was refused. Create a new app password and save it.
• HTTP 404 on the folder: the server address or the user name is wrong, or the address needs its sub folder.
• HTTP 507: the account is out of storage space.
• HTTP 503: the cloud is in maintenance mode or busy.
• The server redirected the request: use the exact https address, with or without www as your cloud expects, because redirects are never followed.
• No share link: the administrator of the cloud may have switched public links off, or the account may not share files. The note shows the reason the server gave.
• A note about the size: the file arrived with a different size than it was sent with. The file stays on your WordPress server; check the upload limits and any proxy in front of your cloud and send it again.

Questions

Does it work with ownCloud?

Yes. Choose ownCloud as the server type. It uses the same files address and the same sharing interface as Nextcloud. The add-on follows the documented interfaces of both products and is tested against a stand-in server that behaves as those documents describe.

Do I need to install anything on my cloud?

No. The add-on only uses what a standard Nextcloud or ownCloud already offers: an account, an app password and WebDAV.

Does it work with several files in one field?

Yes. Every file is its own upload, and a list value is rewritten as a list of links when you store the share links in the entry.

What happens to files that were uploaded before I installed the add-on?

Nothing automatically. Open an old entry and press Send files again to send its files.

Will my visitors wait for the upload?

The upload runs while the form is processed, so a very large file makes the submission a little slower. Keep the largest file setting at a value that suits your hosting.

Can the add-on delete or change files on my cloud?

No. It creates folders and uploads new files, and it removes a file only when it has just uploaded it and the size check failed.

Which Gravity Forms versions does it support?

Gravity Forms 2.9 and newer. It is tested with Gravity Forms 3.1.2 on PHP 8.3 and Gravity Forms 2.9.8 on PHP 7.4.