[Building Sakai] GradebookService, which API to use?

[Ray Davis]

Wow, thanks, Michelle! :)  I think the only thing I can add is 
explaining why there are two service APIs with deprecated methods.

You'll probably be shocked to hear this: It's historical. When the 
Gradebook started out, its one and only client was Samigo (AKA Tests & 
Quizzes). That project had a pretty long history already and didn't want 
to be further destabilized; the new Gradebook project took stability and 
predictability very seriously (since most students, instructors, and 
institutions take grades very seriously) and also wanted to be driven by 
quickly modified (modulo JSF) UX design. Between us, we wanted to nail 
down carefully and early on who was doing what to reduce external 
distractions. That was the original "GradebookService" but its design 
(and a lot of its code) was very different from typical 
mimic-the-browser functionality.

As the Gradebook got deployed in more places, more external clients 
wanted to hook up with it in a "normal" way. And as the Gradebook UX 
design became more stable, it became possible to open up more services 
to external clients. After a while, it got to be pretty confusing to 
have one interface supporting two completely different approaches to 
Gradebook integration, and so we split the API up. But we didn't want to 
break old code unnecessarily, so we left the original super-up-tight 
External Assessment Service methods in the normal API definition, 
deprecated. GB2 might be a good opportunity to finally dump them. :)

Hope this helps,
Ray

On 11/13/09 6:08 AM, Wagner, Michelle R. wrote:
> Hi Steve,
> It depends what you want to accomplish with your gradebook integration. 
>  I think the comment in GradebookExternalAssessmentService.java explains 
> its purpose fairly well:
> “This service is designed for use by external assessment engines. These 
> use the Gradebook as a passive mirror of their own assignments and 
> scores,  letting Gradebook users see those assignments alongside 
> Gradebook-managed  assignments, and combine them when calculating a 
> course grade. The Gradebook application itself will not modify 
> externally-managed assignments and scores”
> 
> Thus, if you want to add assignments to the gradebook that cannot be 
> graded or edited within the gradebook tool and that adhere to your own 
> requirements (ie the gradebook won’t restrict you to its own 
> permissions, etc), use the GradebookExternalAssessmentService.  An 
> example would be in the Assignments tool when you “Add assignment to 
> gradebook.”  Grading, setting the points possible, etc must be done from 
> the  Assignments tool.  You have minimal control over this assignment 
> from the gradebook tool itself.
> 
> Again, I like the comment in the GradebookService.java API:
> “This is the externally exposed API of the gradebook application.  This 
> interface is principally intended for clients of application services -- 
>  that is, clients who want to "act like the Gradebook would" to automate 
> what  would normally be done in the UI, including any authorization 
> checks.  As a result, these methods may throw security exceptions. Call 
> the service's authorization-check methods if you want to avoid them.”
> 
> An example of this usage would be the option to “Associate with an 
> existing gradebook item” in the Assignments tool.  Via the 
> GradebookService you can add/update grades for a gradebook item that is 
> also controlled by the gradebook, but you will hit permission exceptions 
> if you don’t respect the business rules set by the gradebook.  I don’t 
> believe the GradebookService gives you access to externally-managed 
> assignments and vice versa for the GradebookExternalAssessmentService.
> 
> Let me know if you need more information.
> 
> Have a great day,
> Michelle
> 
> 
> On 11/12/09 4:25 PM, "Steve Swinsburg" <steve.swinsburg at gmail.com> wrote:
> 
>     Hi all,
> 
>      From looking at the JavaDocs for GradebookService it seems many, but
>     not all, methods have been deprecated in favour of
>     GradebookExternalAssessmentService. Is the ExternalService the
>     preferred one that external applications are meant to be using? Looks
>     like we need to use a mix of the two in order to do a full set of
>     operations on an Assignment/score?
> 
>     cheers,
>     Steve
>     _______________________________________________