Usage

LmsLicenseeObject represents an organization in the system. The object is used with the CreateOrUpdate method to create and update clients and distributors. It is returned by the Search method when retrieving information about existing organizations in the system.

Permissions

A client application must be logged in with sufficient access rights to create or modify licensees. Required security credentials differ for creating licensees and modifying existing licensees.

Required permissions for creating licensees

• The client application must have Master Administrator privilege
• The client application must have access to the parent of the new licensee
• The parent licensee must be able to add new clients (Master licensee type)

Required permissions for updating licensees

• The client application must have either Master Administrator or Licensee Administrator privilege
• The licensee being updated must be accessible by the client application
• The following fields cannot be updated if the client application is updating its own licensee information:
  • LicenseeType
  • ExpiryDatetime
  • IsAiccAccessEnabled
  • IsAiccTraceEnabled

Identifying Fields

One of the following fields must be specified to uniquely identify a licensee:

• Id, or
• LicenseeId

A description of these fields follow.

Id

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

LicenseeId

A unique string representing the licensee's identifier. This field corresponds to the first part of the licensee ID, username, and password combination used for Firmwater LMS authentication.  This field is exposed as the 'Client ID' in the user interface.

Licensee identifiers are restricted to a maximum length of 40 characters and must start with a letter.  Only letters, numbers, periods, underscores, and hyphens are allowed.

Other Fields

ParentLicenseeId

A string representing the parent licensee's identifier. Except for the root-level licensee, every licensee has a parent licensee. When creating new licensees, this field is required. Because Firmwater LMS does not permit changing a licensee's parent, Firmwater LMS web services ignores the contents this field when updating an existing licensee.

LicenseeName

A string representing the licensee's name. Licensee names must be unique amongst children of the parent licensee; in other words, all direct child licensees of the parent specified in the ParentLicenseeId field must have unique names.

Licensee names can be represented in multiple languages by the specifying the xml:lang attribute. Licensee names are restricted to a maximum length of 100 characters. When searching for licensees using the LicenseeName field, there is no way to restrict the search based on language. The search is performed on all languages.

When creating a licensee, the licensee name must be specified in at least the default language.

LicenseeType

A required enumerated type representing the licensee's type. Firmwater LMS has two types of licensees, master and endUser. The primary difference between the two licensee types is the ability to create child licensees. A master licensee can create new child licensees, while an endUser licensee cannot. Both can edit existing children.

See Permissions for details on the required access privilege for setting this field's value.

DefaultLanguage

An ISO-646 compliant string representing the licensee's default language. When creating new licensees, the default language is set to the parent licensee's default language if not explicitly specified.

ExternalId

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

ApplicationName

A string representing the Firmwater LMS application name for the organization. The application name shows in the page title and in emails that are sent from the system.

Application names can be represented in multiple languages by the specifying the xml:lang attribute. Application names are restricted to a maximum length of 60 characters. When searching for licensees using the ApplicationName field, there is no way to restrict the search based on language. The search is performed on all languages.

When creating new licensees, the value is set to the parent licensee's value if not explicitly specified.

UseLocation

A boolean value indicating whether or not locations are enabled for the organization. If the UseLocation flag is set to true, locations are enabled for the licensee; otherwise, locations are disabled. When creating new licensees, the value is set to the parent licensee's value if not explicitly specified.

UseLocationHierarchy

A boolean value indicating whether or not location hierarchies are enabled for the organization. If the UseLocation flag is set to true, location hierarchies are enabled; otherwise, location hierarchies are disabled. When creating new licensees, the value is set to the parent licensee's value if not explicitly specified.

The value can only be set to true if the organization's UseLocation value is set to true.

AreEventsEnabled

A boolean value indicating whether or not events are enabled for the organization. If the AreEventsEnabled flag is set to true, events are enabled; otherwise, events are disabled. When creating new licensees, the value is set to the parent licensee's value if not explicitly specified.

The value can only be set to true if the organization's UseLocation value is set to true.

UseDepartment

A boolean value indicating whether or not departments are enabled for the organization. If the UseDepartment flag is set to true, departments are enabled for the licensee; otherwise, departments are disabled. When creating new licensees, the value is set to the parent licensee's value if not explicitly specified.

UseJobTitle

A boolean value indicating whether or not job titles are enabled for the organization. If the UseJobTitle flag is set to true, job titles are enabled for the licensee; otherwise, job titles are disabled. When creating new licensees, the value is set to the parent licensee's value if not explicitly specified.

IsCertificationEnabled

A boolean value indicating whether or not certifications are enabled for the organization. If the IsCertificationEnabled flag is set to true, certifications are enabled for the licensee; otherwise, certifications are disabled. When creating new licensees, the value is set to the parent licensee's value if not explicitly specified.

IsMembershipEnabled

A boolean value indicating whether or not membership is enabled for the organization. If the IsMembershipEnabled flag is set to true, membership is enabled for the licensee; otherwise, membership is disabled. When creating new licensees, the value is set to the parent licensee's value if not explicitly specified.

IsSelfRegistrationEnabled

A boolean value indicating whether or not users can sign up for their own accounts for the organization. If the IsSelfRegistrationEnabled flag is set to true, users can sign up for their own accounts for the licensee; otherwise, they cannot. When creating new licensees, the value is set to the parent licensee's value if not explicitly specified.

UseLocationAddress

A boolean value indicating whether or not location addresses are enabled for the organization. If the UseLocationAddress flag is set to true, location addresses are enabled for the licensee; otherwise, location addresses are disabled. When creating new licensees, the value is set to the parent licensee's value if not explicitly specified.

UsePersonAddress

A boolean value indicating whether or not person addresses are enabled for the organization. If the UsePersonAddress flag is set to true, person addresses are enabled for the licensee; otherwise, person addresses are disabled. When creating new licensees, the value is set to the parent licensee's value if not explicitly specified.

IsUsernameEmailAddress

A boolean value indicating whether or not users are identified using an email address.  If the flag is set to true, all usernames must be valid email addresses.  When creating new licensees, the value is set to the parent licensee's value if not explicitly specified.

ExpiryDatetime

A Datetime field representing the organization's expiry date and time. A licensee is considered expired when the expiry date and time is earlier than the current date and time. An expired organization is considered to be disabled and access to Firmwater LMS by all users in the organization is disabled. To clear the expiry date and time of a licensee, set the value of the ExpiryDatetime field to empty string ("").