User email management

A user may have a primary email address and possibly one or more unique alternative addresses attached to their profile that have accumulated for various reasons. It is important to know which of these addresses are valid so an accurate one-to-many mapping can be created for the user. In this way, users can be monitored when they sign in and license usage data can correctly reflect the active users.

The user can link one or more unique alternative email addresses to their profile, all of which need verification. Unverified alternative emails are ignored during matching with CloudBees CI user login event emails. But primary emails do not require any verification and they are used during matching with CloudBees CI user login event emails.

createUserEmail

Creates a new alternative user/email address mapping.

Arguments Descriptions

Arguments	Descriptions
userName	An existing user name. This could be the user’s full name, but more commonly it is the shortened name, first initial and last name, or nickname used for email. Argument type: String
email	The new alternative email address of the user. This field has a format restriction based on the regex pattern `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,6}$`, while the email content, itself, does not have any restrictions on the content. Argument type: String

userName

An existing user name. This could be the user’s full name, but more commonly it is the shortened name, first initial and last name, or nickname used for email.

Argument type: String

The new alternative email address of the user. This field has a format restriction based on the regex pattern ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,6}$, while the email content, itself, does not have any restrictions on the content.

Argument type: String

Positional arguments

userName, email

Request and response

ectool createUserEmail mjones mary.jones@example.com▼

<response requestId="1" nodeId="192.168.1.217">
    <userEmail>
      <userEmailId>55d262d6-faf3-11eb-9c33-4ccc6a9b547d</userEmailId>
      <createTime>2021-08-11T22:27:38.878Z</createTime>
      <email>mary.jones@example.com</email>
      <lastModifiedBy>admin</lastModifiedBy>
      <modifyTime>2021-08-11T22:27:38.878Z</modifyTime>
      <owner>admin</owner>
      <status>UNVERIFIED</status>
      <userName>mjones</userName>
    </userEmail>
</response>▼

deleteUserEmail

Deletes a new user/email address mapping.

Arguments	Descriptions
userName	This could be the user’s full name, but more commonly it is the shortened name, first initial and last name, or nickname used for email. Argument type: String
email	The new email address of the user. Argument type: String

Arguments

Descriptions

userName

This could be the user’s full name, but more commonly it is the shortened name, first initial and last name, or nickname used for email.

Argument type: String

The new email address of the user.

Argument type: String

Positional arguments

userName email

Request and response

ectool deleteUserEmail "aallen" "aallen@example.com"▼

No response is sent back.

getUserEmail

Retrieves the specified user/email mapping.

You must specify the userName.

Arguments	Descriptions
userName	This could be the user’s full name, but more commonly it is the shortened name, first initial and last name, or nickname used for email. Argument type: String
email	The email address of the user. Argument type: String

Arguments

Descriptions

userName

This could be the user’s full name, but more commonly it is the shortened name, first initial and last name, or nickname used for email.

Argument type: String

The email address of the user.

Argument type: String

Positional arguments

userName email

Request and response

ectool.exe getUserEmail mjones mary.jones@example.com▼

<response requestId="1" nodeId="192.168.1.217">
    <userEmail>
      <userEmailId>55d262d6-faf3-11eb-9c33-4ccc6a9b547d</userEmailId>
      <createTime>2021-08-11T22:27:38.878Z</createTime>
      <email>mary.jones@example.com</email>
      <lastModifiedBy>admin</lastModifiedBy>
      <modifyTime>2021-08-11T22:27:38.878Z</modifyTime>
      <owner>admin</owner>
      <status>UNVERIFIED</status>
      <userName>mjones</userName>
    </userEmail>
</response>▼

getUserEmails

Returns all user/email mappings for the specified user.

Arguments	Descriptions
userName	This could be the user’s full name, but more commonly it is the shortened name, first initial and last name, or nickname used for email. Argument type: String
email	The email address of the user. Argument type: String

Arguments

Descriptions

userName

This could be the user’s full name, but more commonly it is the shortened name, first initial and last name, or nickname used for email.

Argument type: String

The email address of the user.

Argument type: String

Positional arguments

userName

Request and response

ectool getUserEmails mjones▼

<response requestId="1" nodeId="192.168.1.217">
    <userEmail>
      <userEmailId>55d262d6-faf3-11eb-9c33-4ccc6a9b547d</userEmailId>
      <createTime>2021-08-11T22:27:38.878Z</createTime>
      <email>mary.jones@example.com</email>
      <lastModifiedBy>admin</lastModifiedBy>
      <modifyTime>2021-08-11T22:27:38.878Z</modifyTime>
      <owner>admin</owner>
      <status>UNVERIFIED</status>
      <userName>mjones</userName>
    </userEmail>
    <userEmail>
      <userEmailId>425696f5-faf3-11eb-8eb6-4ccc6a9b547d</userEmailId>
      <createTime>2021-08-11T22:27:06.127Z</createTime>
      <email>mjones2@example.com</email>
      <lastModifiedBy>admin</lastModifiedBy>
      <modifyTime>2021-08-11T22:27:06.127Z</modifyTime>
      <owner>admin</owner>
      <status>UNVERIFIED</status>
      <userName>mjones</userName>
    </userEmail>
</response>▼

verifyUserEmail

For use in a test or QE environment, this endpoint verifies the email address for the specified user. It simulates the logic of email verification by the user, via a signature token, without actually sending the email to the user.

In a production system, verification email is sent

Via the CloudBees Software Delivery Automation server to the user automatically when an alternative email is created or modified.
Via special verify action in the CloudBees CI Licenses for unverified CloudBees CI users.

Arguments	Descriptions
email	The email address of the user.
signature	Signature to use for verification. Argument type: String

Arguments

Descriptions

The email address of the user.

signature

Signature to use for verification.

Argument type: String

Positional arguments

email

Example verification sequence

Consider this user/email mapping for an alternative, unverified user email for test@example.com:

<userEmail>
      <userEmailId>108a7873-db0d-11eb-a114-080027053628</userEmailId>
      <createTime>2021-07-02T08:11:12.348Z</createTime>
      <email>test@example.com</email>
      <lastModifiedBy>admin</lastModifiedBy>
      <modifyTime>2021-07-02T08:11:12.348Z</modifyTime>
      <owner>admin</owner>
      <status>UNVERIFIED</status>
      <userName>admin</userName>
</userEmail>▼

Verification request for particular email is sent to the CloudBees Software Delivery Automation server. The server simulates the user verification by returning a signature. This phase:
- Sends an email request to verify user’s email with specified address.
- Returns a signature for specified email address.
  
  This phase does not require that the user email address already exists in the CloudBees Software Delivery Automation system as a user email entity. And even if this user email already exists, this phase does not require that it owned by the currently logged CloudBees Software Delivery Automation user. For example, the CloudBees Software Delivery Automation admin user may request verification for user mail that belongs to another CloudBees Software Delivery Automation user.
  
  Request:
  ectool verifyUserEmail test@example.com
  ▼
  Response:
  <response requestId="1" nodeId="192.168.178.41"> <signature> Z0V6ODR1eHBTTGVXMGFCK3NXUEFOQ0h\ VNU9ZS21qLzBZVmgveksxOXlWST0= </signature> </response>
  ▼

Request the verified userEmail object using the signature returned by the CloudBees Software Delivery Automation server from the initial request. This phase:

Changes the status of the currently existing user email address belonging to the current user to VERIFIED.

Creates a new user email address for the current user immediately with the status VERIFIED.

Request:

ectool verifyUserEmail test@mail.com \
       --signature Z0V6ODR1eHBTTGVXMGFCK3NXUEFOQ0hVNU9ZS21qLzBZVmgveksxOXlWST0=▼

Response:

<response requestId="1" nodeId="192.168.178.41">
    <userEmail>
      <userEmailId>108a7873-db0d-11eb-a114-080027053628</userEmailId>
      <createTime>2021-07-02T08:11:12.348Z</createTime>
      <email>test@example.com</email>
      <lastModifiedBy>admin</lastModifiedBy>
      <modifyTime>2021-07-02T08:12:04.288Z</modifyTime>
      <owner>admin</owner>
      <status>VERIFIED</status>
      <userName>admin</userName>
    </userEmail>
  </response>▼

Note that this response confirms the email has been verified.

modifyUserEmail

Modifies a user/email mapping.

Arguments	Descriptions
userName	This could be the user’s full name, but more commonly it is the shortened name, first initial and last name, or nickname used for email. Argument type: String
email	The email address of the user. Argument type: String
newEmail	The new email address for this mapping.

Arguments

Descriptions

userName

This could be the user’s full name, but more commonly it is the shortened name, first initial and last name, or nickname used for email.

Argument type: String

The email address of the user.

Argument type: String

newEmail

The new email address for this mapping.

Positional arguments

userName email

Request and response

ectool modifyUserEmail mjones mjones2@example.com --newEmail mjones.old@example.com▼

<response requestId="1" nodeId="192.168.1.217">
    <userEmail>
      <userEmailId>425696f5-faf3-11eb-8eb6-4ccc6a9b547d</userEmailId>
      <createTime>2021-08-11T22:27:06.127Z</createTime>
      <email>mjones.old@example.com</email>
      <lastModifiedBy>admin</lastModifiedBy>
      <modifyTime>2021-08-11T22:27:06.127Z</modifyTime>
      <owner>admin</owner>
      <status>UNVERIFIED</status>
      <userName>mjones</userName>
    </userEmail>
</response>▼