Skip to content

Latest commit

 

History

History
171 lines (119 loc) · 8.69 KB

submission-review-workflow.md

File metadata and controls

171 lines (119 loc) · 8.69 KB
Raw

Submission Review Message Workflow

How to perform secured submission review message interactions, between platforms and tools.

Workflow

You can find below a submission review message workflow diagram, with steps numbers:

Submission Review Workflow

Each step will be detailed below, from both platform and tool perspectives.

Table of contents

1 - Platform side: LtiSubmissionReviewRequest message generation

You can find below required steps to generate a LtiSubmissionReviewRequest message, needed only if you're acting as a platform.

Create the message

As a platform, you can create a LtiSubmissionReviewRequest message for a tool within the context of a registration.

Platforms can drive the tool behaviour on submission review interactions by providing claims in this message.

You can use the SubmissionReviewLaunchRequestBuilder to create the message:

<?php

use OAT\Library\Lti1p3Core\Message\Payload\Claim\AgsClaim;
use OAT\Library\Lti1p3Core\Message\Payload\Claim\ForUserClaim;
use OAT\Library\Lti1p3Core\Registration\RegistrationRepositoryInterface;
use OAT\Library\Lti1p3SubmissionReview\Message\Launch\Builder\SubmissionReviewLaunchRequestBuilder;

// Create mandatory submission review claims
$agsClaim = new AgsClaim(...);
$forUserClaim = new ForUserClaim(...);

// Create a builder instance
$builder = new SubmissionReviewLaunchRequestBuilder();

// Get related registration of the launch
/** @var RegistrationRepositoryInterface $registrationRepository */
$registration = $registrationRepository->find(...);

// Build LtiSubmissionReviewRequest message
$message = $builder->buildSubmissionReviewLaunchRequest(
    $agsClaim,                                                     // [required] AGS claim
    $forUserClaim,                                                 // [required] for_user claim
    $registration,                                                 // [required] related registration
    'loginHint',                                                   // [required] login hint that will be used afterwards by the platform to perform authentication
    'http://tool.com/submission-review',                           // [optional] tool url where to send the LtiSubmissionReviewRequest message (if none provided will use default tool launch url)
    null,                                                          // [optional] will use the registration default deployment id, but you can pass a specific one
    ['http://purl.imsglobal.org/vocab/lis/v2/membership#Learner'], // [optional] roles
    ['myCustomClaim' => 'myCustomValue']                           // [optional] supplementary claims if needed
);

Since AGS line items can be coupled to LTI resource links, you can also use the buildLtiResourceLinkSubmissionReviewLaunchRequest() method to ease the message creation:

<?php

use OAT\Library\Lti1p3Core\Message\Payload\Claim\AgsClaim;
use OAT\Library\Lti1p3Core\Message\Payload\Claim\ForUserClaim;
use OAT\Library\Lti1p3Core\Registration\RegistrationRepositoryInterface;
use OAT\Library\Lti1p3Core\Resource\LtiResourceLink\LtiResourceLink;
use OAT\Library\Lti1p3SubmissionReview\Message\Launch\Builder\SubmissionReviewLaunchRequestBuilder;

// Create a resource link
$resourceLink = new LtiResourceLink('resourceLinkIdentifier');

// Create mandatory submission review claims
$agsClaim = new AgsClaim(...);
$forUserClaim = new ForUserClaim(...);

// Create a builder instance
$builder = new SubmissionReviewLaunchRequestBuilder();

// Get related registration of the launch
/** @var RegistrationRepositoryInterface $registrationRepository */
$registration = $registrationRepository->find(...);

// Build LtiSubmissionReviewRequest message
$message = $builder->buildLtiResourceLinkSubmissionReviewLaunchRequest(
    $resourceLink,                                                 // [required] resource link
    $agsClaim,                                                     // [required] AGS claim
    $forUserClaim,                                                 // [required] for_user claim
    $registration,                                                 // [required] related registration
    'loginHint',                                                   // [required] login hint that will be used afterwards by the platform to perform authentication
    'http://tool.com/submission-review',                           // [optional] tool url where to send the LtiSubmissionReviewRequest message (if none provided will use default tool launch url)
    null,                                                          // [optional] will use the registration default deployment id, but you can pass a specific one
    ['http://purl.imsglobal.org/vocab/lis/v2/membership#Learner'], // [optional] roles
    ['myCustomClaim' => 'myCustomValue']                           // [optional] supplementary claims if needed
);

Launch the message

As a result of the build, you get a LtiMessageInterface instance that has to be used in the following ways:

<?php

use OAT\Library\Lti1p3Core\Message\LtiMessageInterface;

/** @var LtiMessageInterface $message */

// Main message properties you can use as you want to offer the launch to the platform users
echo $message->getUrl();                // url of the launch
echo $message->getParameters()->all();  // array of parameters of the launch

// Or use those helpers methods to ease the launch interactions
echo $message->toUrl();                // url with launch parameters as query parameters
echo $message->toHtmlLink('click me'); // HTML link, where href is the output url
echo $message->toHtmlRedirectForm();   // HTML hidden form, with possibility of auto redirection

Implement OpenId Connect launch flow

Like any platform originating message, when the LtiSubmissionReviewRequest message is launched, an OIDC flow will start between the tool and the platform.

The underlying core library offers everything you need to securely implement this flow, as documented in the platform originating messages documentation.

2 - Tool side: LtiSubmissionReviewRequest message handling

You can find below required steps to handle a LtiSubmissionReviewRequest message, needed only if you're acting as a tool.

Validate the message

As a tool, you'll receive an HTTP request containing the LtiSubmissionReviewRequest message, generated by the platform, received after OIDC flow completion.

You can use the ToolLaunchValidator to validate it:

<?php

use OAT\Library\Lti1p3Core\Message\Launch\Validator\Tool\ToolLaunchValidator;
use OAT\Library\Lti1p3Core\Registration\RegistrationRepositoryInterface;
use OAT\Library\Lti1p3Core\Security\Nonce\NonceRepositoryInterface;
use Psr\Http\Message\ServerRequestInterface;

/** @var RegistrationRepositoryInterface $registrationRepository */
$registrationRepository = ...

/** @var NonceRepositoryInterface $nonceRepository */
$nonceRepository = ...

/** @var ServerRequestInterface $request */
$request = ...

// Create the validator
$validator = new ToolLaunchValidator($registrationRepository, $nonceRepository);

// Perform validation
$result = $validator->validatePlatformOriginatingLaunch($request);

if (!$result->hasError()) {
    // You can access the related AGS line item
    $lineItemUrl = $result->getPayload()->getAgs()->getLineItemUrl();
    
    // You can access the user details for whom is done the submission review
    $user = $result->getPayload()->getForUser();
    
    // Then implement your logic to handle the LtiSubmissionReviewRequest message and offer submission review
}

Note: more details about platform originating messages on tool side validation can be found in the platform originating messages documentation.