POST /api/events/{event_id} endpoint does not evaluate processing or file fields

Steps to reproduce

Documentation [1] and API specification state this endpoint accepts requests with the following fields:

  • acl

  • metadata

  • presenter

  • presentation

  • audio

  • processing

However, according to the code associated with this endpoint [2], only ACL and metadata are actually processed, new/updated file(s) and/or processing instructions are ignored. Sending a request with only file(s) and/or processing instructions yields a positive (successful) response instead of an error.

This is either an error in the documentation and API specification, or the implementation was forgotten/removed.

Steps to reproduce:
Send a POST request to `/api/events/{event_id}` sending only processing instructions and/or file attachments (`presenter`, `presentation`, or `audio`

Actual Results:
Opencast returns a 204, but nothing happens.

Expected Results:
Either:

  • Opencast returns a 204, ingests file(s) and/or initiates workflow per instruction, or

  • Opencast returns a 400, saying processing instructions and/or file information cannot be processed.


Workaround (if any):
Use internal API to initiate new workflow, other than that: None.


[1] https://docs.opencast.org/develop/developer/api/events-api/#post-apieventsevent_id
[2] https://github.com/opencast/opencast/blob/develop/modules/external-api/src/main/java/org/opencastproject/external/endpoint/EventsEndpoint.java#L393

Activity

Show:
Maxime Pedrotti
July 13, 2018, 6:33 AM

Just to add my thoughts on the points Sven raises:

  • Specification error was my first thought, since I could not find anything in the Github history for the source. I just wanted to keep the possibility open for some other place to hold the implementation and the link being missing.

  • From my understanding of the mechanics of metadata and media packages in Opencast, a change in metadata is not automatically propagated towards publication channels, which is why we need workflows like "Republish metadata" and the "republish-oaipmh" WOH to affect publication channels like the engage module or the OAI-PMH repository. Plus, if one's publication branding includes generating title slides or bumpers from metadata, a new processing workflow would be needed to update the actual video files for the publication. With the current implementation, one could edit metadata for a particular event via an API client, but these changes would only extend to the external API publication (which apparently gets its data directly from the archive), but not to other publication channels. To update the metadata for other external channels (or to include dependencies like event/series branding with metadata), one needs to access the admin UI and initiate these workflows from there.

  • What should happen when an API client uploads a file with a flavor for which there already is an asset in the media package? Personally, I would welcome a solution along the line of this: Replace the existing file with the uploaded one, thus making it possible to update existing media packages in place instead of having to retract and delete the original and reupload a whole new media package. I can see several use case scenarios for this, some examples:

  • A user has made an offline edit to the source file (maybe an instructional video for a seminar, or an image film for a study programme) and wants to upload the changes while keeping the original URLs for the publication, e.g. because the video was embedded on a web site manually, not via LTI or other plugin.

  • A presentation was recorded and published, but the presentation contained copyright infringing materials, which was overlooked during the first run of editing and publishing. Instead of pulling the entire package, the user wants to just edit the relevant part of the source material locally and reupload just the presentation track.

  • Something went wrong with the (primary) recording of the presentation (e.g. distorted image, wrong colors, wrong cropping, etc.), while the camera recording worked, and both parts were successfully ingested. Luckily, there was a successful backup recording of the presentation part, or the presenter (or the service provider for the recording) decide to reenact/reedit the presentation part and now have a separate presentation video. They want to replace the existing presentation video with the correct version, without having to download the package and manually creating a new event.

  • A user has created an event via an API client, e.g. a recording of a presentation given somewhere in their home institution. Now the presenter has decided they want to retract their consent, therefore the video needs to be removed from publication. The API does provide a DELETE action, however, this does not include publication channels - to safely remove a video from publication, one needs to first retract all publications before finally removing the media package from the OC inventory (as is the workflow from the web based admin UI). Using the DELETE option from the API without checking for published artifacts can easily lead to orphaned publications which then have to be manually removed from the servers and file systems they were deployed to (maybe should be raised in a different issue).

  • A user is not happy with the encoding results and wants to try a different workflow/preset, maybe the API client is exposing a list to choose from (either selected by the admin or programmatically generated). The user could then initiate a reprocessing workflow with republication, using the API client alone.

  • From my perspective, this endpoint would be a good place to allow for workflow initiation. One point you raise yourself: Having the option to initiate a workflow with the same request that sends a new set of metadata and/or ACL could be useful. Another point would be that this actually fits the description of the endpoint, i.e. "Updates an event", which - at least in terms of publication channels and possibly media source files in a future implementation - requires a workflow to be initiated (maybe sort of a circular argument).

From my point of view, both the necessity of republishing metadata changes to different publication channels, as well as the use case scenarios for updating (or removing) media packages would warrant the need for workflow initiation via the API.

I realize my points come from a specific configuration, i.e. the main point being that users (presenters, lecturers, students, etc.) would not get access to the admin UI directly (for several reasons specific to my institution's situation and its users), but only through an API client. Other adopters/institutions may have different needs, and I may be in a minority position.

My apologies for this long comment, which turned more into a user story with feature request than a bug report. Just to finish: This all is by no means ignoring the work already put into the API implementation and the fact that you already have plans for this among other things, I just would like to make the case for this functionality stronger, not criticize the developers.

Sven Stauber
July 12, 2018, 5:52 PM

I was aware that triggering workflows is currently not supported but I was not aware that the specification says that it is.

From my point of view, that is a specification error as this never was implemented and therefore never was supported. Adding it would then be a new functionality that likely is "backwards-compatible" so should be included in a new minor version.

I would suggest to adjust the specification as there can be no client at there that uses this (as it never worked).

Not clear to me what is supposed to happen if new files are added to an existing event as this leads to problems (what is Opencast supposed to do with multiple different presenter/source, for example).

Also not clear to me whether this should be used to start workflows as starting a workflow for an existing event does not necessary need acl and metadata. Being able to specify acl and metadata while starting a workflow can be handy but also somewhat mixes up concerns. No strong opinion.

We do have the "starting workflow" on our short-term radar, but no ETA decided yet.

Greg Logan
July 12, 2018, 5:42 PM

, thoughts on this? My gut says we should be sending back a 400 for now, and fix it in a future API rev?

Your pinned fields
Click on the next to a field label to start pinning.

Assignee

Unassigned

Reporter

Maxime Pedrotti

Severity

Incorrectly Functioning Without Workaround