CreateUserSession

Firmwater LMS Web Services API‎ > ‎2. Methods‎ > ‎

CreateUserSession

A mechanism for generating an authorization token that is later used to create an LMS session for a specified user. The authorization token allows an external user to be automatically authenticated and, if desired, sent directly into specified learning content.

Syntax

UserSessionResult = lmsBinding.CreateUserSession (LmsPersonObject person, string activityRootId, string leafItemId);

Usage

When invoked by a client application, Firmwater LMS will create/update the person object passed in and identify the activity requested. If a department, location, and/or job title is specified by the person object that does not exist, Firmwater LMS will automatically attempt to create the necessary objects. A client application can then use the returned URL (containing the authorization token) to authenticate a user and direct them to the requested activity.

Rules and Guidelines

Permissions

A client application must be logged in with sufficient privilege and access rights to create/modify the passed in LmsPersonObject and to register the user to receive the requested content (see CreateOrUpdate for further information).

LMS Session Described

Ordinarily, LMS users login manually from a login page. Upon authentication of the entered client ID, username and password combination, a user is granted access to an LMS session. Users with active LMS sessions are free to navigate through the LMS in accord with their security privilege and access rights. During the LMS session, users can then access learning content they are registered to receive.

Authorization Token

An authorization token serves as a means of authentication into Firmwater LMS without requiring a client ID, username, and password combination. It is a globally unique identifier (GUID) representing authentication information for a single user, and can be thought of as the user's key to Firmwater LMS. Client applications must be aware that authorization tokens may expire. A token's validity period is controlled by Firmwater LMS administrators, hence, it is recommended that client application developers contact system administrators to determine the validity period of authorization tokens created via CreateUserSession calls.

User Authentication

If an authorization token is a user's key, the authentication page can be thought of as the door the key unlocks. As part of the response to a CreateUserSession call, Firmwater LMS returns a URL pointing to the authentication page that is formulated to automatically authenticate the user (using the authorization token) and forward them to the requested page. A client application need simply redirect the user to this URL.

Arguments

Name	Type	Description
person	LmsPersonObject	The user for which an LMS session will be created
activityRootId	string	Root activities are container items such as courses. This argument represents either the identifier of the activity container page to be displayed to the user, or assuming 'leafItemId' is supplied, the identifier of the root activity that the leaf activity belongs to. If two or more activities exist in the LMS with the specified activityRootId, then the most recently created one is used.
leafItemId	string	Identifier of the leaf activity the user is to experience. A leaf activity is a launchable piece of learning content.

If neither the activityRootId nor the leafItemId are included, the user is directed to her top level "My Training" page. If leafItemId is set, Firmwater LMS enforces that activityRootId also be set; a leaf item cannot be identified without first identifying the parent course.

Return Object

UserSessionResult

Sample SOAP messages

Request

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:ns4="http://firmwater.com/webservices/lms/lmsservice1"
>

  <SOAP-ENV:Header>
    <ns4:SessionHeader SOAP-ENV:actor="http://schemas.xmlsoap.org/soap/actor/next" SOAP-ENV:mustUnderstand="0">
    <ns4:sessionId>89a9772c-6a5a-43e1-a607-4e60e311cf1d</ns4:sessionId></ns4:SessionHeader>
  </SOAP-ENV:Header>

  <SOAP-ENV:Body>
    <ns4:CreateUserSession>
      <ns4:person>
        <ns4:Username>jsmith</ns4:Username>
        <ns4:LicenseeId>XYZOrganization</ns4:LicenseeId>
        <ns4:LastName>Smith</ns4:LastName>
        <ns4:FirstName>Joe</ns4:FirstName>
        <ns4:AdministrativePrivilege>student</ns4:AdministrativePrivilege>
        <ns4:LocationObject>
          <ns4:LicenseeId>XYZOrganization</ns4:LicenseeId>
          <ns4:LocationName>New York</ns4:LocationName>
        </ns4:LocationObject>
        <ns4:DepartmentObject>
          <ns4:LicenseeId>XYZOrganization</ns4:LicenseeId>
          <ns4:DepartmentName>Development</ns4:DepartmentName>
        </ns4:DepartmentObject>
        <ns4:JobTitleObject>
          <ns4:LicenseeId>XYZOrganization</ns4:LicenseeId>
          <ns4:JobTitle>Software Engineer</ns4:JobTitle>
        </ns4:JobTitleObject>
      </ns4:person>
    
      <ns4:activityRootId>C1234</ns4:activityRootId>
      <ns4:leafItemId></ns4:leafItemId>
    </ns4:CreateUserSession>
  </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Response

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
>

  <soap:Body>
    <CreateUserSessionResponse xmlns="http://firmwater.com/webservices/lms/lmsservice1">
      <CreateUserSessionResult>
        <Url>https://apps.firmwater.com/lms/login.aspx?TargetUrl=%2flms%2ftraining%2fitem.aspx&at=A6962878-FC7D-416C-A425-84BC0C45824E</Url>
        <Token>A6962878-FC7D-416C-A425-84BC0C45824E</Token>
      </CreateUserSessionResult>
    </CreateUserSessionResponse>
  </soap:Body>

</soap:Envelope>

	Search this site