LmsLocationObject

Usage

LmsLocationObject represents a location within an organization. The object is used with the CreateOrUpdate method to create and update locations. It is returned by the Search method when retrieving information about existing locations in the organization.

Permissions

A client application must be logged in with sufficient access rights to modify or create a location. Listed below are the general permission requirements necessary to update/create a location:

  • The licensee must have locations enabled (see LmsLicenseeObject field UseLocation)
  • The administrative privilege under which the client application is logged in determines what locations can be modified and/or created:
    • Master Administrators: can create/modify any location within any organization accessible to them
    • Licensee Administrators: can create/modify any location within their own organization
    • Multiple Location Administrators: can modify most, but not all, settings for their own location. Multiple location administrators can also create/modify locations that are children of their own location.
    • Local Administrators: can modify most, but not all, settings for their own location

Identifying Fields

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

  • Id, or
  • LocationName AND LicenseeId

A description of these fields follow.

Id

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

LocationName

A required string representing the location's name. Location names must be unique within a licensee. Location names are restricted to a maximum length of 100 characters.

LicenseeId

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

Other Fields

ExternalLocationId

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

LocationType

A string representing the location type in the licensee's default language. The specified location type must already exist in the organization. This field is required if the organization has location hierarchies enabled.

ParentId

A 36-character globally unique identifier to uniquely identify the parent location. Parent locations are only applicable if the organization has location hierarchies enabled. The location's LocationType dictates whether a parent location must be specified. The LocationType also limits the set of locations from which the parent location can be selected. The location specified as the parent location must have a type matching the parent type of the specified LocationType.

ParentLocationName

A string representing the parent location's name. This field is ignored if the ParentId field is specified. Parent locations are only applicable if the organization has location hierarchies enabled. The location's LocationType dictates whether a parent location must be specified. The LocationType also limits the set of locations from which the parent location can be selected. The location specified as the parent location must have a type matching the parent type of the specified LocationType.

PostalAddress

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

ExpiryDatetime

A Datetime field representing the location's expiry date and time. A location is considered expired when the expiry date and time is earlier than the current Firmwater LMS date and time. To clear the expiry date and time of a location, simply set the value of the ExpiryDatetime field to empty string ("").