User Methods

class netlab.api.UserApiMixin
user_account_add(*, com_id, acc_user_id, acc_password, acc_full_name, acc_type=<AccountType.STUDENT: 'S'>, acc_privs=None, acc_display_name=None, acc_sort_name=None, acc_email=None, acc_can_login=True, acc_pw_change=True, cls_id=None, tz_id=11, date_format=<DateFormat.ISO: 'ISO'>, time_format=<TimeFormat.HOUR24: '24'>, first_weekday=0, page_length=25, **kwargs)

Add a user account on the NETLAB system. For accepted values see the properties documentation for user_account_get().

Parameters

  • com_id (int) – Community ID.

  • acc_user_id (str) – User Account ID.

  • acc_password (str) – Unencrypted account password.

  • acc_full_name (str) – Account full name.

  • acc_type (AccountType) – Account type.

  • acc_can_login (bool) – User can login. Defaults to True.

  • acc_pw_change (bool) – Upon first login, force user to change password. Defaults to True.

  • acc_privs (list[AccountPrivileges]) – Supplemental account privileges for instructors in list or tuple format.

  • acc_display_name (str) – Account name, people will see this name in discussions, messages, and comments.

  • acc_sort_name (str) – Account name as it appears in sorted lists.

  • acc_email (str) – Account email address.

  • cls_id (int) – Class ID. (If you want to add user directly to a class during account creation.)

  • tz_id (int) – Timezone identifier. Defaults to 11.

  • date_format (DateFormat) – Date format preference.

  • time_format (TimeFormat) – Time format preference.

  • first_weekday (int) – First day of week preference.

  • page_length (int) – The number of items to display in paginated lists.

Returns

On success, returns acc_id.

Return type

int

user_account_get(*, acc_id, properties='default', **kwargs)

Retrieves a user account on the NETLAB system.

Parameters

  • acc_id (int) – User Account ID.

  • properties (list[str] or 'all' or 'default') – Properties consist of any combination of properties listed below under Properties. You may also use “all” to include all properties, or “default” for a smaller subset of properties.

Returns

Account data for the requested acc_id with the requested properties.

Return type

dict

Properties

acc_can_login

User allowed to login.

acc_display_name

Account name people will see this name in discussions, messages and comments.

acc_email

Account email.

acc_fs_id

Filesystem identifier of the account root folder.

acc_full_name

Account full name.

acc_id

Account identifier.

acc_last_ip

Last IP address of user.

acc_last_login

Datetime of last account login.

acc_last_ua

User agent string of the browser when logging in from the UI.

acc_logins

Number of account logins.

acc_privs

Supplemental account privileges for instructors only. AccountPrivileges

acc_pw_change

Force user to change password.

acc_session_time_started

Datetime of session start time.

acc_sort_name

Account name as it appears in sorted lists.

acc_sys

Mark as system account.

acc_time_created

Datetime account was created.

acc_time_last_access

Datetime of last access.

acc_type

Account type. AccountType

acc_user_id

Unique system-wide login identifier.

acc_uuid

Globally unique account ID.

com_full_name

Community name.

com_id

Unique community identifier.

tz_iana

Timezone IANA database identifier.

tz_id

Time zone identifier.

tz_name

Time zone name.

acc_nlx_terms

Lab designer terms and conditions acknowleged.

acc_npd_terms

Pod designer terms and conditions acknowleged.

acc_pw_console

Instructor’s lab device console password.

acc_pw_enable

Instructor’s lab device enable password.

accman_list_com_id

Persist account manager community selection in list view (admin and syswide).

date_format

Date format preference. netlab.enums.DateFormat

time_format

Time format preference. netlab.enums.TimeFormat

first_weekday

First day of week preference. An integer from 0 - 6 mapping to Sunday - Saturday.

page_length

The number of items to display in paginated lists. Possible values are 10, 25, 50, 100. A value of -1 will disable pagination and return all items.

user_account_list(*, com_id=None, acc_type=None, properties='default', **kwargs)

Query a list of the user accounts in the NETLAB system. The list method is only restricted by community id and account types. The properties only identify those properties or fields that will be returned via the underlying query.

Parameters

  • com_id (int) – Community ID

  • acc_type (AccountType) – User account type.

  • properties (list[str] or 'all' or 'default') – Properties consist of any combination of properties listed below under Properties. You may also use “all” to include all properties, or “default” for a smaller subset of properties.

Returns

A list of dictionaries (a set of records) where the dictionaries contain requested properties per user.

Properties

acc_can_login

User allowed to login.

acc_display_name

Account name people will see this name in discussions, messages and comments.

acc_email

Account email.

acc_fs_id

Filesystem identifier of the account root folder.

acc_full_name

Account full name.

acc_id

Account identifier.

acc_last_ip

Last IP address of user.

acc_last_login

Datetime of last account login.

acc_last_ua

User agent string of the browser when logging in from the UI.

acc_logins

Number of account logins.

acc_privs

Supplemental account privileges for instructors only. netlab.enums.AccountPrivileges

acc_pw_change

Force user to change password.

acc_session_time_started

Datetime of session start time.

acc_sort_name

Account name as it appears in sorted lists.

acc_sys

Mark as system account.

acc_time_created

Datetime account was created.

acc_time_last_access

Datetime of last access.

acc_type

Account type. netlab.enums.AccountType

acc_user_id

Unique system-wide login identifier.

acc_uuid

Globally unique account ID.

com_id

Unique community identifier.

tz_id

Time zone identifier.

user_account_password_set(*, acc_id, new_password, force_reset=False, **kwargs)

Sets the user account password.

Parameters

  • acc_id (int) – Account ID.

  • new_password (str) – New account password.

  • force_reset (bool) – Force user to reset password. Defaults to False.

Returns

The change succeeded.

Return type

‘OK’

user_account_remove(*, acc_id, **kwargs)

Removes the specified user account.

Parameters

acc_id (int) – User Account ID

Returns

The change succeeded.

Return type

‘OK’

This method queries and/or retrieves user accounts. Also see user_account_search_iter().

Filters and returns paged results of user accounts. Any property from user_account_list() can be filtered upon. Multiple filter will be combined using AND. Returns zero or more user accounts that match filter query.

Parameters

  • properties (list[str] or 'all' or 'default') – Properties consist of any combination of properties listed below under Properties. You may also use “all” to include all properties, or “default” for a smaller subset of properties.

  • order (str or list) – List of properties to sort by in order of preference.

  • filter (dict) – Search criteria. See below for how to use filters.

  • limit (int) – Page size or maximum number of records returned. This method can return a maximum of 500 use account records. Call the method multiple times with successive page numbers to return all data.

  • page (int) – Starting page number (pages start at one). When page is None, returns only info like ‘total_records’ with no accounts. A page that goes pass all records will return no accounts.

  • offset (int) – Starting record number. If page and offset are both None, no records are returned; only meta data about total users and pages are returned.

Returns

A list of user accounts that match filter.

Return type

dict

Examples

Collect the account id and account user id with acc_id that is 100031.

Client().user_account_search(properties=[‘acc_id’, ‘acc_user_id’], page=1, filter={‘acc_id’: 100031})

Collect first page of accounts, ordered by acc_id.

Client().user_account_search(properties=[‘acc_id’, ‘acc_user_id’], page=1, order=’acc_id’)

Return how many users can login.

Client().user_account_search(filter={‘acc_can_login’: True})[‘total_records’]

Properties

The following properties may be used in this method. The text in bold indicates the contexts in which the property may be used (see contexts below). The text following the | character describes the property.

Properties in communities and timezones must be fully qualified (i.e. timezones.tz_name). Properties starting with accounts my be specified without namespace (i.e. acc_full_name or accounts.acc_full_name may be used).

accounts.acc_can_login

SELECT, FILTER, ORDER | Logins enabled flag.

accounts.acc_display_name

SELECT, FILTER, ORDER | User display name.

accounts.acc_email

SELECT, FILTER, ORDER | Email address (RFC 2822).

accounts.acc_full_name

SELECT, FILTER, ORDER | User full name.

accounts.acc_id

SELECT, FILTER, ORDER | Local account identifier on system.

accounts.acc_last_ip

SELECT, FILTER, ORDER | Last IP address of user.

accounts.acc_last_login

SELECT, FILTER, ORDER | Timestamp of last account login.

accounts.acc_last_ua

SELECT, FILTER, ORDER | Last user agent string.

accounts.acc_logins

SELECT, FILTER | Number of times user has logged in.

accounts.acc_privs

SELECT, FILTER | Account privileges.

accounts.acc_pw_change

SELECT, FILTER | Password change pending on next login.

accounts.acc_session_time_started

SELECT, FILTER, ORDER | Timestamp of session start time.

accounts.acc_sort_name

SELECT, FILTER, ORDER | User’s sortable display name.

accounts.acc_sys

SELECT, FILTER, ORDER | System account flag.

accounts.acc_time_created

SELECT, FILTER, ORDER | Time account was created.

accounts.acc_time_last_access

SELECT, FILTER, ORDER | Time acocunts was last accessed.

accounts.acc_type

SELECT, FILTER, ORDER | Account type.

accounts.acc_user_id

SELECT, FILTER, ORDER | Local user ID on system.

accounts.acc_uuid

SELECT, FILTER | Globally unique account identifier.

accounts.com_id

SELECT, FILTER, ORDER | Local community identifier on system.

accounts.tz_id

SELECT, FILTER, ORDER | Timezone identifier.

communities.com_enabled

SELECT, FILTER, ORDER | Community enabled flag.

communities.com_full_name

SELECT, FILTER, ORDER | Community name.

communities.com_id

SELECT, FILTER, ORDER | Local community identifier on system.

communities.com_max_slots_per_res

SELECT, FILTER, ORDER | Community maximum slots per reservation.

communities.com_min_hours_btw_res

SELECT, FILTER, ORDER | Community minimum hours between reservations.

communities.com_mynetlab_news

SELECT, FILTER | Community MyNetlab page news markdown.

communities.com_mynetlab_welcome

SELECT, FILTER | Community MyNetlab page welcome markdown.

communities.com_tz_id

SELECT, FILTER, ORDER | Timezone identifier.

communities.com_uuid

SELECT, FILTER | Globally unique community identifier.

timezones.tz_iana

SELECT, FILTER, ORDER | Timezone IANA identifier.

timezones.tz_id

SELECT, FILTER, ORDER | Timezone identifier.

timezones.tz_name

SELECT, FILTER, ORDER | Timezone name.

timezones.tz_sort

SELECT, FILTER, ORDER | Timezone sort order.

user_account_search_iter(*, properties, order=None, filter=None, limit=100, **kwargs)

This method queries and/or retrieves user accounts.

Gets all users from server and then performs filtering locally. Any property from user_account_list() can be filtered upon. Multiple filter will be combined using AND. Returns zero or more user accounts that match filter query.

Parameters

  • properties (list[str] or 'all' or 'default') – Properties consist of any combination of properties listed below under Properties. You may also use “all” to include all properties, or “default” for a smaller subset of properties.

  • order (str or list) – Sort order.

  • filter (dict) – Search criteria. See below for how to use filters.

  • limit (int) – Page size collected in a single request from the server. This can be used to tune performace over large record sets. Maximum 500.

Returns

A series of user accounts that match filter. This method returns an iterator, which can be used in for loops like a list. See [the offical Python documenation](https://docs.python.org/3.6/library/stdtypes.html#iterator-types) for more infomation.

Return type

iter[dict]

Examples

Collect the account id and account user id with acc_id that is 100031.

Client().user_account_search_iter(properties=[‘acc_id’, ‘acc_user_id’], filter={‘acc_id’: 100031})

Collect first page of accounts, ordered by acc_id.

Client().user_account_search_iter(properties=[‘acc_id’, ‘acc_user_id’], order=’acc_id’)

Return how many users can login.

Client().user_account_search_iter(properties=[‘acc_id’], filter={‘acc_can_login’: True,

‘communities.com_id’: 1})

Properties

The following properties may be used in this method. The text in bold indicates the contexts in which the property may be used (see contexts below). The text following the | character describes the property.

Properties in communities and timezones must be fully qualified (i.e. timezones.tz_name). Properties starting with accounts my be specified without namespace (i.e. acc_full_name or accounts.acc_full_name may be used).

accounts.acc_can_login

SELECT, FILTER, ORDER | Logins enabled flag.

accounts.acc_display_name

SELECT, FILTER, ORDER | User display name.

accounts.acc_email

SELECT, FILTER, ORDER | Email address (RFC 2822).

accounts.acc_full_name

SELECT, FILTER, ORDER | User full name.

accounts.acc_id

SELECT, FILTER, ORDER | Local account identifier on system.

accounts.acc_last_ip

SELECT, FILTER, ORDER | Last IP address of user.

accounts.acc_last_login

SELECT, FILTER, ORDER | Timestamp of last account login.

accounts.acc_last_ua

SELECT, FILTER, ORDER | Last user agent string.

accounts.acc_logins

SELECT, FILTER | Number of times user has logged in.

accounts.acc_privs

SELECT, FILTER | Account privileges.

accounts.acc_pw_change

SELECT, FILTER | Password change pending on next login.

accounts.acc_session_time_started

SELECT, FILTER, ORDER | Timestamp of session start time.

accounts.acc_sort_name

SELECT, FILTER, ORDER | User’s sortable display name.

accounts.acc_sys

SELECT, FILTER, ORDER | System account flag.

accounts.acc_time_created

SELECT, FILTER, ORDER | Time account was created.

accounts.acc_time_last_access

SELECT, FILTER, ORDER | Time acocunts was last accessed.

accounts.acc_type

SELECT, FILTER, ORDER | Account type.

accounts.acc_user_id

SELECT, FILTER, ORDER | Local user ID on system.

accounts.acc_uuid

SELECT, FILTER | Globally unique account identifier.

accounts.com_id

SELECT, FILTER, ORDER | Local community identifier on system.

accounts.tz_id

SELECT, FILTER, ORDER | Timezone identifier.

communities.com_enabled

SELECT, FILTER, ORDER | Community enabled flag.

communities.com_full_name

SELECT, FILTER, ORDER | Community name.

communities.com_id

SELECT, FILTER, ORDER | Local community identifier on system.

communities.com_max_slots_per_res

SELECT, FILTER, ORDER | Community maximum slots per reservation.

communities.com_min_hours_btw_res

SELECT, FILTER, ORDER | Community minimum hours between reservations.

communities.com_mynetlab_news

SELECT, FILTER | Community MyNetlab page news markdown.

communities.com_mynetlab_welcome

SELECT, FILTER | Community MyNetlab page welcome markdown.

communities.com_tz_id

SELECT, FILTER, ORDER | Timezone identifier.

communities.com_uuid

SELECT, FILTER | Globally unique community identifier.

timezones.tz_iana

SELECT, FILTER, ORDER | Timezone IANA identifier.

timezones.tz_id

SELECT, FILTER, ORDER | Timezone identifier.

timezones.tz_name

SELECT, FILTER, ORDER | Timezone name.

timezones.tz_sort

SELECT, FILTER, ORDER | Timezone sort order.

user_account_update(*, acc_id, acc_user_id=None, acc_type=None, acc_can_login=None, acc_pw_change=None, acc_password=None, acc_privs=None, acc_full_name=None, acc_display_name=None, acc_sort_name=None, acc_email=None, tz_id=None, date_format=None, time_format=None, first_weekday=None, page_length=None, **kwargs)

Update the user account. For accepted values see the properties documentation for user_account_get().

Parameters

  • acc_id (int) – Account ID

  • acc_user_id (str) – Unique system-wide login identifier.

  • acc_type (AccountType) – Account type.

  • acc_can_login (bool) – User allowed to login.

  • acc_pw_change (bool) – Force user to change password.

  • acc_password (str) – Account password

  • acc_privs (list[AccountPrivileges]) – Supplemental account privileges for instructors in list or tuple format.

  • acc_full_name (str) – Account full name.

  • acc_display_name (str) – Account name people will see this name in discussions, messages and comments.

  • acc_sort_name (str) – Account name as it appears in sorted lists.

  • acc_email (str) – Account e-mail address.

  • tz_id (int) – Timezone identifier.

  • date_format (DateFormat) – Date format preference.

  • time_format (TimeFormat) – Time format preference.

  • first_weekday (int) – First day of week preference.

  • page_length (int) – The number of items to display in paginated lists.

Returns

The change succeeded.

Return type

‘OK’

user_community_add(*, com_full_name, com_id, com_enabled=True, com_max_slots_per_res=None, com_min_hours_btw_res=None, com_mynetlab_news=None, com_mynetlab_welcome=None, **kwargs)

This method allows you to add a community to the NETLAB+ system.

Parameters

  • com_full_name (str) – Community full name.

  • com_id (int) – Community identifier.

  • com_enabled (bool) – Is community enabled.

  • com_max_slots_per_res (int) – Max amount of slots per reservation.

  • com_min_hours_btw_res (int) – Minimum hours between reservations.

  • com_mynetlab_news (str) – Community MyNETLAB+ news entry.

  • com_mynetlab_welcome (str) – Community MyNETLAB+ welcome message.

Returns

Community ID of the newly created community.

Return type

int

user_community_find(*, com_full_name, **kwargs)

This method allows you to find a community based on com_full_name.

Parameters

com_full_name (str) – Community full name.

Returns

The Community ID on success.

Return type

int or None

user_community_get(*, com_id, properties='default', **kwargs)

This method allows you to retrieve a community and its properties.

Parameters

  • com_id (int) – Community ID.

  • properties (list[str] or 'all') – Properties to return. Accepts string or list. See below for all available properties. You may also use “all” to include all properties.

Returns

An object with the properties requested:

Return type

dict

Properties

com_alt_banner

Alternate community banner.

com_alt_banner_height

Alternate banner height.

com_alt_banner_width

Alternate banner width.

com_enabled

Is community enabled.

com_full_name

Community full name.

com_id

Community identifier.

com_max_slots_per_res

Max amount of slots per reservation.

com_min_hours_btw_res

Minimum hours between reservations.

com_mynetlab_news

Community MyNETLAB+ news entry.

com_mynetlab_welcome

Community MyNETLAB+ welcome message.

user_community_list(*, properties='default', sort_property='com_id', **kwargs)

Retrieve a list of communities.

Parameters

  • properties (list[str] or 'all' or 'default') – Properties to return. Accepts string or list. See below for all available properties. You may also use “all” to include all properties.

  • sort_property (str) – Property to sort list by. Only com_id (default) and com_full_name are valid options.

Returns

A list of objects with the properties requested:

Return type

list[dict]

Properties

com_alt_banner

Alternate community banner.

com_alt_banner_height

Alternate banner height.

com_alt_banner_width

Alternate banner width.

com_enabled

Is community enabled.

com_full_name

Community full name.

com_id

Community identifier.

com_max_slots_per_res

Max amount of slots per reservation.

com_min_hours_btw_res

Minimum hours between reservations.

com_mynetlab_news

Community MyNETLAB+ news entry.

com_mynetlab_welcome

Community MyNETLAB+ welcome message.

user_community_remove(*, com_id, **kwargs)

This method allows you to remove a community.

Parameters

com_id (int) – Community identifier.

Returns

The change succeeded.

Return type

‘OK’

user_community_update(*, com_id, com_full_name=None, com_enabled=None, com_mynetlab_welcome=None, com_mynetlab_news=None, com_min_hours_btw_res=None, com_max_slots_per_res=None, com_ext_slots_per_res=None, **kwargs)

Update a community.

Parameters

  • com_id (int) – Community ID.

  • com_full_name (str) – Community full name.

  • com_enabled (bool) – Is community enabled.

  • com_mynetlab_welcome (str) – Community MyNETLAB+ welcome message.

  • com_mynetlab_news (str) – Community MyNETLAB+ news entry.

  • com_min_hours_btw_res (int) – Minimum hours between reservations.

  • com_max_slots_per_res (int) – Max amount of slots per reservation.

  • com_ext_slots_per_res (int or enums.CommunityExtensionSlots) – Allow extensions to reservations for students and teams. Instructors are not restricted to this limit.

Returns

The update completed successfully.

Return type

‘OK’

user_logins_system_get(**kwargs)

This method allows you to query the User Logins status and number of active logins.

Returns

A dictionary with the following properties:

Return type

dict

active

Number of active users logged in.

enabled

User logins status.

user_logins_system_set(*, enabled, logout=False, **kwargs)

This method allows you to enable and disable user logins.

Parameters

  • enabled (bool) – Enable or disable user logins.

  • logout (bool) – Logout users that are already logged in.

Returns

A dictionary with the following properties:

Return type

dict

changed

Whether user login status was changed.

logouts

Number of users logged out.

user_session_keepalive(*, acc_id, **kwargs)

This method performs a keepalive on a logged in user’s session and restarts their session timeout. The last access for the session is set to the current time.

Parameters

acc_id (int) – Local account identifier.

Returns

A dictionary with the following properties:

Return type

dict

acc_session_time_started

Session start time, or None if the administrator specifies an acc_id that is not logged in.

acc_time_last_access

Updated last access time, or None if the administrator specifies an acc_id that is not logged in.