users

Creates, updates, deletes, gets or lists a users resource.

Overview

Name	users
Type	Resource
Id	aws.workmail.users

Fields

The following fields are returned by SELECT queries:

describe_user

Name	Datatype	Description
city	string	City where the user is located.
company	string	Company of the user.
country	string	Country where the user is located.
department	string	Department of the user.
disabled_date	string (date-time)	The date and time at which the user was disabled for WorkMail usage, in UNIX epoch time format.
display_name	string	The display name of the user.
email	string	The email of the user. (pattern: <code>[a-zA-Z0-9._%+-]{1,64}@[a-zA-Z0-9.-]+.[a-zA-Z-]{2,}</code>)
enabled_date	string (date-time)	The date and time at which the user was enabled for WorkMailusage, in UNIX epoch time format.
first_name	string	First name of the user.
hidden_from_global_address_list	boolean	If enabled, the user is hidden from the global address list.
identity_provider_identity_store_id	string	Identity Store ID from the IAM Identity Center. If this parameter is empty it will be updated automatically when the user logs in for the first time to the mailbox associated with WorkMail. (pattern: <code>^d-[0-9a-f]{10}$|^[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}$</code>)
identity_provider_user_id	string	User ID from the IAM Identity Center. If this parameter is empty it will be updated automatically when the user logs in for the first time to the mailbox associated with WorkMail. (pattern: <code>^([0-9a-f]{10}-|)[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}$</code>)
initials	string	Initials of the user.
job_title	string	Job title of the user.
last_name	string	Last name of the user.
mailbox_deprovisioned_date	string (date-time)	The date when the mailbox was removed for the user.
mailbox_provisioned_date	string (date-time)	The date when the mailbox was created for the user.
name	string	The name for the user. (pattern: <code>[\w-.]+(@[a-zA-Z0-9.-]+.[a-zA-Z0-9-]{2,})?</code>)
office	string	Office where the user is located.
state	string	The state of a user: enabled (registered to WorkMail) or disabled (deregistered or never registered to WorkMail). (ENABLED, DISABLED, DELETED)
street	string	Street where the user is located.
telephone	string	User's contact number.
user_id	string	The identifier for the described user.
user_role	string	In certain cases, other entities are modeled as users. If interoperability is enabled, resources are imported into WorkMail as users. Because different WorkMail organizations rely on different directory types, administrators can distinguish between an unregistered user (account is disabled and has a user role) and the directory administrators. The values are USER, RESOURCE, SYSTEM_USER, and REMOTE_USER. (USER, RESOURCE, SYSTEM_USER, REMOTE_USER)
zip_code	string	Zip code of the user.

list_users

Name	Datatype	Description
disabled_date	string (date-time)	The date indicating when the user was disabled from WorkMail use.
display_name	string	The display name of the user.
email	string	The email of the user. (pattern: <code>[a-zA-Z0-9._%+-]{1,64}@[a-zA-Z0-9.-]+.[a-zA-Z-]{2,}</code>)
enabled_date	string (date-time)	The date indicating when the user was enabled for WorkMail use.
id	string	The identifier of the user.
identity_provider_identity_store_id	string	Identity store ID from the IAM Identity Center. If this parameter is empty it will be updated automatically when the user logs in for the first time to the mailbox associated with WorkMail. (pattern: <code>^d-[0-9a-f]{10}$|^[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}$</code>)
identity_provider_user_id	string	User ID from the IAM Identity Center. If this parameter is empty it will be updated automatically when the user logs in for the first time to the mailbox associated with WorkMail. (pattern: <code>^([0-9a-f]{10}-|)[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}$</code>)
name	string	The name of the user. (pattern: <code>[\w-.]+(@[a-zA-Z0-9.-]+.[a-zA-Z0-9-]{2,})?</code>)
state	string	The state of the user, which can be ENABLED, DISABLED, or DELETED. (ENABLED, DISABLED, DELETED)
user_role	string	The role of the user. (USER, RESOURCE, SYSTEM_USER, REMOTE_USER)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_user	select	region		Provides information regarding the user.
list_users	select	region		Returns summaries of the organization's users.
create_user	insert	region, OrganizationId, DisplayName		Creates a user who can be used in WorkMail by calling the RegisterToWorkMail operation.
update_user	update	region, OrganizationId, UserId		Updates data for the user. To have the latest information, it must be preceded by a DescribeUser call. The dataset in the request should be the one expected when performing another DescribeUser call.
delete_user	delete	region		Deletes a user from WorkMail and all subsequent systems. Before you can delete a user, the user state must be DISABLED. Use the DescribeUser action to confirm the user state. Deleting a user is permanent and cannot be undone. WorkMail archives user mailboxes for 30 days before they are permanently removed.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_user

Provides information regarding the user.

SELECT
city,
company,
country,
department,
disabled_date,
display_name,
email,
enabled_date,
first_name,
hidden_from_global_address_list,
identity_provider_identity_store_id,
identity_provider_user_id,
initials,
job_title,
last_name,
mailbox_deprovisioned_date,
mailbox_provisioned_date,
name,
office,
state,
street,
telephone,
user_id,
user_role,
zip_code
FROM aws.workmail.users
WHERE region = '{{ region }}' -- required
;

list_users

Returns summaries of the organization's users.

SELECT
disabled_date,
display_name,
email,
enabled_date,
id,
identity_provider_identity_store_id,
identity_provider_user_id,
name,
state,
user_role
FROM aws.workmail.users
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_user

Creates a user who can be used in WorkMail by calling the RegisterToWorkMail operation.

INSERT INTO aws.workmail.users (
OrganizationId,
Name,
DisplayName,
Password,
Role,
FirstName,
LastName,
HiddenFromGlobalAddressList,
IdentityProviderUserId,
region
)
SELECT 
'{{ OrganizationId }}' /* required */,
'{{ Name }}',
'{{ DisplayName }}' /* required */,
'{{ Password }}',
'{{ Role }}',
'{{ FirstName }}',
'{{ LastName }}',
{{ HiddenFromGlobalAddressList }},
'{{ IdentityProviderUserId }}',
'{{ region }}'
RETURNING
user_id
;

Manifest

# Description fields are for documentation purposes
- name: users
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the users resource.
  - name: OrganizationId
    value: "{{ OrganizationId }}"
    description: |
      The identifier of the organization for which the user is created.
  - name: Name
    value: "{{ Name }}"
    description: |
      The name for the new user. WorkMail directory user names have a maximum length of 64. All others have a maximum length of 20.
  - name: DisplayName
    value: "{{ DisplayName }}"
    description: |
      The display name for the new user.
  - name: Password
    value: "{{ Password }}"
    description: |
      The password for the new user.
  - name: Role
    value: "{{ Role }}"
    description: |
      The role of the new user. You cannot pass SYSTEM_USER or RESOURCE role in a single request. When a user role is not selected, the default role of USER is selected.
    valid_values: ['USER', 'RESOURCE', 'SYSTEM_USER', 'REMOTE_USER']
  - name: FirstName
    value: "{{ FirstName }}"
    description: |
      The first name of the new user.
  - name: LastName
    value: "{{ LastName }}"
    description: |
      The last name of the new user.
  - name: HiddenFromGlobalAddressList
    value: {{ HiddenFromGlobalAddressList }}
    description: |
      If this parameter is enabled, the user will be hidden from the address book.
  - name: IdentityProviderUserId
    value: "{{ IdentityProviderUserId }}"
    description: |
      User ID from the IAM Identity Center. If this parameter is empty it will be updated automatically when the user logs in for the first time to the mailbox associated with WorkMail.

UPDATE examples

update_user

Updates data for the user. To have the latest information, it must be preceded by a DescribeUser call. The dataset in the request should be the one expected when performing another DescribeUser call.

UPDATE aws.workmail.users
SET 
OrganizationId = '{{ OrganizationId }}',
UserId = '{{ UserId }}',
Role = '{{ Role }}',
DisplayName = '{{ DisplayName }}',
FirstName = '{{ FirstName }}',
LastName = '{{ LastName }}',
HiddenFromGlobalAddressList = {{ HiddenFromGlobalAddressList }},
Initials = '{{ Initials }}',
Telephone = '{{ Telephone }}',
Street = '{{ Street }}',
JobTitle = '{{ JobTitle }}',
City = '{{ City }}',
Company = '{{ Company }}',
ZipCode = '{{ ZipCode }}',
Department = '{{ Department }}',
Country = '{{ Country }}',
Office = '{{ Office }}',
IdentityProviderUserId = '{{ IdentityProviderUserId }}'
WHERE 
region = '{{ region }}' --required
AND OrganizationId = '{{ OrganizationId }}' --required
AND UserId = '{{ UserId }}' --required;

DELETE examples

delete_user

Deletes a user from WorkMail and all subsequent systems. Before you can delete a user, the user state must be DISABLED. Use the DescribeUser action to confirm the user state. Deleting a user is permanent and cannot be undone. WorkMail archives user mailboxes for 30 days before they are permanently removed.

DELETE FROM aws.workmail.users
WHERE region = '{{ region }}' --required
;