Learning Tools Interoperability (LTI)® Access For All Personal Needs and Preferences (AfA PNP) Connector Service

Introduction

Scope and Context

This document builds upon all the concepts and terms introduced in the Learning Tools Interoperability (LTI)® 1.3 specification [[LTI-13]], specifically:

The notions of LTI Platforms and LTI Tools as participants in an LTI workflow
The interactions of messages and services.

This document defines how to obtain access to an Access For All Personal Needs and Preferences (AfA PNP) Service using the Learning Tools Interoperability (LTI)® Advantage functionality [[LTI-13]]. This provides a standard for enabling a tool to obtain the personal needs and preferences record for the user's learning activity.

The 1EdTech Access for All Personal Needs and Preferences (AfA PNP) Service 1.0 creates an API wrapper that surrounds the original AFA PNP data model [[AFAPNP-DM-30]] with a REST-based service definition using JavaScript Object Notation (JSON) payloads [[AFAPNP-RJ-10]]. The original Access For All Specification (AfA) is intended to promote an inclusive user experience by enabling the matching of the characteristics of resources to the needs and preferences of individual users.

Conformance Statements

Structure of this Document

The structure of the rest of this document is:

An outline description of the stucture of the rest of this document.
2. PERSONAL NEEDS & PREFERENCES (PNP) SERVICE	An overview of the AfA PNP service, see [[AFAPNP-SM-10]], and the corresponding REST/JSON binding [[AFAPNP-RJ-10]].
3. PROVIDING PNP INFORMATION USING LTI	Explanation of how this new LTI Advantage service makes use of the LTI Advantage Core functionality to enable access to an AfA PNP server (access to the server.
4. PNP SERVICE CONNECTOR CLAIMS IN LTI MESSAGES	Definition and description of the new custom claims that are used in the LTI launch mesage to provide access to the corresponding AfA PNP service.
5. BEST PRACTICES	The best practice RECOMMENDATIONS for LTI Advamntage Platforms and/or Tools that support the LTI AfA PNP Connector Service functionality.
6. CONFORMANCE & CERTIFICATION	The certification process and conformance requirements for LTI Advantage certified Platforms or Tools to become certified for the LTI AfA PNP Connector Service.
APPENDIX A – REVISION HISTORY	History of the various published versions of this document. This includes details of the changes made with respect to the previously published version.
APPENDIX B – REFERENCES	The details of the set of documents cited within this document.
APPENDIX C – LIST OF CONTRIBUTORS	The people who were responsible for the creation of this document.

Acronyms

AfA: Access for All
ASL: American Sign Language
AT: Assistive Technology
DRD: Digital Resource Description
HTTPS: Secure HyperText Tranport Protocol
LTI: Learning Tools Interoperability
JSON: JavaScript Object Notation
JWT: JSON Web Token
PNP: Personal Needs & Preferences
REST: Repesentational State Transfer
TLS: Transport Layer DSecurity
URI: Uniform Resource Identifier
URL: Uniform Resource Locator

Personal Needs & Preferences (PNP) Service

The information presented in this Section is taken for the formal service definition documents [[AFAPNP-SM-10]] and [[AFAPNP-RJ-10]]. The aim of the repetition of this material herein is to identify the changes to the service and data models when access is enabled through an LTI launch to the Tool requiring the AfA PNP records. Therefore, reference to the source service documents is essential when using the actual AfA PNP Service.

Overview of the PNP Service

The set of endpoints defined in the AfA PNP Service is listed in the following Table. When access is enabled via an LTI launch ONLY the getAfAPNPRecordForUserForActivity endpoint is available.

The Set of REST Endpoints and the URL-leaf Values.
Service Call	REST Endpoint	HTTP Verb	Available in LTI
getAfAPNPRecordForUserForActivity	/users/{userSourcedId}/activities/{activitySourcedId}/afapnprecords Get the AfA PNP record for the identified user (`userSourcedId`) undertaking the identifiy learning activity (`activitySourcedId`).	GET	Yes
getAfAPNPRecordSetForUser	/users/{userSourcedId}/afapnprecords	GET	No
getAllAfAPNPRecords	/afapnprecords	GET	No

The corresponding points to be noted due to the availability of this single endpoint are:

The ONLY scope that MUST be used or that is permitted, excluding an proprietary extensions, when using an LTI launch is https://purl.imsglobal.org/spec/afapnp/v1p0/scope/afapnprecord.lti.readonly
The ONLY query parameter that is permitted is fields which enables the consumer to identify the set of properties that MUST ONLY be returned
While the use of access tokens is REQUIRED, the mechanism by which the access token is obtained for LTI-enabled access is different from the original service definition;
All of the paths MUST also contain, as the base of the path, excluding the host name, the string: "/ims/afapnp/v1p0"
The OpenAPI files (JSON and YAML versions) are available at:-
- https://purl.imsglobal.org/spec/afapnp/v1p0/schema/openapi/imsafapnpv1p0_openapi3_v1p0p0.json
- https://purl.imsglobal.org/spec/afapnp/v1p0/schema/openapi/imsafapnpv1p0_openapi3_v1p0p0.yaml
respectively
The JSON Schema files for the validation of the JSON payloads for the getAfAPNPRecordForUserForActivity endpoint are available at:-
- https://purl.imsglobal.org/spec/afapnp/v1p0/schema/jsd/afapnpservicev1p0-getafapnprecordforuserforactivity-200-responsepayload-schemav1p0p0.json
- https://purl.imsglobal.org/spec/afapnp/v1p0/schema/jsd/afapnpservicev1p0-getafapnprecordforuserforactivity-default-400-401-403-404-429-500-responsepayload-schemav1p0p0.json

Overview of the AfA PNP Service Data Model

The schematic diagram "AccessForAllPNP Record" data model is shown in the UML Figure below. The full definition for all of these properties is available in [[AFAPNP-SM-10]].

UML diagram of the AfA PNP record. — AfA PNP record definition.

The definition for each property is:

access-mode-required - access mode that a user seeks either in an adaptation or an original resource as a replacement for a different access mode. This attribute relates an existingAccessMode to an access mode that the user prefers, called an adaptationRequest.
adaptation-type-required - nature or genre of the adaptation required as a replacement for a specific access mode. This attribute relates an existingAccessMode to an adaptation type that the user prefers, called an adaptationRequest.
at-interoperable - a preference for resources which are compatible with assistive technologies. Resources that are interoperable with AT should be selected whenever possible.
educational-complexity-of-adaptation - a preference for a resource that is simplified or enriched relative to another resource that presents the same intellectual content.
hazard-avoidance - a resource having such a characteristic should not be delivered to a user with this preference.
input-requirements - single input system that is sufficient to control a resource.
language-of-adaptation - a preference for the language of the adaptation [[RFC4646]].
language-of-interface - a preference for the language of the user interface [[RFC4646]].
adaptation-detail-required - this attribute relates an existingAccessMode to an adaptation detail that the user prefers, called an adaptationRequest.
adaptation-media-required - this attribute relates an existingAccessMode to an adaptation media that the user prefers, called an adaptationRequest.
educational-level-of-adaptation - a preference for the education level of the adaptation.
linguistic-guidance - additional definitions or explanations are associated with the content to assist users who are not fluent readers of the language in which the content is written.
keyword-emphasis - certain words are designated in the content as key words. Programs should designate how they are to be emphasized.
keyword-translation - certain specific words would have translations available to users who need some assistance with difficult or important words in the content. The user profile should specify the language requested and the content would supply translation for the required languages.
simplified-language-portions - an entirely different version of a question may be given to a user using simpler language.
simplified-graphics - an entirely different version of a question may be given to a user using simpler graphics.
item-translation - an alternate item is made and the user exposed to the alternate language version. The Item information must contain which specific language it supports.
sign-language - animated or live action movie recordings can be provided to the user as either an ASL translation or Signed English version of the Item.
encouragement - some users may benefit from receiving expressions of encouragement as they work on the Test/Item.
additional-testing-time - if a test has a time limit, the user will be allowed additional time to complete the test.
line-reader - describes the preferences for the use of a line reader.
magnification - describes the use of the magnification settings for the user.
spoken - describes the settings for use of Speech devices.
tactile - describes the settings for use of tactile devices.
braille - describes the settings for use of Braille devices.
answer-masking - various types of content masking are possible to limit the amount of content rendered when an item is first presented.
keyboard-directions - directions that supply information about how to control an interaction using a keyboard, which may include specific keyboard shortcuts (combinations of key strokes that perform a specific function).
additional-directions - provides supplemental content that contains additional directions. Generally used as a cognitive support for some users that might benefit from some additional context, or specific guidance on how they might proceed through the content/problem/interaction. Note that this is distinct from keyboard directions, or directions for a specific support (like screen-reader).
long-description - an alternative text that is longer than a few sentences, generally used to describe a non-text object that requires a longer description than alternative text, and/or might require text formatting (headings, tables, lists, etc.).
captions - synchronized visual and/or text alternative for both speech and non-speech audio information needed to understand the media content (from WCAG2).
environment - contains information about the physical space which the candidate occupies, including the space itself, anything that should or should not be in that space, the social environment, medicines, software, hardware, machines, and whether the candidate will be taking breaks (usually referring to assessment breaks)
transcript - a non-synchronous written alternative for time-based media content, which includes dialogue (including the speaker name/role) and descriptions of sounds and/or important information that is presented visually.
alternative-text - text that is programmatically associated with non-text content and that serves the equivalent purpose (from WCAG 2.0). Adding alternative text to an image is commonly done by using the alt attribute on an image (img) tag. It is intended to be a short description of the object.
audio-description - narration added to a soundtrack to describe important visual details that cannot be understood from the main soundtrack alone (from WCAG 2.0). Audio-descriptions can be useful for video-only media, or synchronized media (video and audio) content.
high-contrast - a resource offering an alternative visual version of another resource, with visual presentation of text and images of text that has a contrast ratio of at least 7:1, or, for larger text, a contrast ratio of at least 4.5:1 (WCAG2 Guidelines).
layout-single-column - indicates that the user requests that the content be displayed in a single column of text when possible.
text-appearance - used to define the set of characteristics that describe the appearance of displayed text.
calculator-on-screen - presence of this attribute makes available, on screen, the calculator tool.
dictionary-on-screen - presence of this attribute makes available, on screen, the dictionary tool.
glossary-on-screen - presence of this attribute makes available, on screen, the glossary tool.
thesaurus-on-screen - presence of this attribute makes available, on screen, the thesaurus tool.
homophone-checker-on-screen - presence of this attribute makes available, on screen, the homophone checker tool.
note-taking-on-screen - presence of this attribute makes available, on screen, the note taking tool.
visual-organizer-on-screen - presence of this attribute makes available, on screen, the visual organizer tool.
outliner-on-screen - presence of this attribute makes available, on screen, the outliner tool.
peer-interaction-on-screen - presence of this attribute makes available, on screen, the peer interaction tool.
spell-checker-on-screen - presence of this attribute makes available, on screen, the spell checker tool.
activate-at-initialization-set - used to define the set of features that MUST be activated during initalization of the system i.e. the default settings at the start of the learning activity.
activate-as-option-set - used to define the set of features that MAY be activated during the learning activity by the user i.e. features that the user can may available.
prohibit-set - used to define the set of features that MUST be prohibited during initalization of the system i.e. the features that will not be available during the learning activity.
extensions - permits the use of proprietary properties. The form of the extension is dependent on the type of binding.

Providing PNP Information Using LTI

AfA PNP Endpoint Service Workflow Overview

The general workflow around the Caliper Endpoint involves these two general steps:

The platform, in an LTI message (most commonly, the resource link request message described in the LTI 1.3 Core specification [[!LTI-13]] provides a new https://purl.imsglobal.org/spec/lti-afapnp/claim/afapnp-endpoint-service claim that comprises the details of the AfA PNP Endpoint that the tool will use.
The tool requests an access token from the platform's authorization service to use the service. With this access token, the tool can then obtain the corresponding AfA PNP record(s) the endpoint.

Communicating the Availability of the Service

The platform MUST communicate the availability of the AfA PNP Connector Service in every LTI message where the service is relevant. Where use of the service is not relevant (for example, if a tool does not support accessibility capabilities), the platform MUST NOT include the availability information in any LTI messages.

The platform MAY change the afapnp_endpoint_hosturl value when it deems necessary; therefore, by best practice, the tool should check with each message for the AfA PNP Endpoint URL to use for reporting on activity. By best practice, the platform should maintain the presence of the AfA PNP Endpoint URL communicated within a message for some length of time, as tools may delay some time after the user actually completed activity before sending events related to the activity.

Using the Service

To use the service, the tool MUST acquire a properly scoped authorization token, and must include it in requests to the service, as defined in the 1EdTech Security Framework [[SEC-11]] document. As with both the core LTI and AfA PNP Service specifications, this specification requires the use of HTTPS (with TLS) with all interactions with the AfA PNP endpoints.

Obtaining the access tokens for the AfA PNP follows the process used by all similar services supplied by an LTI Platform. Access tokens MUST protect all the services described by the platform; tools MUST retrieve these access tokens using the JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants as specified in the 1EdTech Security Framework - Section 4.1.1 Using JSON Web Tokens with OAuth 2.0 [[SEC-11]]. Acquisition of an access token requires three pieces of information:

Authorization server endpoint - the endpoint URL from which the access token will be obtained (this is also used as the value for the aud claim
OAuth 2 Client Id for the Tool - this is also used as the iss and sub values in the client assertion JWT.

All of the above data MUST be issued by the LTI Platform during registration.

A resource server, e.g. platform instance, is uniquely identified by its issuer, client_id, and deployment_id. Therefore when requesting an OAuth 2 bearer token the client i.e. Tool, SHOULD include the deployment_id as part of the JWT to request an access token.

PNP Service Connector Claims in LTI Messages

The optional https://purl.imsglobal.org/spec/lti-afapnp/claim/afapnp-endpoint-service claim's value contains properties about the available AfA PNP service. When including this claim in an LTI message, the sending platform, by best practice, indicates to the receiving tool that it expects the tool to obtain the AFA Record for use with this tool and the corresponding learning activity. The set of child claims are described in the Table below.

The set of claims available to provide access to the AfA PNP Service.
Claim Name	Data-type	Multiplicity	Definition
afapnp_endpoint_hosturl	String (Format=URL)	REQUIRED [1]	The endpoint from which the AFA PNP records MUST be obtained. This is ONLY the identified host i.e. the appropriate URL leaf structure as defined in the specification MUST be appended to this URL.
afapnp_activity_ids	String	REQUIRED [1..*]	The identifier(s) for the activity for which the corresponding AFA PNP record is needed. Each learning activity MAY have a different AfA PNP record.
scopes	String (Format=URI)	REQUIRED [1..*]	Access to the service MUST be controlled by the authorization scope(s) defined here. This MAY include new scopes not defined in the base specification.

An example of the set of claims is shown in the Figure below.

Example of the set of AfA PNP claims in an LTI message.


{
  
  "https://purl.imsglobal.org/spec/lti/claim/custom": {
     "https://purl.imsglobal.org/spec/lti-afapnp/claim/afapnp-endpoint-service": {
        "afapnp_endpoint_hosturl": "https://example.edu/lti/afapnp-hosturl",
        "afapnp_activity_ids": [
            "1c519ff7-3dfa-4764-be48-d2fb35a2925a"
        ],
        "scopes": [
           "https://purl.imsglobal.org/spec/afapnp/v1p0/scope/afapnprecord.lti.readonly"
        ]
     }
  }
  
}

Best Practices

ED NOTES are:

Clarify the relationship between an LTI Platform and the owner/provider of the AfA PNP Service Provider.
Add information about the definition/usage of a default PNP Record e.g. an activity identifier value of "default"? Should this default record be returned if the specified record cannot be supplied?
Clarify on how the various extension capabilities MAY be used;
Explain privacy related issues when supplying the AfA PNP records. Explain how this is addressed as part of the AfA PNP Service definition.

TO BE COMPLETED IN THE FINAL RELEASE.

Conformance and Certification

TBD...

Conformance Testing Process

The process for conformance testing implementations of LTI AfA PNP Connector Service 1.0 includes the following:

Go to the 1EdTech Conformance Test Suite for the LTI AfA PNP Connector Service. Conformance Test Suite links are available other Sections of this document;
Follow the onscreen instructions to run the tests;
Once the test has been successfully run, submit a print out of the test results along with the following information to [email protected]:
1. Your Name
2. Your Organization
3. Your Product Name and Version
4. Date the Product was tested
5. Whether the product is an LTI Platform or an LTI Tool (consumer of AfA PNP records).

All Tests for the appropriate operational modes must be passed successfully to be considered 1EdTech compliant.

NOTE: There is a separate certification process for systems that are AfA PNP Service Providers [[AFAPNP-CONF-10]].

Conformance Mark

After you have submitted your successful conformance information to [email protected], and received confirmation and a registration number from 1EdTech you may then apply the appropriate conformance mark. The 1EdTech conformance chart will list your conformance details. If you have any questions, please feel free to contact us at any point.

Membership in the LTI Advantage Alliance is the only way to achieve official conformance to the LTI AfA PNP Connector Service 1.0. Products without a 1EdTech Conformance Registration Number are not considered to be compliant by 1EdTech.

LTI Tool AfA PNP Service Connector Conformance Requirements

TO BE COMPLETED IN THE FINAL RELEASE.

LTI Platform AfA PNP Service Connector Conformance Requirements

TO BE COMPLETED IN THE FINAL RELEASE.

Version History

Publication history and revision details for this specification.
Version No.	Release Date	Comments
Candidate Final Draft 1	12th December, 2023	A draft Candidate Final release of this document. This is for review by the 1EdTech LTI and QTI Project Groups.

Abstract

Introduction

Scope and Context

Conformance Statements

Structure of this Document

Acronyms

Personal Needs & Preferences (PNP) Service

Overview of the PNP Service

Overview of the AfA PNP Service Data Model

Providing PNP Information Using LTI

AfA PNP Endpoint Service Workflow Overview

Communicating the Availability of the Service

Using the Service

PNP Service Connector Claims in LTI Messages

Best Practices

Conformance and Certification

Conformance Testing Process

Conformance Mark

LTI Tool AfA PNP Service Connector Conformance Requirements

LTI Platform AfA PNP Service Connector Conformance Requirements

Revision History

Version History