Users & Identity

Domain Users represent the actual users of your application. Convergence provides an Identity Service to allow users to get information about the identity of other users in the system.

Domain Users

Domain users are those users who are allowed to log into the domain through the convergence client. Users are identified by two primary pieces of information:

  1. email address
  2. username

No two users in the system can have the same username or email. When retrieved from the server, a user's identity will have the following structure:

{
  username: "user",
  email: "user@example.com",
  firstName: "Joe",
  lastName: "User",
  displayName: "Joe User"
}

You can manage this information through the Convergence Administration Interface.

Identity Service

The identity service allows users to query for the identity of users. You can look up users explicitly by either username or email. Or, you can search for them using any number of fields. All requests return promises.

Looking Up Single Users

var identityService = domain.identity();

// We assume that the search parameter is a username.  
// This is identical to identityService.user("juser", "username") 
identityService.user("juser").then((user) => {
  console.log(user); // will be undefined if the user does not exist
});

// Alternatively, specify a lookup by email
identityService.user("user1@example.com", "email").then((user) => {
  console.log(user); // will be undefined if the user does not exist
});

Looking Up Multiple Users

var identityService = domain.identity();

// Lookup by username
identityService.users(["juser", "mhoward"]).then((users) => {
  users.forEach(user => console.log(user));
});

// Lookup by email
identityService.users(["user1@example.com", "user2@example.com"], "email").then((users) => {
  users.forEach(user => console.log(user));
});

Searching for Users

You can search for users using a basic wildcard search across multiple fields. The search method will return any user that contains the specified value anywhere in the specified fields.

var identityService = domain.identity();

identityService.search(
  ["firstName", "lastName"], // Search fields
  "smith", // search term
  0, // offset
  10, // limit
  true // ascending
).then((users) => {
  users.forEach(user => console.log(user));
});

Which would match the following: John Smith, Jane Smithers, Smithy McFlabaroo, etc.

Domain Users

The various methods in the identity service return information about individual users or collection of users. In both cases the objects that are returned are instances of the DomainUser class. The most commonly used methods are outlined below:

Field Description
username Returns the unique username of this user.
firstName Returns the first name of this user.
lastName Returns the last name of this user.
displayName Returns the display name for this user.
email Returns the email for this user.
isAnonymous Returns true if the user connected anonymously.

results matching ""

    No results matching ""