LmsPersonObject

Usage

LmsPersonObject represents a person within the system. The object is used with the CreateOrUpdate method to create and update people. It is returned by the Search method when retrieving information about existing people in the system.

Permissions

A logged in client application must ensure they have sufficient privilege and access rights to create or modify a person. The object to be saved is restricted by the following rules:

  • the administrative privilege cannot be greater then client application's privilege
  • the user's licensee must be accessible by the client application
  • students may edit themselves

Firmwater LMS allows licensees to configure which person fields are editable and which ones are required. A client application may only edit fields that are editable and, when creating a new user, must supply all required fields.

Identifying Fields

One of the following groups of fields must be specified to uniquely identify a Person record:

  • Id, or
  • Username AND LicenseeId

A description of these fields follow.

Id

A 36-character globally unique identifier to uniquely identify a person. This field is read-only but can be used when searching for or updating an LmsPersonObject.

Username

A string representing the person's username that will be used for Firmwater LMS logins. Usernames are unique within a licensee; therefore, a valid licensee ID and username will uniquely identify a person.

Usernames are restricted to a maximum length of 300 characters.   If the licensee's IsUsernameEmailAddress flag is set to true, the username must be a valid email address; otherwise, it must meet the licensee's minimum username length requirements.

Client applications should be aware that an attempt to create a new user using an existing username (within the licensee) will overwrite existing user information. 

LicenseeId

A string representing the ID of the licensee that the person is a part of. An authenticated client application attempting to create/modify a person must have access to the licensee specified by LicenseeId.

Other Fields

AdministrativePrivilege

An enumerated type representing the administrative privilege of the user being created/modified. If an administrative privilege is not specified, new users are created with a privilege level of 'student'.

The following values are supported:

  • student
  • localAdmin
  • localReportsOnly
  • multipleLocationAdmin
  • multipleLocationReportsOnly
  • licenseeAdmin
  • licenseeReportsOnly
  • masterAdmin
  • masterReportsOnly

FirstName

A string representing the first name of the user being created or modified. First names are restricted to a maximum length of 40 characters.

MiddleName

An string representing the middle name of the user being created or modified. Middle names are restricted to a maximum length of 40 characters.

LastName

A string representing the last name of the user being created or modified. Last names are restricted to a maximum length of 40 characters.

DepartmentObject

An LmsDepartmentObject representation of the department the person belongs to. When creating/updating a person: if the department already exists, only the identifing fields need to be set on the object; otherwise all required field needs to be set, and an attempt will be made to create the department on behalf of the user. Firmwater LMS ignores the DepartmentObject field for licensees with departments disabled. Note: Use of the DepartmentId and DepartmentName fields are to be deprecated; client applications should be updated to use the DepartmentObject field.

JobTitleObject

An LmsJobTitleObject representation of the job title the person belongs to. When creating/updating a person: if the job title already exists, only the identifing fields need to be set on the object; otherwise all required field needs to be set, and an attempt will be made to create the job title on behalf of the user. Firmwater LMS ignores the JobTitleObject field for licensees with job titles disabled. Note: Use of the JobTitleId and JobTitle fields are to be deprecated; client applications should be updated to use the JobTitleObject field.

LocationObject

An LmsLocationObject representation of the location the person belongs to. When creating/updating a person: if the location already exists, only the identifing fields need to be set on the object; otherwise all required field needs to be set, and an attempt will be made to create the location on behalf of the user. Firmwater LMS ignores the LocationObject field for licensees with locations disabled. Note: Use of the LocationId and LocationName fields are to be deprecated; client applications should be updated to use the LocationObject field.

Password

A string representing the person's password. If this field is not set when creating a new user, the person will not have the ability to log into Firmwater LMS. User sessions can still be created for the person by an administrator via the CreateUserSession web service method. If this field is not set during an update to a user, the user's password will remain unchanged.

EmailAddress

A string representing the person's email address. When set, the value must be a valid email address.  When the licensee's IsUsernameEmailAddress flag is set to true, this field is read-only.  The email address associated with a person is used for password recovery and to send notifications.  

ResidencePhone

A string representing the person's residence phone number.

BusinessPhone

A string representing the person's business phone number.

MobilePhone

A string representing the person's mobile phone number.

PreferredLanguage

An ISO-646 string representing the user's preferred language. The licensee must be configured to support the specified language. If no language is specified, new users are created with a preferred language of English.

ExternalId

A string used as an external identifier for the person. External identifiers are client specific. Firmwater LMS makes no assumption nor places restrictions on the significance of this string. External person identifiers are restricted to a maximum length of 255 characters.

PasswordExpiryDatetime

A Datetime field representing the user's password expiry date and time. A user's password is considered expired when the password expiry date and time is earlier than the current Firmwater LMS date and time. An expired password ensures that the user must change his/her password upon next user interface login. The web service API is not affected by expired passwords. To clear the expiry date and time of a password simply set the value of the PasswordExpiryDatetime field to empty string ("").

ExpiryDatetime

A Datetime field representing the user's expiry date and time. A user is considered expired when the expiry date and time is earlier than the current Firmwater LMS date and time. An expired user is considered to be disabled and access to Firmwater LMS by the user is not permitted. To clear the expiry date and time of a user simply set the value of the ExpiryDatetime field to empty string ("").

PostalAddress

A PostalAddress object representing the user's postal address. This information is ignored if the user's licensee does not support person addresses (see LmsLicenseeObject field UsePersonAddress).

IsMember

A read-only boolean value representing whether this person has a membership.

Member

A Member object representing the person's membership information. This property will only exist if if the IsMember property is true.

DateOfBirth

A Date field representing the user's date of birth. This field is empty if there is no date of birth information for the user. To clear the date of birth for a user set the value of DateOfBirth field to an empty string ("").

PhotoUrl

A read-only string that contains the URL of the user's photo. You cannot do a search based on this property.

CustomFields

An array of CustomField objects. When reading from the api the fields contain a FieldId, FieldName and FieldValue. When updating a custom field for a user, a FieldId and FieldValue must be supplied.  


The following properties are deprecated and should no longer be used:

  • DepartmentName
  • DepartmentId
  • JobTitle
  • JobTitleId
  • LocationName
  • LocationId