[LON-CAPA-cvs] cvs: loncom /html/adm/help/tex Course_Prefs_ExternalTools.tex Docs_Adding_External_Tool.tex Domain_Configuration_LTI_Tools.tex
raeburn
raeburn at source.lon-capa.org
Mon Jun 16 13:01:11 EDT 2025
raeburn Mon Jun 16 17:01:11 2025 EDT
Modified files:
/loncom/html/adm/help/tex Course_Prefs_ExternalTools.tex
Domain_Configuration_LTI_Tools.tex
Docs_Adding_External_Tool.tex
Log:
- Document options for "Destination URL which differs from launch URL" and
"Return URL sent on launch" in External Tool definition and configuration
of each tool instance.
-------------- next part --------------
Index: loncom/html/adm/help/tex/Course_Prefs_ExternalTools.tex
diff -u loncom/html/adm/help/tex/Course_Prefs_ExternalTools.tex:1.1 loncom/html/adm/help/tex/Course_Prefs_ExternalTools.tex:1.2
--- loncom/html/adm/help/tex/Course_Prefs_ExternalTools.tex:1.1 Thu Jan 25 19:19:52 2024
+++ loncom/html/adm/help/tex/Course_Prefs_ExternalTools.tex Mon Jun 16 17:01:11 2025
@@ -2,11 +2,11 @@
The domain coordinator for your domain can choose to enable definition and configuration of External Tools by course type, or for specific course(s). If tool definition is available in your course you will be able to use: Settings $>$ Course Settings $>$ Display (``External Tools'' checked) to create new External Tool definitions for use in your course, or to modify existing ones.
-Note: External Tools may also have been defined at a domain level for use in your course. If the tool you want to use is already available then you do not need to define your own, but can simply click``External'' in the function categories listed at the right side of the Course Editor, below the editor tabs, and then click ``External Tool''. From there you'll choose `` Defined in domain'' and select the tool to add. If the tool you want to use is not available at a domain level, then after you have defined the tool (see below) clicking the ``Defined in course'' option will allow you to add an instance of that tool to the folder currently being edited. Tools added to the ``Supplemental content'' area will not store grades passed back from the Provider. If you wish to use that functionality you should add a tool instance to a folder or sub-folder in the ``Main Content'' area, and check ``Yes'' for Gradable.
+Note: External Tools may also have been defined at a domain level for use in your course. If the tool you want to use is already available then you do not need to define your own, but can simply click ``External'' in the function categories listed at the right side of the Course Editor, below the editor tabs, and then click ``External Tool''. From there you'll choose `` Defined in domain'' and select the tool to add. If the tool you want to use is not available at a domain level, then after you have defined the tool (see below) clicking the ``Defined in course'' option will allow you to add an instance of that tool to the folder currently being edited. Tools added to the ``Supplemental content'' area will not store grades passed back from the Provider. If you wish to use that functionality you should add a tool instance to a folder or sub-folder in the ``Main Content'' area, and check ``Yes'' for Gradable.
-By defining an External Tool in a course you enable use of LON-CAPA as an LTI Consumer (where LTI = Learning Tool Interoperability). Under the LTI protocol, the user's identity, as well as the course context, can be sent to the external tool (the Provider), which will trust the identity and role information provided by LON-CAPA (the Consumer). Any LON-CAPA data being provided are included in an encrypted form in the tool launch page sent to the user's web browser by LON-CAPA. The external tool will assign appropriate privileges to the user within the tool, based on the user's role.
+By defining an External Tool in a course you enable use of LON-CAPA as an LTI Consumer (where LTI = Learning Tool Interoperability). Under the LTI protocol, the user's identity, as well as the course context, can be sent to the external tool (the Provider), which will trust the identity and role information provided by LON-CAPA (the Consumer). Integrity of data in the payload sent by LON-CAPA to the user's web browser, which the browser then submits to the Provider, is assured by including a signature in the payload which the Provider must verify on receipt. The external tool will assign appropriate privileges to the user within the tool, based on the user's role.
-The shared key and secret used to encrypt data sent to the Tool Provider are typically provided to you when contact the Provider to let them know you would like to use their tool with your Learning Management System, i.e., with LON-CAPA at your institution.
+The shared key and secret used to sign the payload sent to the Tool Provider on launch are typically provided to you when contact the Provider to let them know you would like to use their tool with your Learning Management System, i.e., with LON-CAPA at your institution.
When you use Settings $>$ Course Settings $>$ Display (``External Tools'' checked) a table will be displayed listing all currently available External Tools (i.e., LTI Providers) defined in the course, as well as an ``Add'' checkbox (for the last row in the table), used to add a new External Tool.
@@ -26,7 +26,7 @@
\item{\textbf{Optional settings}}
-There are five optional settings, for which you can set default values, which optionally you may allow to be overridden for each tool instance: Display target (iFrame, Tab, or Window), Width and Height (if target is Window), default link text, and default explanation.
+There are seven optional settings, for which you can set default values, which optionally you may allow to be overridden for each tool instance: Display target (iFrame, Tab, or Window), Width and Height (if target is Window), default link text explanation (unless target is iFrame), destination URL (if different from Provider URL), and return LON-CAPA URL.
Optionally, you can also:
\begin{itemize}
@@ -37,7 +37,7 @@
\item{\textbf{User data sent on launch}}
-For each External Tool, you will set what data are sent when it is launched. You can choose to send any or all of: Full Name, First Name, Last Name, E-mail address, Role (i.e., current ``LTI'' role, as determined from current role in LON-CAPA), and User (either username or username:domain) for the user launching a tool instance in a course.
+For each External Tool, you will set what user data are sent when it is launched. You can choose to send any or all of: Full Name, First Name, Last Name, E-mail address, Role (i.e., current ``LTI'' role, as determined from current role in LON-CAPA), and User (either username or username:domain) for the user launching a tool instance in a course.
\item{\textbf{Role mapping}}
@@ -47,11 +47,11 @@
\item{\textbf{Configurable in course}}
-The five optional settings: display target (and width and height, when target is window), default link text, and default explanation can be set to be configurable for each instance of a tool in a course.
+The seven optional settings: display target (and width and height, when target is window), default link text and explanation (when target is tab or window), different destination URL, and return LON-CAPA URL, can be set to be configurable for each instance of a tool in a course.
In addition, two other items sent on launch to the external tool - Course label and Course title - can be set to be configurable for each tool instance. If Course label is not configurable, the institutional course code for the LON-CAPA course will be used, whereas if Course title is not configurable, the LON-CAPA course title will be used, respectively, for context\_label and context\_title, as part of the data sent to the external tool on launch.
-Lastly, the Provider URL can be set to be configurable, so that text, such as a path or query string, will be appended to the default Provider URL to which the encrypted LTI data are sent on launch can. The text appended can potentially be unique for each tool instance.
+Lastly, the Provider URL can be set to be configurable, so that text, such as a path or query string, will be appended to the default Provider URL to which the signed LTI data are sent on launch. The text appended can potentially be unique for each tool instance. If there is a need to deep-link to a particular location in the Provider, post-launch, and the Tool Provider supports use of an appended string, this would be preferred to specification of a different destination URL (see above), as the latter is performed with client-side javascript with the need to specify a delay between launch and redirect.
\item{\textbf{Custom items sent on launch}}
@@ -78,6 +78,7 @@
launch_presentation_document_target
launch_presentation_locale
launch_presentation_height
+launch_presentation_return_url
launch_presentation_width
lis_outcome_service_url
lis_person_contact_email_primary
Index: loncom/html/adm/help/tex/Domain_Configuration_LTI_Tools.tex
diff -u loncom/html/adm/help/tex/Domain_Configuration_LTI_Tools.tex:1.4 loncom/html/adm/help/tex/Domain_Configuration_LTI_Tools.tex:1.5
--- loncom/html/adm/help/tex/Domain_Configuration_LTI_Tools.tex:1.4 Sun May 24 21:48:38 2020
+++ loncom/html/adm/help/tex/Domain_Configuration_LTI_Tools.tex Mon Jun 16 17:01:11 2025
@@ -1,8 +1,8 @@
\label{Domain_Configuration_LTI_Tools}
-By adding one or more External Tools to a domain, you will be enabling use of your LON-CAPA domain as an LTI Consumer (where LTI = Learning Tool Interoperability). Under the LTI protocol, the user's identity, as well as the course context, can be sent to the external tool (the Provider) which will trust the identity and role information provided by LON-CAPA (the Consumer). Any LON-CAPA data being provided are included in an encrypted form in the tool launch page sent to the user's web browser by LON-CAPA. The external tool will assign appropriate privileges to the user within the tool, based on the user's role.
+By adding one or more External Tools to a domain, you will be enabling use of your LON-CAPA domain as an LTI Consumer (where LTI = Learning Tool Interoperability). Under the LTI protocol, the user's identity, as well as the course context, can be sent to the external tool (the Provider) which will trust the identity and role information provided by LON-CAPA (the Consumer). Integrity of data in the payload sent to the user's web browser by LON-CAPA, which the browser then submits to the Provider, is assured by including a signature in the payload which the Provider must verify on receipt. The external tool will assign appropriate privileges to the user within the tool, based on the user's role.
-The shared key and secret used to encrypt data sent to the Tool Provider are typically provided to you when contact the Provider to let them know you would like to use their tool with your Learning Management System, i.e., with the LON-CAPA service for your domain.
+The shared key and secret used to sign the payload sent to the Tool Provider on launch are typically provided to you when contact the Provider to let them know you would like to use their tool with your Learning Management System, i.e., with the LON-CAPA service for your domain.
When a Domain Coordinator includes ``External Tools (LTI)'' as one of the domain settings to display/modify via the ``Set domain configuration'' link in the Main Menu, a table will be displayed listing all currently available External Tools (i.e., LTI Providers) configured for use in the domain, as well as an ``Add'' checkbox (for the last row in the table), used to add a new External Tool.
@@ -22,7 +22,7 @@
\item{\textbf{Optional settings}}
-There are five optional settings, for which you can set default values, which optionally you may allow a Course Coordinator to override for each tool instance: Display target (iFrame, Tab, or Window), Width and Height (if target is Window), default link text, and default explanation.
+There are seven optional settings, for which you can set default values, which optionally you may allow a Course Coordinator to override for each tool instance: Display target (iFrame, Tab, or Window), Width and Height (if target is Window), default link text and explanation (unless target is iFrame), destination URL (if different from Provider URL), return LON-CAPA URL.
Optionally, you can also:
\begin{itemize}
@@ -33,7 +33,7 @@
\item{\textbf{User data sent on launch}}
-For each External Tool, you will set what data are sent when it is launched. You can choose to send any or all of: Full Name, First Name, Last Name, E-mail address, Role (i.e., current ``LTI'' role, as determined from current role in LON-CAPA), and User (either username or username:domain) for the user launching a tool instance in a course.
+For each External Tool, you will set what user data are sent when it is launched. You can choose to send any or all of: Full Name, First Name, Last Name, E-mail address, Role (i.e., current ``LTI'' role, as determined from current role in LON-CAPA), and User (either username or username:domain) for the user launching a tool instance in a course.
\item{\textbf{Role mapping}}
@@ -43,11 +43,11 @@
\item{\textbf{Configurable in course}}
-The five optional settings: display target (and width and height, when target is window), default link text, and default explanation can be set to be configurable for each instance of a tool in a course by the Course Coordinator.
+The seven optional settings: display target (and width and height, when target is window), default link text and explanation (when target is tab or window), different destination URL, and return LON-CAPA URL, can be set to be configurable for each instance of a tool in a course by the Course Coordinator.
In addition, two other items sent on launch to the external tool - Course label and Course title - can be set to be configurable by a Course Coordinator. If Course label is not configurable, the institutional course code for the LON-CAPA course will be used, whereas if Course title is not configurable, the LON-CAPA course title will be used, respectively, for context\_label and context\_title, as part of the data sent to the external tool on launch.
-Lastly, the Provider URL can be set to be configurable, so that a Course Coordinator can specify text (potentially unique for each tool instance), such as a path or query string, which will be appended to the default Provider URL to which the encrypted LTI data are sent on launch.
+Lastly, the Provider URL can be set to be configurable, so that a Course Coordinator can specify text (potentially unique for each tool instance), such as a path or query string, which will be appended to the default Provider URL to which the signed LTI data are sent on launch. If there is a need to deep-link to a particular location in the Provider, post-launch, and the Tool Provider supports use of an appended string, this would be preferred to specification of a different destination URL (see above), as the latter is performed with client-side javascript with the ned to specify a delay between launch and redirect.
\item{\textbf{Custom items sent on launch}}
@@ -74,6 +74,7 @@
launch_presentation_document_target
launch_presentation_locale
launch_presentation_height
+launch_presentation_return_url
launch_presentation_width
lis_outcome_service_url
lis_person_contact_email_primary
Index: loncom/html/adm/help/tex/Docs_Adding_External_Tool.tex
diff -u loncom/html/adm/help/tex/Docs_Adding_External_Tool.tex:1.4 loncom/html/adm/help/tex/Docs_Adding_External_Tool.tex:1.5
--- loncom/html/adm/help/tex/Docs_Adding_External_Tool.tex:1.4 Thu Jan 25 19:51:24 2024
+++ loncom/html/adm/help/tex/Docs_Adding_External_Tool.tex Mon Jun 16 17:01:11 2025
@@ -14,10 +14,18 @@
\begin{itemize}
+\item Post-login destination -- you can specify the destination URL to which
+the browser will be redirected post-LTI authentication. To allow
+time for the initial launch to complete, you will specify a delay in seconds
+before client-side javascript executes the redirect.
+
+\item Append to URL -- you can specify text to append to the default URL
+(shown) to which the data payload will be sent on launch.
+
\item Display target
\begin{itemize}
\item iframe -- the tool will be launched within the standard interface, (i.e.,
-inline menu including navigation controls, and links/icons)
+inline menu including navigation controls, and links/icons).
\item tab -- a page containing a link to launch the tool will be displayed
in a separate web browser tab.
@@ -42,9 +50,6 @@
\item Course label -- e.g., institutional course code (sent on launch of tool)
\item Course title -- Course Title
-\item Append to URL -- you can specify text to append to the default URL
-(shown) which will be requested on launch.
-
\item Gradable -- if a tool is used in Main Content, you can choose whether
to accept scores passed back by the tool, if the domain configuration
specified availability of a passback service.
@@ -59,13 +64,13 @@
name of the tool you wish to use from the drop-down list. Doing
so will cause the options for the tool to be displayed. If display is in
an iframe, by default, but you are permitted to choose one of the other types,
-then click tab or window will cause additional elements to be displayed.
+then clicking tab or window will cause additional elements to be displayed.
For tools defined in the domain, your domain coordinator can tell you what
data are sent to the external tool when it is displayed. Typically, though,
this will include the username of the user, as well as the user's current
``LTI'' role. For tools defined in the course, you can see what data are sent
-ny using Settings $>$ Course Settings $>$ Display (``External Tools'' checked).
+by using Settings $>$ Course Settings $>$ Display (``External Tools'' checked).
LTI uses a more restricted set of roles -- Instructor, Content Developer,
Teaching Assistant or Learner -- than are available in LON-CAPA. For tools
@@ -75,6 +80,7 @@
Student (LON-CAPA) will map to Learner (LTI).
Under the LTI protocol, the user's identity, as well as the course context, will
-be sent to the external tool in an encrypted form, and the tool (the LTI Provider)
-will trust the user's identity and role sent from LON-CAPA (the LTI Consumer),
-and then assign appropriate privileges to the user within the tool.
+be sent to the external tool in a signed payload, and the tool (the LTI Provider)
+must verify the signature before it will trust the user's identity and role sent
+from LON-CAPA (the LTI Consumer), and then assign appropriate privileges
+to the user within the tool.
More information about the LON-CAPA-cvs
mailing list