[LON-CAPA-cvs] cvs: doc /help course.manual.texxml /loncapafiles loncapafiles.lpml loncom/html/adm/help/tex Course_Prefs_ExternalTools.tex

[raeburn]

raeburn		Thu Jan 25 19:19:53 2024 EDT

  Added files:                 
    /loncom/html/adm/help/tex	Course_Prefs_ExternalTools.tex 

  Modified files:              
    /doc/help	course.manual.texxml 
    /doc/loncapafiles	loncapafiles.lpml 
  Log:
  - Add documentation for External tools configuration in Course Settings
  
  
-------------- next part --------------
Index: doc/help/course.manual.texxml
diff -u doc/help/course.manual.texxml:1.53 doc/help/course.manual.texxml:1.54
--- doc/help/course.manual.texxml:1.53	Sat Dec 23 21:40:31 2023
+++ doc/help/course.manual.texxml	Thu Jan 25 19:19:52 2024
@@ -100,6 +100,9 @@
     <subsection name="Menu Display">
       <file name="Course_Prefs_Menus.tex"/>
     </subsection>
+    <subsection name="External Tools">
+      <file name="Course_Prefs_ExternalTools.tex"/>
+    </subsection>
     <subsection name="Link Protection">
       <file name="Course_Prefs_Linkprotection.tex"/>
     </subsection>
Index: doc/loncapafiles/loncapafiles.lpml
diff -u doc/loncapafiles/loncapafiles.lpml:1.1049 doc/loncapafiles/loncapafiles.lpml:1.1050
--- doc/loncapafiles/loncapafiles.lpml:1.1049	Thu Jan 25 19:02:17 2024
+++ doc/loncapafiles/loncapafiles.lpml	Thu Jan 25 19:19:53 2024
@@ -2,7 +2,7 @@
  "http://lpml.sourceforge.net/DTD/lpml.dtd">
 <!-- loncapafiles.lpml -->
 
-<!-- $Id: loncapafiles.lpml,v 1.1049 2024/01/25 19:02:17 raeburn Exp $ -->
+<!-- $Id: loncapafiles.lpml,v 1.1050 2024/01/25 19:19:53 raeburn Exp $ -->
 
 <!--
 
@@ -3675,6 +3675,7 @@
 Course_Parameter_Table_Mode.tex;
 Course_Prefs_Bridgetasks.tex;
 Course_Prefs_Display.tex;
+Course_Prefs_ExternalTools.tex;
 Course_Prefs_Grading.tex;
 Course_Prefs_Printouts.tex;
 Course_Prefs_Classlists.tex;

Index: loncom/html/adm/help/tex/Course_Prefs_ExternalTools.tex
+++ loncom/html/adm/help/tex/Course_Prefs_ExternalTools.tex
\label{Course_Prefs_ExternalTools}

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.

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.

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.

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.

Internally in LON-CAPA each external tool you configure for your course receives a unique numerical ID (starting at 1), which remains unchanged, regardless of any future changes made to the configuration for that particular tool.  A drop-down list in the left column of the External Tools table can be used to change the order in which available tools are listed in both the configuration table, and also in the dropdown list in the ``External Tool'' item in the Course Editor (``External tab''), when one or more tools are available.

Settings available in each External Tool definition are:

\begin{itemize}

\item{\textbf{Required settings}}

The Provider name will be the Tool name shown in the listing of available External Tools in the Course Editor.

For each External Tool the unique key and secret will be provided to you by the Tool Provider, as will the remote URL which will handle LTI launch requests from link(s) to instance(s) of the tool in LON-CAPA courses in your domain.

Each External Tool can be configured to allow additional information to be appended to the Tool URL for each tool instance.  There are four other required settings: Version, Message Type, Signature Method and Nonce lifetime. You will likely use the default values provided for each of the four.

\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.

Optionally, you can also:
\begin{itemize}
\item Set whether a tool can return grade information to the LON-CAPA course from which it was launched, for the user (and tool instance).  You can also set the lifetime (in days) of the unique grade passback ID sent to the external tool, each time a user launches a particular instance of a tool in a course.
\item Set whether a tool can retrieve roster information for the LON-CAPA course from which it was launched, within a specified number of seconds from launch.
\item Upload a small image file, which will be used as an icon for the file type for each tool instance in the Course Editor.
\end{itemize}

\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.

\item{\textbf{Role mapping}}

LTI uses a more restricted set of roles - Instructor, Content Developer, Teaching Assistant or Learner - than are available in LON-CAPA.

For each tool you will set mapping to an LTI role to be used for each standard LON-CAPA role. At a minimum you should likely set that Course Coordinator (LON-CAPA) will map to Instructor (LTI), and Student (LON-CAPA) will map to Learner (LTI).

\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.

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.

\item{\textbf{Custom items sent on launch}}

Besides the set of standard LTI items, you may also add name=value pairs to send additional data to the LTI Provider on launch of the tool in a LON-CAPA course.

LON-CAPA will automatically prepend \emph{custom\_} to the name of each custom item you set in the tool configuration when preparing the data to send to the external tool.

If the entry in the \emph{value} textbox is of the form: LONCAPA::env\{lcenvkey\}, where \emph{lcenvkey} is the name of an item in LON-CAPA's own \%env hash, then the LONCAPA::env\{lcenvkey\} value in the custom\_name=value pair sent on launch will be the value of \$env\{lcenvkey\} in effect in the user's LON-CAPA session. Otherwise, whatever value is set in the domain configuration for the tool for item \emph{name} will be sent as the pair: custom\_name=value.

\end{itemize}

For reference the complete set of parameters (other than custom\_*) which could be present in the data POSTed on LTI launch (depending on how the tool is configured) is as follows:

\begin{verbatim}

basiclti_submit
context_id
context_label
context_title
context_type
ext_ims_lis_basic_outcome_url
ext_ims_lis_memberships_url
ext_ims_lis_memberships_id
launch_presentation_document_target
launch_presentation_locale
launch_presentation_height
launch_presentation_width
lis_outcome_service_url
lis_person_contact_email_primary
lis_person_name_family
lis_person_name_full
lis_person_name_given
lis_person_sourcedid
lis_result_sourcedid
lti_message_type
lti_version
oauth_consumer_key
oauth_nonce
oauth_signature
oauth_signature_method
oauth_timestamp
oauth_version
resource_link_id
resource_link_title
roles
tool_consumer_info_product_family_code
tool_consumer_info_version
tool_consumer_instance_description
tool_consumer_instance_guid
tool_consumer_instance_name
tool_consumer_instance_url
user_id

\end{verbatim}