Cannot develop own BackgroundTask when using Nextcloud Developer Documentation

šŸ’» Development
1

Hi,

I am trying to develop and register a own bacground task in my app. I am using the following documentation: https://docs.nextcloud.com/server/15/developer_manual/app/backgroundjobs.html

The documentation says that I have to create a static method which accesses $thisā€¦ That does not work as well as I know and it throws me the following error:
Cannot make non static method OCP\BackgroundJob\Job::run() static in class OCAā€¦

I tried to get the task started automatically by making the run() function non-static but nothing happens at all. I cannot see any logging or actions getting done by my task. I added the following section to my info.xml file

<background-jobs>
        <job>OCA\.....\Cron\SynchronizationTask</job>
    </background-jobs>

And my constructor of the task looks like this:

use OCA\.....;
use OCP\BackgroundJob\TimedJob;
use OCP\Files\Node;
use OCP\Files\File;
use OCP\Files\Folder;
use OCP\ILogger;

class SynchronizationTask extends TimedJob
{

    public function __construct(ITimeFactory $time,.......,
                                ILogger $Logger)
    {
        parent::__construct($time);

       .....

        parent::setInterval(60);
    }

Can anyone help me to get my background task running?

2

Yeah, I was struggling with this as well. In general, Iā€™m finding the docs/DX of NC a bit frustrating.

I finally figured out how to develop/debug my cron jobs by running cron.php directly, e.g.

sudo -E -u www-data php -dxdebug.remote_host=192.168.21.1 -f /var/www/html/cron.php

That should register print statements on the command line or logging messages in the logs.

To run the job again if you have errors, however, you may have to remove it from the oc_jobs table and disable/reenable the app.

Oh, and it appears the namespace should be \OC\BackgroundJob\QueuedJob, not \OCP (as stated in the docs) - at least for queued jobs on NC18.

HTH

3

Hey, Iā€™m sorry to hear that. Unfortunately for most of us who have been working with the platform for years itā€™s hard to describe these APIs in a way that they make sense for people new to Nextcloud.

Mind sharing your issues that you first encountered and what helped you understand the system better? We can try to improve the docs based on this.

1 Like
4

Sure. Here are a few of the things I found frustrating:

  1. Where are the internal API docs? For example, if I want to find all of the methods of a Node (File?) instance, or a Filesystem insance, where do I go? These docs are especially important for a large code-base that uses interfaces and a ā€œone thing per fileā€ approach. For example, to track down the the final call for generating an image thumbnail I had to traverse 7 files: Generate.php -> IPreview.php -> IProvider.php -> IProviderV2.php -> IImage.php -> Image.php -> image.php -> imagecopyresampled()
  2. Developing background tasks (as described in this issue).
  3. Developing events (or Hooks?). Hooks are deprecated but there arenā€™t any File create/update event listeners. And there seem to be two ways of using hooks - the way described in the docs, and another mysterious way I discovered Util::connectHook('OC_Filesystem', 'post_create', FileHooks::class, 'onUpdatedFile');. Only the undocumented approach worked for me.
  4. IRC was a ghost town and the forums didnā€™t help.

All that said, I still love Nextcloud and will continue to try to hack on it and improve it. Thanks for the great project with real FOSS values!

1 Like
5

Thanks.

The internal API is not documented internally because, well, itā€™s supposed to be internal and not used by the apps. If one of the public/exported APIs uses internals or there is no public API then we either have not considered this for apps nor or itā€™s missing (API bug?).

For the jobs docs I found https://docs.nextcloud.com/server/stable/developer_manual/app/backgroundjobs.html (jus tlike @jbreitung did). The run is indeed neither public nor static. Iā€™m preparing a docs update. Good catch! (edit: see https://github.com/nextcloud/documentation/pull/2157)

And regarding hooks: yeah, they are ā€¦ not great. And so we decided to go ahead and deprecate them. Weā€™re in a transition to a better events-based system. I put quite some effort into this. You can find its documentation at https://docs.nextcloud.com/server/stable/developer_manual/app/events.html. We are constantly expanding the number of available events, but weā€™re not yet covering everything. So please let us know about which specific events youā€™re missing and weā€™ll add them. This is a collaborative process. We donā€™t want to just create an event for everything but keep the API maintainable and only export things that are sensible to expose.

IRC is dead, yes. We mostly use https://cloud.nextcloud.com/call/xs25tz5y now. If the IRC is still mentioned in the docs then we should remove it.

1 Like
6

Hi, thanks @ChristophWurst for the commit to update the background jobs doc because it was really confusing.

To give some feedback, I really had some troubles to get started with Nextcloud App development because of these things:

  • Finding out how to access the filesystem and how the access management is done by the filesystem API is really tricky. It was not clear for me to realize that a filesystem view is depending on a user and fetching files by e.g. their ID also depends on a users access rights. In my case I wanted to scan the filesystem which should not depend on a specific user. That was very complicated to find out how to do itā€¦

  • Another tricky thing is loggingā€¦ Until today I did not find out how to get reliable log messages escpecially when it comes to background jobs. At the beginning I had the issue that my background job kind of stopped because of an unknown reason and it did not logged anything of an errorā€¦ I manually added more and more log messages into my job to find out the error step by step. Because of that I created an issue (https://github.com/owncloud/core/issues/37489) on GitHub to provide more information about executed background jobs during development or manual triggering.

  • Building on the point above it may generally be useful to get all information about (all) background jobsā€¦ The entities which are handled by the job worker are containing useful information which can be very helpful when trying to find out the cause of an issue.

  • The thing with the hooks documentationā€¦ You already know it, so I dont want to add something more about that.

  • It would also be very helpful for new Nextcloud App developers to get a basic ā€œCRUDā€ based example about dealing with folders and files. If you havenā€™t done it before it is really hard to find out how it works and how the Nextcloud core API wants you to work with it.

  • Besides of that, my collegue is working on an administration UI for our developed App and he is really annoyed by it. It would be very helpful to provide some basic App UI documentation which describes the main cases ā€œfile selectionā€ and ā€œCRUD with CSRF via the Apps routesā€.

Besides of all that, Iā€™ve found a very good playlist on YouTube which explaines the process of an Nextcloud App development very good for beginners: https://www.youtube.com/playlist?list=PL0ZTCrsTNYF9EnvK39wVng4WFpEdX8X0I

I really dont want to blame anyone of the Nextcloud community and the development team because I know how hard it is to maintain a documentation of a product you are very familiar with also for people who did not know anything about that product. But I think it is a good way to stay in contact together to increase the usability of the documentation :slight_smile:

Best regards!

1 Like
7

Please open a ticket about this at https://github.com/nextcloud/documentation/issues/new. This is not my area of expertise, so I also canā€™t really help with this :grimacing:

Hm. That shouldnā€™t be too tricky. Have you seen https://docs.nextcloud.com/server/stable/developer_manual/app/logging.html? Iā€™m personally a huge fan of verbose logging because itā€™s easy to adjust the log level and get LOTS of info even on a production system without having to attach a debugger. So my approach is to almost always have an ILogger injected and add as many this->logger->debug(...) statements as necessary. Those should then help you find the error more easily.

On that note it also sometimes makes sense to catch errors yourself and have custom logging. Like for background jobs donā€™t just rely on the global error handler but actively add a

try {
    // actual job logic
} catch (\Throwable $e) {
    $this->logger->logException($e, [
        'message' => 'bla bla bla failed: ' . $e->getMessage(),
        'level' => ILogger::WARN, // adjust as needed
    ]);
}

to your background job. Then the job itself will cleanly exit but youā€™ll have all the crash info in the logs with your custom error message.

Again, please open a separate ticket about this!

Is this specifically about the admin pages or the UI in general? For the former I would also appreciate a new ticket so we donā€™t lose track about it. I donā€™t think we have this documented well.

Yes, please. As I said the issues that many of us have become betriebsblind, so we donā€™t need the docs anymore to implement things and therefore completely forget about documentation. We donā€™t do this intentionally, so Iā€™m very happy about getting feedback on what is missing specifically. Thanks a lot!

1 Like
8

Hi again,

I opended the following issues on GitHub to track the suggestion of improving the developer documentation:

Is this specifically about the admin pages or the UI in general?

For our app we only need an UI for administrators but I think it would be nice to improve the documentation on a way which describes both cases.

1 Like
9

You may use GitHub - nextcloud/server: ā˜ļø Nextcloud server, a safe home for all your data instead of GitHub - owncloud/core: ā˜ ownCloud web server core (Files, DAV, etc.) the next time :wink: But I agree with their reason to close it. Use xdebug during development to check the jobs execution (itā€™s more powerful than any logging).

1 Like