Manage line items, post scores, and read results from a platform's gradebook using the Assignment and Grade Services (AGS) v2.0.
AGS has two workflows depending on the launch claim.
Coupled. The platform creates a single line item for the resource link. The tool posts scores against that line item directly.
{:ok, client} = Ltix.GradeService.authenticate(launch_context)
:ok = Ltix.GradeService.post_score(client, score)Programmatic. The tool manages its own line items and can create, update, or delete them.
{:ok, client} = Ltix.GradeService.authenticate(launch_context)
{:ok, items} = Ltix.GradeService.list_line_items(client)
{:ok, item} = Ltix.GradeService.create_line_item(client,
label: "Quiz 1", score_maximum: 100
)
:ok = Ltix.GradeService.post_score(client, score, line_item: item)Summary
Functions
Acquire an OAuth token for the grade service.
Same as authenticate/2 but raises on error.
Create a new line item.
Same as create_line_item/2 but raises on error.
Delete a line item.
Same as delete_line_item/2 but raises on error.
Fetch a single line item.
Same as get_line_item/2 but raises on error.
Fetch all line items from the container endpoint.
Same as list_line_items/2 but raises on error.
Fetch results for a line item.
Same as list_results/2 but raises on error.
Post a score for a user.
Same as post_score/3 but raises on error.
Fetch line items as a lazy stream.
Same as stream_line_items/2 but raises on error.
Fetch results for a line item as a lazy stream.
Same as stream_results/2 but raises on error.
Update a line item.
Same as update_line_item/2 but raises on error.
Functions
@spec authenticate(Ltix.LaunchContext.t() | Ltix.Registerable.t(), keyword()) :: {:ok, Ltix.OAuth.Client.t()} | {:error, Exception.t()}
Acquire an OAuth token for the grade service.
Accepts a %LaunchContext{} or any struct implementing Ltix.Registerable
(including Ltix.Registration). With a launch context, the endpoint and
scopes are extracted from the AGS claim. With a registration, pass the
endpoint via the :endpoint option, built with
Ltix.LaunchClaims.AGSEndpoint.new/1.
From a launch context
{:ok, client} = Ltix.GradeService.authenticate(launch_context)From a registration
{:ok, client} = Ltix.GradeService.authenticate(registration,
endpoint:
AGSEndpoint.new!(
line_items: "https://lms.example.com/lineitems",
scopes: ["https://purl.imsglobal.org/spec/lti-ags/scope/lineitem"]
)
)Options (launch context)
:req_options(keyword/0) - Options passed through toReq.request/2. The default value is[].:local_network_access(nil|:none|:local|:loopback) - Addresses platform requests may connect to besides public ones.:localadds private network addresses, and:loopbackadds those and this machine. Defaults toconfig :ltix, :local_network_access, then:none.:storage_adapter(module/0) - Module implementingLtix.StorageAdapter, which signs token requests. Defaults to the application configuration.:storage_adapter_options(keyword/0) - Options passed to the storage adapter's signing callbacks. The default value is[].:require_all_scopes(boolean/0) - Return aScopeMismatcherror unless every scope the endpoints need was granted. The default value isfalse.
Options (registration)
:endpoint(struct of typeLtix.LaunchClaims.AGSEndpoint) - Required. AGS endpoint struct.:deployment(term/0) - The deployment the token is for, as a struct implementingLtix.Deployableor a deployment ID. Token requests include it.:req_options(keyword/0) - Options passed through toReq.request/2. The default value is[].:local_network_access(nil|:none|:local|:loopback) - Addresses platform requests may connect to besides public ones.:localadds private network addresses, and:loopbackadds those and this machine. Defaults toconfig :ltix, :local_network_access, then:none.:storage_adapter(module/0) - Module implementingLtix.StorageAdapter, which signs token requests. Defaults to the application configuration.:storage_adapter_options(keyword/0) - Options passed to the storage adapter's signing callbacks. The default value is[].:require_all_scopes(boolean/0) - Return aScopeMismatcherror unless every scope the endpoints need was granted. The default value isfalse.
@spec authenticate!(Ltix.LaunchContext.t() | Ltix.Registerable.t(), keyword()) :: Ltix.OAuth.Client.t()
Same as authenticate/2 but raises on error.
@spec create_line_item(Ltix.OAuth.Client.t(), keyword()) :: {:ok, Ltix.GradeService.LineItem.t()} | {:error, Exception.t()}
Create a new line item.
Options
:endpoint(struct of typeLtix.LaunchClaims.AGSEndpoint) - Override the endpoint stored on the client.:label(String.t/0) - Required. Human-readable label.:score_maximum(number/0) - Required. Maximum score (must be > 0).:resource_link_id(String.t/0) - Bind to a resource link.:resource_id(String.t/0) - Tool's resource identifier.:tag(String.t/0) - Qualifier tag.:start_date_time(struct of typeDateTime) - When the line item starts accepting submissions.:end_date_time(struct of typeDateTime) - When the line item stops accepting submissions.:grades_released(boolean/0) - Hint about releasing grades.:extensions(nil|map/0) - Extension properties keyed by fully qualified URLs, given as strings or atoms. The default value is%{}.
@spec create_line_item!(Ltix.OAuth.Client.t(), keyword()) :: Ltix.GradeService.LineItem.t()
Same as create_line_item/2 but raises on error.
@spec delete_line_item(Ltix.OAuth.Client.t(), keyword()) :: :ok | {:error, Exception.t()}
Delete a line item.
Returns :ok on success.
By default, returns an error for the platform-coupled line item
(the line_item URL from the launch claim). Pass force: true
to override.
Options
:endpoint(struct of typeLtix.LaunchClaims.AGSEndpoint) - Override the endpoint stored on the client.:line_item(String.t/0| struct of typeLtix.GradeService.LineItem) - Line item URL or struct. Defaults to the endpoint'sline_item.:force(boolean/0) - Delete even if this is the coupled line item from the launch claim. The default value isfalse.
@spec delete_line_item!(Ltix.OAuth.Client.t(), keyword()) :: :ok
Same as delete_line_item/2 but raises on error.
@spec get_line_item(Ltix.OAuth.Client.t(), keyword()) :: {:ok, Ltix.GradeService.LineItem.t()} | {:error, Exception.t()}
Fetch a single line item.
Options
:endpoint(struct of typeLtix.LaunchClaims.AGSEndpoint) - Override the endpoint stored on the client.:line_item(String.t/0| struct of typeLtix.GradeService.LineItem) - Line item URL or struct. Defaults to the endpoint'sline_item.
@spec get_line_item!(Ltix.OAuth.Client.t(), keyword()) :: Ltix.GradeService.LineItem.t()
Same as get_line_item/2 but raises on error.
@spec list_line_items(Ltix.OAuth.Client.t(), keyword()) :: {:ok, [Ltix.GradeService.LineItem.t()]} | {:error, Exception.t()}
Fetch all line items from the container endpoint.
Follows all rel="next" pagination links and returns a flat list
of %LineItem{} structs.
Options
:endpoint(struct of typeLtix.LaunchClaims.AGSEndpoint) - Override the endpoint stored on the client.:resource_link_id(String.t/0) - Filter to line items bound to this resource link.:resource_id(String.t/0) - Filter by the tool's resource identifier.:tag(String.t/0) - Filter by tag.:per_page(integer/0) - Page size hint.:max_line_items(integer/0|:infinity) - Safety limit for eager fetch. Returns aCollectionTooLargeerror if exceeded. Set to:infinityto disable, or usestream_line_items/2for large gradebooks. The default value is10000.
@spec list_line_items!(Ltix.OAuth.Client.t(), keyword()) :: [ Ltix.GradeService.LineItem.t() ]
Same as list_line_items/2 but raises on error.
@spec list_results(Ltix.OAuth.Client.t(), keyword()) :: {:ok, [Ltix.GradeService.Result.t()]} | {:error, Exception.t()}
Fetch results for a line item.
GETs {line_item}/results. Follows all rel="next" pagination links
and returns a list of %Result{} structs.
Options
:endpoint(struct of typeLtix.LaunchClaims.AGSEndpoint) - Override the endpoint stored on the client.:line_item(String.t/0| struct of typeLtix.GradeService.LineItem) - Line item URL or struct. Defaults to the endpoint'sline_item.:user_id(String.t/0) - Filter results to a single user.:per_page(integer/0) - Page size hint.:max_results(integer/0|:infinity) - Safety limit for eager fetch. Returns aCollectionTooLargeerror if exceeded. Set to:infinityto disable, or usestream_results/2for large courses. The default value is10000.
@spec list_results!(Ltix.OAuth.Client.t(), keyword()) :: [ Ltix.GradeService.Result.t() ]
Same as list_results/2 but raises on error.
@spec post_score(Ltix.OAuth.Client.t(), Ltix.GradeService.Score.t(), keyword()) :: :ok | {:error, Exception.t()}
Post a score for a user.
The score is POSTed to {line_item}/scores. When no :line_item option
is given, uses the endpoint's line_item URL (coupled flow).
Options
:endpoint(struct of typeLtix.LaunchClaims.AGSEndpoint) - Override the endpoint stored on the client.:line_item(String.t/0| struct of typeLtix.GradeService.LineItem) - Line item URL or struct. Defaults to the endpoint'sline_item.
@spec post_score!(Ltix.OAuth.Client.t(), Ltix.GradeService.Score.t(), keyword()) :: :ok
Same as post_score/3 but raises on error.
@spec stream_line_items(Ltix.OAuth.Client.t(), keyword()) :: {:ok, Enumerable.t()} | {:error, Exception.t()}
Fetch line items as a lazy stream.
Returns {:ok, stream} where each element is a %LineItem{}. Use this
for large gradebooks where you want to process line items incrementally
or stop early. list_line_items/2 returns the whole list. Later page
failures and parsing errors raise during enumeration.
Options
:endpoint(struct of typeLtix.LaunchClaims.AGSEndpoint) - Override the endpoint stored on the client.:resource_link_id(String.t/0) - Filter to line items bound to this resource link.:resource_id(String.t/0) - Filter by the tool's resource identifier.:tag(String.t/0) - Filter by tag.:per_page(integer/0) - Page size hint.
@spec stream_line_items!(Ltix.OAuth.Client.t(), keyword()) :: Enumerable.t()
Same as stream_line_items/2 but raises on error.
@spec stream_results(Ltix.OAuth.Client.t(), keyword()) :: {:ok, Enumerable.t()} | {:error, Exception.t()}
Fetch results for a line item as a lazy stream.
Returns {:ok, stream} where each element is a %Result{}. Use this
for large courses where you want to process results incrementally or
stop early. list_results/2 returns the whole list. Later page failures
and parsing errors raise during enumeration.
Options
:endpoint(struct of typeLtix.LaunchClaims.AGSEndpoint) - Override the endpoint stored on the client.:line_item(String.t/0| struct of typeLtix.GradeService.LineItem) - Line item URL or struct. Defaults to the endpoint'sline_item.:user_id(String.t/0) - Filter results to a single user.:per_page(integer/0) - Page size hint.
@spec stream_results!(Ltix.OAuth.Client.t(), keyword()) :: Enumerable.t()
Same as stream_results/2 but raises on error.
@spec update_line_item(Ltix.OAuth.Client.t(), Ltix.GradeService.LineItem.t()) :: {:ok, Ltix.GradeService.LineItem.t()} | {:error, Exception.t()}
Update a line item.
PUTs the full line item to its id URL. Callers should GET first to
avoid overwriting fields they did not intend to change.
@spec update_line_item!(Ltix.OAuth.Client.t(), Ltix.GradeService.LineItem.t()) :: Ltix.GradeService.LineItem.t()
Same as update_line_item/2 but raises on error.