Users.idl

Go to the documentation of this file.

/**
 * @file   Users.idl
 * @brief  Work with user accounts as an representation of physical email boxes.
 *
 * @author Dusan Juhas, Martin Kuchar
 *
 * @copyright Copyright © 2017 Kerio Technologies s.r.o.
 */

#import <kerio/web/idl/SharedStructures.idl>
#import <AdminStructures.idl> //ActionAfterDays
#import <common.idl> //DateTimeStamp
#import <ContactsCommon.idl>
#import <DistributedDomain.idl> //HomeServer
#import <MobileCommon.idl>

module kerio {
module jsonapi {
module admin {

struct PublicFolder {
   kerio::web::KId id;
   string name;
};

typedef sequence<PublicFolder> PublicFolderList;

/**
 * List of email addresses
 */
typedef sequence<string> UserEmailAddressList;

/**
 * Export format type.
 */
enum FileFormatType {
   TypeXml, ///< Extensible Markup Language
   TypeCsv  ///< Comma Separated Values
};

/**
 * Type of user role.
 */
enum UserRoleType {
   UserRole,      ///< regular user without any administration rights
   Auditor,    ///< read only access to administration
   AccountAdmin,  ///< can administer Users,Groups,Aliases,MLs
   FullAdmin,     ///< unlimited administration
   BuiltInAdmin,  ///< BuiltIn admin role can be returned only in Session::WhoAmI method for built-in administrator. This role must NOT be assigned.
   BuiltInDomainAdmin   ///< BuiltIn domain admin role can be returned only in Session::WhoAmI method for built-in domain administrator. This role must NOT be assigned.
};

/**
 *
 * Note: all fields must be assigned if used in set methods.
 */
struct UserRight {
   UserRoleType   userRole;
   boolean        publicFolderRight;
   boolean        archiveFolderRight;
};

/**
 * Forwarding setup for user.
 */
enum UserForwardMode {
   UForwardNone,  ///< Forwarding is disabled
   UForwardYes,   ///< Forward all messages for this user to some addresses, don't deliver the message to the mailbox.
   UForwardDeliver   ///< Forward all messages for this user to some addresses, and also deliver the message to user's mailbox.
};

/**
 *  Type of deleting folder of the user
 */
enum UserDeleteFolderMode {
   UDeleteUser,   ///< Delete user without deleting his folder.
   UDeleteFolder, ///< Delete user and delete his folder.
   UMoveFolder    ///< Delete user and his folder will move into another user's folder.
};

/**
 * Settings of email forwarding.
 * Note: all fields must be assigned if used in set methods.
 */
struct EmailForwarding {
   UserForwardMode mode;
   UserEmailAddressList  emailAddresses; ///< list of email addresses, make sense only for UForwardDeliver
};

/**
 * Properties of user's groups.
 */
struct UserGroup {
   kerio::web::KId id;     ///< global identification
   string name;
   string description;
   DataSource itemSource;
};

/**
 * List of user's groups.
 */
typedef sequence<UserGroup> UserGroupList;

/**
 * Settings of items limit.
 * Note: all fields must be assigned if used in set methods.
 */
struct ItemCountLimit {
   boolean              isActive;
   long                 limit;
};

/**
 * Amount of storage used and items currently stored in user's store.
 */
struct QuotaUsage {
   long                 items;
   kerio::web::ByteValueWithUnits   storage;
};

/**
 * List of QuotaUsage.
 */
typedef sequence<QuotaUsage> QuotaUsageList;

/**
 * Last login information.
 */
struct LastLogin {
   DateTimeStamp  dateTime;   ///< date and time of last login
   string         protocol;   ///< protocol name of last login, example POP3
};

/**
 * Per-user message retention policy.
 */
struct CleanOut {
   boolean        isUsedDomain;  ///< use domain settings
   ActionAfterDays   deletedItems;  ///< clean Deleted Items folder (maximum: 24855)
   ActionAfterDays   junkEmail;     ///< clean Junk Email folder (maximum: 24855)
   ActionAfterDays sentItems;    ///< clean Sent Items folder (maximum: 24855)
   ActionAfterDays   autoDelete;    ///< clean all folders (maximum: 24855)
};

/**
 * User details.
 */
struct User {
   kerio::web::KId               id;                  ///< [READ-ONLY] global identification
   kerio::web::KId               domainId;            ///< [REQUIRED FOR CREATE] ID of domain where user belongs to
   kerio::web::KId               companyContactId;    ///< ID of company contact associated with this user

   string                     loginName;           ///< [REQUIRED FOR CREATE] [USED BY QUICKSEARCH] loginName name
   string                     fullName;            ///< [USED BY QUICKSEARCH]
   string                     description;         ///< [USED BY QUICKSEARCH]
   boolean                    isEnabled;           ///< user account is enabled/disabled
   DataSource                 itemSource;          ///< is user stored internally or by LDAP? This field cannot be used with Or queries.
   UserAuthType               authType;            ///< supported values must be retrieved from engine by ServerInfo::getSupportedAuthTypes()
   string                     password;            ///< [WRITE-ONLY]
   boolean                    isPasswordReversible;   ///< typically triple DES
   boolean                    allowPasswordChange; ///< if it is set to false the password can be changed only by the administrator
   boolean                 hasDefaultSpamRule;     ///< now: available only on user creation

    UserRight                 role;             ///< user role
   UserRight                  groupRole;           ///< the mightiest user role obtained via group membership
   UserRight                  effectiveRole;       ///< the mightiest user role from role and groupRole
    boolean                   isWritableByMe;         ///< Does caller have right to change the user? E.g. if Account Admin gets User structure for Full Admin, isWritableByMe will be false. This field is read-only and cannot be used in kerio::web::SearchQuery conditions.
    
    UserEmailAddressList         emailAddresses;         ///< List of user email addresses. His default one (loginName@domain) is not listed here
   EmailForwarding               emailForwarding;     ///< email forwarding setting
   UserGroupList              userGroups;          ///< groups membership
   ItemCountLimit             itemLimit;           ///< max. number of items
   kerio::web::SizeLimit         diskSizeLimit;       ///< max. disk usage
   long                    consumedItems;       ///< current items used
   kerio::web::ByteValueWithUnits   consumedSize;        ///< current disk usage
   boolean                    hasDomainRestriction;   ///< user can send/receive from/to his/her domain only
   kerio::web::SizeLimit         outMessageLimit;     ///< limit of outgoing message
   LastLogin                  lastLoginInfo;       ///< information about last login datetime and protocol
   boolean                    publishInGal;        ///< publish user in global address list? Default is true - the user will be published in Global Address Book.
   CleanOut                cleanOutItems;       ///< Items clean-out settings
   IdEntity                accessPolicy;        ///< ID and name of Access Policy applied for user. Only ID is writable.

   HomeServer                 homeServer;          ///< [WRITE-ONCE] Id of user's homeserver if server is in a distributed domain.
   kerio::web::OptionalEntity    migration;           ///< [READ-ONLY] migration.enabled is true if user's store is just being migrated and migration.id contains migration task id
};

/**
 * List of users.
 */
typedef sequence<User> UserList;

/**
* User effective rights (inherited from groups)
*/
struct EffectiveUserRights {
   kerio::web::KId      userId;                 ///< [READ-ONLY] global identification
   boolean           hasDomainRestriction;         ///< user can send/receive from/to his/her domain only
};

/**
 * List of users effective rights
 */
typedef sequence<EffectiveUserRights> EffectiveUserRightsList;

/**
 * Type of user directory
 */
enum ServerDirectoryType {
   WinNT,            ///< Windows NT Domain directory (Win NT 4.0)
   ActiveDirectory,  ///< Active Directory (Windows 2000 and newer)
   NovellEDirectory  ///< Novell eDirectory
};

/**
 * Properties of the server from which users are imported.
 */
struct ImportServer {
   ServerDirectoryType   directoryType;
   string      remoteDomainName;
   string      address;    ///< server IP or FQDN
   string      loginName;
   string      password;
   string      ldapFilter;
   boolean     isSecureConnection;
};

/**
 * Login statistics - count and timestamp of the last login.
 */
struct LoginStats {
   long       count;
   string     lastLogin;
};

/**
 * Statistics about user's usage of quota, logins to different services.
 */
struct UserStats {
   string      name;          ///< user's loginName
   QuotaUsage  occupiedSpace;
   LoginStats  pop3;
   LoginStats  securePop3;
   LoginStats  imap;
   LoginStats  secureImap;
   LoginStats  http;
   LoginStats  secureHttp;
   LoginStats  ldap;
   LoginStats  secureLdap;
   LoginStats  nntp;
   LoginStats  secureNntp;
   LoginStats  activeSync;
   LoginStats  secureActiveSync;
   LoginStats  xmpp;
   LoginStats  secureXmpp;
};

/**
 * List of users' statistics.
 */
typedef sequence<UserStats> UserStatList;

/**
 * Result of a mass operation.
 */
struct ResultTriplet {
   long inputIndex;
   long itemsCount;
};

/**
 * List of mass operation results.
 */
typedef sequence<ResultTriplet> ResultTripletList;

/**
 * User to be removed, what to do with his/her mailbox.
 */
struct RemovalRequest {
   kerio::web::KId      userId;        ///< ID of user to be removed
   UserDeleteFolderMode method;        ///< removal method
   boolean        removeReferences;    ///< if true all reference to this user is going to be removed as well
   kerio::web::KId         targetUserId;  ///< applicable only when moving user's store to another user, use empty string if not moving user's messages to target mailbox
   DirectoryServiceDeleteMode mode;       ///< delete mode
};

typedef sequence<RemovalRequest> RemovalRequestList;

/**
 * A user being imported from directory server.
 */
struct Importee {
   User  userItem;      ///< user data
   boolean  isImportable;  ///< [READ-ONLY] user can be imported
   string   message;    ///< [READ-ONLY] error message if user is not importable
};

typedef sequence<Importee> ImporteeList;

struct MailboxCount {
   long active;   ///< the number of active mailboxes on server
   long total;    ///< the number of created users on server
};

/**
 * Resut of autentication.
 */
enum AuthResult {
   AuthOK,           ///< User was autenticated
   AuthFail,         ///< Wrong login name or password.
   AuthUserDisabled, ///< User cannot to log in, because his account is disabled.
   AuthLicense,      ///< User cannot log in, because license limit was reached.
   AuthDenied,       ///< User is denied to log in.
   AuthTryLater      ///< User cannot to log in at this moment, try later.
};


/**
 * User accounts management.
 */
interface Users {

   /**
    * Activate user(s) from a directory service.
    *
    * @param errors - list of error messages for appropriate users
    * @param userIds - list of global user identifiers
    */
   void activate(out kerio::web::ErrorList errors, in kerio::web::KIdList userIds);

   /**
   * Activate user(s) from a directory service in distributed domain environment.
   *
   * @param errors - list of error messages for appropriate users
   * @param userIds - list of global user identifiers
   * @param homeServerId - Id of server in distributed domain on which users will be activated
   */
   void activateOnServer(out kerio::web::ErrorList errors, in kerio::web::KIdList userIds, in kerio::web::KId homeServerId);

   /**
    * Register connection.
    *
    * @param service - service name (should be some real service ID, returned by Services.get)
    * @param connectionId - unique connection identifier
    * @param port - host port
    * @param isSecure - ssl connection
    */
   void connectFromExternalService(out boolean result, in string service, in string connectionId, in string clientIpAddress, in long port, in boolean isSecure);

   /**
    * Authenticate given user and create session. connectionId must be registered by function connectFromExternalService otherwise authenticate fails.
    *
    * @param result - resut of autentication.
    * @param userName - login name + domain name (can be omitted if primary) of the user to be logged in, e.g. "jdoe" or "jdoe@company.com"
    * @param password - password of the user to be authenticate (base64-encoded)
    * @param connectionId - connection identifier, must be the same as in connectFromExternalService
    * @param isSecure - ssl connection
    */
   void authenticateConnectionFromExternalService(out AuthResult result, in string userName, in string password, in string service, in string connectionId, in boolean isSecure);

   /**
    * Unregister connection registered by connectFromExternalService and destroy session created if authenticateFromExternalService was called.
   * @param service - service name
   * @param connectionId - unique connection identifier
   */
   void disconnectFromExternalService(in string service, in string connectionId);

   /**
    * Cancel wiping of user's mobile device.
    *
    * @param userId - global user identifier
    * @param deviceId - ID of user's mobile device to cancel wipe
    */
   void cancelWipeMobileDevice(in kerio::web::KId userId, in string deviceId);

   /**
    * Check integrity of all folders in user(s) mailboxes.
    * If corrupted folder is found, try to fix it.
    *
    * @param userIds - list of user identifiers
    */
   void checkMailboxIntegrity(in kerio::web::KIdList userIds);

   /**
    * Create new users.
    *
    * @param errors - error message list
    * @param result - list of IDs of created users  
    * @param users - new user entities
    */
   void create(out kerio::web::ErrorList errors, out kerio::web::CreateResultList result, in UserList users);

   /**
   * Create new users in directory service
   * @param errors - error message list
   * @param result - list of IDs of created users
   * @param users - new user entities
   */
   void createLdap(out kerio::web::ErrorList errors, out kerio::web::CreateResultList result, in UserList users);

   /**
    * Export statistics of given users in given format.
    *
    * @param fileDownload - description of output file
    * @param userIds - list of IDs of given users
    * @param format - output data format
    */
   void exportStatistics(out kerio::web::Download fileDownload, in kerio::web::KIdList userIds, in FileFormatType format);

   /**
    * Export given domain users to comma-separated values file format.
    *
    * @param fileDownload - description of output file
    * @param filename - part of filename; full filename is compound as user_<domainname>_<filename>_<date>.csv
    * @param query - query attributes and limits
    * @param domainId - domain identification
   */
   void exportToCsv(out kerio::web::Download fileDownload, in string filename, in kerio::web::SearchQuery query, in kerio::web::KId domainId);

   /**
    * Obtain a list of users in given domain.
    *
    * @param list - users
    * @param totalItems - number of users found in given domain
    * @param query - query attributes and limits
    * @param domainId - domain identification
    */
   void get(out UserList list, out long totalItems, in kerio::web::SearchQuery query, in kerio::web::KId domainId);

   /**
    * Obtain a list of contact public folders in given domain.
    *
    * @param publicFolderList - list of public folders
    * @param domainId - global identification of domain
    */
   void getContactPublicFolderList(out PublicFolderList publicFolders, in kerio::web::KId domainId);

   /**
    * Obtain list of users from given LDAP server potentially importable to the Connect server.
    *
    * @param newUsers - list of users
    * @param importServer - properties of the server to import from
    * @param domainToImport - the mailserver domain where users are imported
    */
   void getFromServer(out ImporteeList newUsers, in ImportServer importServer, in kerio::web::KId domainToImport);

   /**
    * Obtain the number of users created on the server and number of active mailboxes.
    * This method may take a long time if a directory service for mapped users is not available.
    *
    * @param count - Number of users created on the server and number of active mailboxes.
    */
   void getMailboxCount(out MailboxCount count);

   /**
    * Obtain a list of mobile devices of given user.
    *
    * @param list - mobile devices of given user
    * @param totalItems - number of mobile devices found for given user
    * @param userId - name of user
    * @param query - query attributes and limits
    */
   void getMobileDeviceList(out kerio::jsonapi::mobile::MobileDeviceList list, out long totalItems, in kerio::web::KId userId, in kerio::web::SearchQuery query);

   /**
    * Obtain a list of LDAP mapped users who are not activated in given domain.
    * Only user's ID, loginName, fullName, description are set in structures.
    *
    * @param newUsers - list of users
    * @param domainId - global identification of domain
    */
   void getNotActivated(out ImporteeList newUsers, in kerio::web::KId domainId);

   /**
    * Obtain a size of items stored for recovering.
    *
    * @param errors - error message list
    * @param sizes - count and size of items
    * @param userIds - global identification of user
    */
   void getRecoveryDeletedItemsSize(out kerio::web::ErrorList errors, out QuotaUsageList sizeList, in kerio::web::KIdList userIds);

   /**
    * Obtain statistics of given users.
    *
    * @param list - users' statistics
    * @param userIds - list of IDs of given users
    * @param query - query parameters and limits
    */
   void getStatistics(out UserStatList list, in kerio::web::KIdList userIds, in kerio::web::SearchQuery query);

   /**
    * Parse users from given string. It is used to import users from file. The only supported encoding is UTF-8.
    *
    * @param users - list of parsed users with appropriate status and message
    * @param fileId - ID of the uploaded file
    * @param domainToImport - import to given domain, magic constants
    *                   'PRIMARY_DOMAIN': use primary domain
    *                   'PRESERVE_FROM_CSV': preserve domain from CSV file (use primary if not defined)
    */
   void parseFromCsv(out ImporteeList users, in string fileId, in kerio::web::KId domainToImport);

   /**
    * Recover deleted items for particular user(s).
    * If the user quota is exceeded an error with code 4000 will be returned.
    *
    * @param recoveryMessages - list of recovery messages
    * @param userIds - list of user IDs
    * @param recoverAnyway - if true messages are recovered even if the user quota is exceeded.
    */
   void recoverDeletedItems(out kerio::web::ErrorList errors, out ResultTripletList recoveryMessages, in kerio::web::KIdList userIds);

   /**
    * Remove user(s).
    *
    * @param errors - list of users failed to remove only (successfully removed are NOT listed)
    * @param requests - list of user IDs to be removed, method, and owner of deleted messages
    */
   void remove(out kerio::web::ErrorList errors, in RemovalRequestList requests);

   /**
    * Remove mobile device from the list of user's mobile devices.
    *
    * @param userId - name of user
    * @param deviceId - ID of user's mobile device to be removed
    */
   void removeMobileDevice(in kerio::web::KId userId, in string deviceId);

   /**
    * IM: Reset buddy list of selected users
    *
    * @param userIds - list of user identifiers
    */
   void resetBuddyList(in kerio::web::KIdList userIds);


   /**
   * Obtains user effective rights (inherited from groups)
   *
   * @param errors - list of users failed to get effective rights
   * @param result - list of effective rights
   * @param userIds - list of IDs of users
   */
   void getEffectiveUserRights(out kerio::web::ErrorList errors, out EffectiveUserRightsList result, in kerio::web::KIdList userIds);


   /**
    * Set users' details according given pattern.
    *
    * @param errors - create a new user
    * @param userIds - list of IDs of users to be changed
    * @param pattern - pattern to use for new values
    */
   void set(out kerio::web::ErrorList errors, in kerio::web::KIdList userIds, in User pattern);

   /**
    * Wipe user's mobile device.
    *
    * @param userId - global user identifier
    * @param deviceId - ID of user's mobile device to be wiped
    */
   void wipeMobileDevice(in kerio::web::KId userId, in string deviceId);

   /**
   * Get personal user contacts
   *
   */
   void getPersonalContact(out kerio::web::ErrorList errors, out kerio::jsonapi::contacts::PersonalContactList contacts, in kerio::web::KIdList userIds);

   /**
   * Set personal user contacts
   *
   */
   void setPersonalContact(out kerio::web::ErrorList errors, in kerio::web::KIdList userIds, in kerio::jsonapi::contacts::PersonalContact contact);
};

}; }; };//end of namespace