kobotoolbox: add job examples

[hunterachieng]

DO NOT MERGE UNTIL kobo 3.0 is released

Short Description

Implement job examples for kobotoolbox adaptor

Closes #970

AI Usage

Please disclose how you've used AI in this work (it's cool, we just want to
know!):

• Code generation (copilot but not intellisense)
• Learning or fact checking
• Strategy / design
• Optimisation / refactoring
• Translation / spellchecking / doc gen
• Other
• I have not used AI

You can read more details in our
Responsible AI Policy

[josephjclark]

What is the value of the fn() block in this example?

[josephjclark]

Ok that new example is great!

I think it would be nice to have another example which uses http helpers to do something a bit more weird. Something we can't do with the other APIs.

I don't know what that is. Maybe you can ask around the team for ideas? Or look at the APIs and see if you can invent something?

I wouldn't spend ages on this. I agree with @aleksa-krolls that 2 or 3 examples is ideal. But as this is a small API and for our users the use-case is surely just "I want to download some/all form submissions", there might not be much value in that.

I suppose the other thing I can think of (in the same example or a different one) is to download submissions after a certain date. You'd need to use the query strings for that which aren't well documented but I could probably help

[hunterachieng]

Ok that new example is great!

I think it would be nice to have another example which uses http helpers to do something a bit more weird. Something we can't do with the other APIs.

I don't know what that is. Maybe you can ask around the team for ideas? Or look at the APIs and see if you can invent something?

I wouldn't spend ages on this. I agree with @aleksa-krolls that 2 or 3 examples is ideal. But as this is a small API and for our users the use-case is surely just "I want to download some/all form submissions", there might not be much value in that.

I suppose the other thing I can think of (in the same example or a different one) is to download submissions after a certain date. You'd need to use the query strings for that which aren't well documented but I could probably help

I can add the example with the date filters. Let me read the docs again and will ping you if I am stuck

[aleksa-krolls]

@hunterachieng maybe an example that uses cursor? Something like the below which gets all submissions greater or equal to the cursor date.

https://kf.kobotoolbox.org/api/v2/assets/${survey.uid}/data/?format=json&query={"_submission_time":{"$gte":"${cursorDate}"}

[hunterachieng]

@josephjclark I have re-read the docs and the only other thing we can do is ordering the items such as ?ordering=date_modified

[josephjclark]

@hunterachieng what about Aleksa's suggestion? You can pass a query on get submissions

You could also use http to fetch a form I'd (maybe via another query)

[hunterachieng]

@josephjclark I have implemented the example but I used http.get since getSubmissions does not take in any options object

[josephjclark]

@hunterachieng why do we not have options in getSubmissions? The issue asks for this:

getSubmissions(formId, options) // options is { query, limit, start }

[hunterachieng]

@hunterachieng why do we not have options in getSubmissions? The issue asks for this:

getSubmissions(formId, options) // options is { query, limit, start }

I have added it back

[josephjclark]

This is cool, but

1. we ought to use cursor() to set up the cursor. This should simulate a whole job step
2. the fn block doesn't do anything

Maybe we can make this more interesting by doing:

1. getForms() to pull down all forms
2. each($.data, getSubmissions($.data.id, { query })

That then is a job that gets all submissions for all forms, using a cursor. Cool!

Also, please double check that kobo (and the template) exports cursor from common!

[hunterachieng]

Yes cursor is exported in both

[josephjclark]

Looks great to me! Thanks @hunterachieng

@aleksa-krolls as you're a bit savvier with Kobo any comments?

I don't want to merge this until the update is out, so let's keep this open but approved for now.

[aleksa-krolls]

@josephjclark made a small change to one of the comments, but otherwise looks good to merge whenever ready