User
A user [User
] is either an employee (an employee working for your company or a subcontractor), a generic resource (virtual or placeholder resource that represents a staffing need) or a guest user (a customer that can sign in to your OpenAir account and view information that is associated with them and the projects that your company delivers to them). Employees and guest users can sign into your company's OpenAir account. Employees (named resources) and generic resources can be booked to projects and tasks.
Review the Usage Guidelines for the User
object.
— |
XML |
SOAP |
REST |
Database table |
---|---|---|---|---|
Object |
|
|
— |
|
Supported Commands |
— |
— |
The User
object has the following standard properties:
User
object properties may also include custom fields. The object type supports the custom equal to
read method and the enable_custom
read attribute.
XML |
SOAP |
Database |
Description |
---|---|---|---|
|
|
|
The ID of the associated company work schedule [ |
|
|
|
Optional accounting code that can be used for integration with external accounting systems. |
|
|
|
A 1/0 field indicating if the user is designated as an active user. |
|
— |
— |
The user's address. See Address Fields. The |
— |
|
|
First line of the user's address. |
— |
|
|
Second line of the user's address. |
— |
|
|
Third line of the user's address. |
— |
|
|
Fourth line of the user's address. |
— |
|
|
The user's city. |
— |
|
— |
The internal ID of the associated |
— |
|
|
The user's country. |
— |
|
|
[Required] The user's Email address. |
— |
|
|
The user's fax number. |
— |
|
|
The user's first name. |
— |
|
— |
The internal ID of the associated |
— |
|
|
The user's last name. |
— |
|
|
The user's middle name. |
— |
|
|
The user's mobile number. |
— |
|
|
The user's phone number. |
— |
|
|
The user's salutation. |
— |
|
|
The user's state or region. |
— |
|
|
The user's ZIP code or postal code. |
|
|
|
The internal ID of the approval process for expense authorizations submitted by the user. Mutually exclusive with |
|
|
|
The internal ID of the Other possible values:
|
|
|
— |
Internal hash key. |
|
|
|
The internal ID of the approval process [ |
|
|
|
The internal ID of the Other possible values:
|
|
|
|
Optional accounting code that can be used for integration with external accounting systems. See also |
|
|
|
[Write-only] New cost value. Used with |
|
|
|
The internal ID of the cost center [ |
|
|
|
[Write-only] Currency of the cost. Used with |
|
|
|
[Write-only] End date for the new loaded cost. If left blank, the new cost will have no end date. See Date Fields. Used with |
|
|
|
[Write-only] If multiple loaded cost levels are enabled, use this field to hold the level of the loaded cost. Used with |
|
|
|
[Write-only] Start date for the new loaded cost. If left blank, the new cost will assume the current date as it's start date. See Date Fields. Used with |
|
|
|
[Read-only] The date and time when the record was created. See Date Fields. |
|
|
|
The user's currency. Three-letter currency code. |
|
|
|
The internal ID of the attachment [ |
|
|
|
The internal ID of the department [ |
|
|
|
The internal ID of the approval process [ |
|
|
|
The internal ID of the Other possible values:
|
|
|
|
The unique external ID of the user, if the record was imported from an external system. |
|
|
|
The unique external ID of the user, if the record was imported from an external system. In the XML and SOAP API, the |
|
|
— |
A comma delimited list of internal IDs of filter sets [ |
|
|
— |
A unique string which changes when the primary filter set changes for the user. |
|
|
— |
User-specific settings. See Company and User Settings. |
|
|
|
A 1/0 field indicating whether this is a generic resource. Cannot be modified. |
|
|
— |
A comma delimited list of internal IDs of hierarchy nodes [ |
|
|
|
The user's password hint. |
|
|
|
[Read-only] The unique internal identifier of the user. Automatically assigned by OpenAir. |
|
|
— |
[Write-only] A 1/0 field indicating whether the user should draw their workschedule from an account_workschedule or draw from a custom workschedule. 0 sets the user workschedule to the account workschedule specified in account_workscheduleid, 1 constructs a custom workschedule from the supplied workschedule_workdays and workschedule_workhours fields. Used with |
|
|
|
The internal ID of the job code [ |
|
|
|
The internal ID of the filter set override [ |
|
|
|
The internal ID of the user's line manager (internal ID of another |
|
|
|
A 1/0 field indicating if the user is locked out of your company's OpenAir account. |
|
|
|
The date and time of the user's last sign-in. See Date Fields. |
|
|
|
The internal ID of the filter set override [ |
|
|
|
The user's two-factor authentication (2FA) status. The property is read-only if two-factor authentication is not enabled for your company's OpenAir account. Possible values:
|
|
|
|
The display name for the user in lists. This is generated automatically if not set. |
|
|
|
[Required] The users nickname. This must be unique. |
|
|
|
The internal ID of the filter set override [ |
|
|
|
[Required] The user's password. Not returned when reading objects. |
|
|
|
A 1/0 field indicating if the user must change password on next sign in. |
|
|
|
The payroll code for this user. |
|
|
|
The internal ID of the approval process [ |
|
|
|
The internal ID of the Other possible values:
|
|
|
— |
Label as shown on form picklist. |
|
|
|
The internal ID of the filter set override [ |
|
|
|
The internal ID of the approval process [ |
|
|
|
The internal ID of the Other possible values:
|
|
|
|
The internal ID of the filter set override [ |
|
|
|
The internal ID of the approval process [ |
|
|
|
The internal ID of the Other possible values:
|
|
|
|
The internal ID of the user's primary filter set [ |
|
|
|
Comma delimited list of internal IDs of hierarchy nodes [ |
|
|
|
The hourly billing rate for the user's time. |
|
|
|
The internal ID of the filter set override [ |
|
|
|
The internal ID of the filter set override [ |
|
|
|
The internal ID of the approval process [ |
|
|
|
The internal ID of the Other possible values:
|
|
|
|
The internal ID of the role [ |
|
|
|
The date and time when the user's resource profile was last updated using OpenAir API. See Date Fields. |
|
|
|
The internal ID of the |
|
|
|
The date and time when the user's resource profile was last updated using OpenAir UI. See Date Fields. |
|
|
|
The internal ID of approval process [ |
|
|
|
The internal ID of the Other possible values:
|
|
|
|
The user's social security number. Returned only if the authenticated user is an account administrator. |
|
|
|
The internal ID of the approval process [ |
|
|
|
The internal ID of the Other possible values:
|
|
|
|
The internal ID of the filter set override [ |
|
|
|
[Write-only] End date for the new tag. If left blank, the end date for the new tag will be undefined and the new tag will assume default status for the user. See Date Fields. Used with |
|
|
|
[Write-only] The ID of the tag group attribute [ Used with |
|
|
|
[Write-only] The ID of the tag group [ Used with |
|
|
|
[Write-only] Start date for the new tag. If left blank, the start date for the new tag will be set to the current date. See Date Fields. Used with |
|
|
|
The internal ID of the filter set override [ |
|
|
|
The internal ID of the approval process [ |
|
|
|
The internal ID of the Other possible values:
|
|
|
|
The internal ID of the approval process [ |
|
|
|
The internal ID of the Other possible values:
|
|
|
|
The internal ID of the filter set override [ |
|
|
|
The user's timezone. Defaults to the time zone for the company's account if not set when adding a user. |
|
|
— |
Legacy field. |
|
|
— |
[Write-only] Set to |
|
|
— |
[Write-only] Set to |
|
|
— |
[Write-only] Set to |
|
|
|
[Read-only] Date and time when the record was last updated or modified. See Date Fields. |
|
|
|
The internal ID of the user location [ |
|
|
|
The first day of the week for the user:
Defaults to the first day of the week for the company's account if not set when adding a user. |
|
|
— |
A CSV list of workdays, with each value indicating a day in the schedule and values ranging from Used with |
|
|
— |
A CSV list of values for the user's default workhours and workhours for each day. At least one value for workschedule_workhours must be submitted, but a value for each day may be submitted as well. For example, if the user's workschedule_workdays is set to “ Used with |
|
|
|
The internal ID of the user's work schedule [ |
Usage Guidelines
Review the following guidelines:
-
Notes on relevant access privileges and role permissions:
-
To view, create or modify a user record or generic user record, the primary filter set assigned to the authenticated user must allow access to that user record or generic user record.
-
To modify a guest user record, the primary filter set assigned to the authenticated user must allow access to all users.
-
To create or modify a user record (other than the authenticated user's own record), the authenticated user must be an administrator or have the View, modify, and create new users or View and modify users role permission.
-
To modify user settings [
flags
], the authenticated user must be an administrator. -
All authenticated users can modify their own user record without the View, modify, and create new users and View and modify users role permission role permissions.
-
The
role_id
property can be set to1
(Administrator) only if the role authenticated user is Administrator. -
The
filterset_ids
property can be changed by any authenticated user with the Modify filter sets for existing things role permission, even if that authenticated does not have the View, modify, and create new users or View and modify users role permission. -
To create or modify a generic user record, the authenticated user must be an administrator or have the View and modify generics role permission.
-
-
To add users, use the
CreateUser
(XML API) orcreateUser()
(SOAP API) command instead of theAdd
oradd()
command. -
Limits are enforced to prevent you from creating or activating users if doing so would exceed the number of user licenses purchased for your account. If no user licenses of the appropriate type are available, the
CreateUser
(XML API) orcreateUser()
(SOAP API) command creates a new user record, but sets it as inactive (clears the Active box on the employee record), and theCreateUser
(XML API) orModify
(XML API) ormodify()
(SOAP API) commands cannot be used to activate a user record (to check the Active box on the employee record). For more information about OpenAir licensing and compliance, see Licenses. -
You can use the
generic
attribute to1
when readingUser
objects to return generic resources only. See Read Attributes. -
When adding a user, default values are used for approval fields (
<transaction>_approvalprocess
and<transaction>_approver
where<transaction>
, typically a two-letter code, designates the transaction type) if not set. Unless default values were set when adding a user in the OpenAir UI, the head of the department associated with the user (if set), or the first account administrator (otherwise) is the default approver. -
When adding or modifying a user, you can the following information for that user:
-
Loaded cost – See Updating User Loaded Costs.
-
Entity tag – See Updating User Entity Tags.
-
Work schedule – See Setting User Work Schedule.
-
Updating User Loaded Costs
You can set or update user loaded cost information when creating or updating a user object. To do so, use the following property values:
Property |
Value |
Notes |
---|---|---|
|
|
— |
|
|
— |
|
|
If an empty value is used, the |
|
New loaded cost value. |
— |
|
The currency of the new loaded cost value. |
— |
|
The loaded cost level, if multiple cost levels are enabled for your account. Defaults to |
— |
To read user loaded cost information, use the LoadedCost
object.
Updating User Entity Tags
You can set or update the user entity tags when creating or updating a user object. To do so, use the following property values:
Property |
Value |
Notes |
---|---|---|
|
|
— |
|
|
— |
|
|
Use an empty value to set the entity tag as the default entity tag for the user valid from |
|
ID of the tag group for the new entity tag. |
— |
|
The ID of the tag group attribute assigned to the new entity tag. |
— |
To read user entity tag information, use the Entitytag
object.
Setting User Work Schedule
You can set or update the user work schedule when creating or updating a user object. To do so, use the following property values:
Property |
Value |
Notes |
---|---|---|
|
|
— |
|
|
— |
|
Comma-separated list of numbers for usual work days. Each day of the week is represented by a number from |
Used if |
|
|
Used if To allow for different work hours, check the Enable distinct work hours per day on work schedule box on the Optional Features administration form (Administration > Global Settings > Optional Features) |
|
The ID of the company work schedule. |
Used if |
To read user work schedule information, use the UserWorkschedule
object.