MailingLists.idl

Go to the documentation of this file.

/**
 * @file   MailingLists.idl
 * @brief  Work with mailing lists, the groups of email addresses and the ability to archive the electronic communication.
 *
 * @author Dusan Juhas
 *
 * @copyright Copyright © 2017 Kerio Technologies s.r.o.
 */

#import <kerio/web/idl/SharedStructures.idl>
#import <AdminStructures.idl> //DataSource
#import <DistributedDomain.idl> //HomeServer

module kerio {
module jsonapi {
module admin {

/**
 * Mailing List (=ML) Action Access Right Type
 */
enum MlPermission {
   Allowed, ///< certain action is allowed
   Moderated,  ///< certain action must be approved by moderator
   Denied      ///< certain action is denied
};

/**
 * Moderator Posting Access Right Type
 */
enum ModeratorPermission {
   PostAllowed,            ///< certain action is allowed
   PostModerated,          ///< certain action must be approved by moderator
   PostAccordingMembership    ///< certain action is ruled according modarator membership
};

/**
 * ML Addressee Type
 */
enum MlReplyTo {
   Sender,        ///< email address of the sender
   ThisList,      ///< email address of the ML
   OtherAddress,  ///< the address of the original sender will be substituted by a user defined email address
   SenderThisList ///< Sender + ThisList
};

/**
 * Type of Mailing List Membership
 */
enum MlMembership {
   Member,           ///< obtains contributions
   Moderator         ///< can manipulate with members but does not obtain contributions
};

/**
 * ML member
 */
struct UserOrEmail {
   boolean        hasId;      ///< is a real user or email address only?
   kerio::web::KId      userId;     ///< global user identification
   string         emailAddress;  ///< email address, filled only if hasId is false
   string         fullName;      ///< fullName of user or associated email
   MlMembership   kind;       ///< a kind of membership
};

/**
 * A ML member being imported from CSV file.
 */
struct MLMemberImportee {
   UserOrEmail member;     ///< ML member data
   boolean  isImportable;  ///< ML member can be imported
   string   message;    ///< error message if ML member is not importable
};

typedef sequence<MLMemberImportee> MLMemberImporteeList;

/**
 * List of ML members
 */
typedef sequence<UserOrEmail> UserOrEmailList;

/**
 * type indicator
 */
enum TrusteeKind {
   TrusteeUser,   // the type is the user
   TrusteeGroup   // the type is the group
};

/**
 * Entities that have access rights to read ML archive
 */
struct Trustee {
   TrusteeKind kind;       ///< is user or group?
   kerio::web::KId   readerId;   ///< group or user KId
   string displayString;      ///< login name or group name with domain name
   boolean     isEnabled;      ///< true if user account is enabled
   DataSource  itemSource;    ///< internal/LDAP
};

/**
 * List of entities that have access rights to read ML archive
 */
typedef sequence<Trustee> TrusteeList;

/**
 * Trustee target can be user or group
 */
struct TrusteeTarget {
   kerio::web::KId   id;            ///< unique identifier
   TrusteeKind    type;       ///< is user or group?
   string         name;       ///< loginName for the User, name in square brackets for the Group
   string         fullName;      ///< fullname for the User, empty string for the Group
   string         description;   ///< description of User/Group
   boolean        isEnabled;     ///< is the User/Group enabled?
   DataSource     itemSource;    ///< is the User/Group stored internally or by LDAP?
   HomeServer     homeServer;    ///< id of users homeserver if server is in Cluster; groups haven't homeserver
};

/**
 * List of trustee targets
 */
typedef sequence<TrusteeTarget> TrusteeTargetList;

/**
 * Rules for subscription
 */
struct SubscriptionPolicy {
   MlPermission   type;
   boolean        moderatorReview;
   boolean        moderatorNotification;
};

/**
 * Rules for posting
 */
struct PostingPolicy {
   MlPermission      memberPosting;          ///< posting policy for ML member(s)
   MlPermission      nonMemberPosting;       ///< posting policy for ML non-member(s)
   ModeratorPermission  moderatorPosting;       ///< posting policy for ML moderator(s)
   boolean           userPostingNotification;   ///< notify user that the posting will be reviewed by a moderator
   boolean           sendErrorsToModerator;     ///< send delivery errors to moderator(s)
};

/**
 * How is the archive organized?
 */
struct ArchiveSettings {
   boolean     keepArchive;            ///< maintain archive
   boolean     archiveOnlyForLogged;      ///< the archive is available for logged users only
   TrusteeList archiveReaderList;         ///< list of archive readers, can be either user or group, meaningful only if onlyForLogged is true
};

/**
 * Mailing List Structure
 */
struct Ml {
   kerio::web::KId         id;               ///< [READ-ONLY] global identification of ML
   kerio::web::KId         domainId;         ///< [REQUIRED FOR CREATE] [WRITE-ONCE] identification in which domain ML exists
   string               name;          ///< [REQUIRED FOR CREATE] [WRITE-ONCE] ML name, name@domain is email address
   string               description;      ///< description
   kerio::web::KId         languageId;       ///< language to be spoken withing mailing list
   string               welcomeString;    ///< string to be sent as welcome of a new memeber
   string               footerString;     ///< string to be sent as footer of each contribution
   SubscriptionPolicy      subscription;     ///< type of ML subscription policy
   PostingPolicy        posting;       ///< type of ML posting policy
   MlReplyTo            replyTo;       ///< how should be replied to
   string               otherAddress;     ///< if replyTo is OtherAddress, it contains email address
   string               subjectPrefix;    ///< prefix for each subject
   boolean              hideSenderAddress;   ///< replace sender's email address by ML address
   boolean              allowEmptySubject;   ///< allow posting with empty subject
   ArchiveSettings         archive;       ///< archive settings
   
   long              membersCount;     ///< [READ-ONLY] Number of members.
   HomeServer           homeServer;       ///< [READ-ONLY] Id of users homeserver if server is in Cluster
};

/**
 * List of mailing lists
 */
typedef sequence<Ml> MlList;

interface MailingLists {

   /**
    * Add one or more members/moderators to a mailing list.
    *
    * @param errors - appropriate error messages
    * @param members - ML members and/or moderators
    * @param mlId - unique ML identifier
    */
   void addMlUserList(out kerio::web::ErrorList errors, in UserOrEmailList members, in kerio::web::KId mlId);

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

   /**
    * Export of mailing list users of specified membership type.
    *
    * @param kind - membership type
    * @param mlId - unique ML identifier
    * @param fileDownload - description of output file
    */
   void exportMlUsersToCsv(out kerio::web::Download fileDownload, in MlMembership kind, in kerio::web::KId mlId);

   /**
    * Obtain a list of mailing lists.
    *
    * @param list - mailing lists
    * @param totalItems - amount of MLs for given search condition, useful when a limit is defined in search query
    * @param query - query conditions and limits
    * @param domainName - domain identification
    */
   void get(out MlList list, out long totalItems, in kerio::web::SearchQuery query, in kerio::web::KId domainId);

   /**
    * Obtain list of mailing list users including membership type.
    *
    * @param list - mailing list members and/or moderators
    * @param totalItems - amount of MLs members for given search condition, useful when a limit is defined in search query
    * @param query - orderBy definition (conditions and limit are ignored)
    * @param mlId - unique ML identifier
    */
   void getMlUserList(out UserOrEmailList list, out long totalItems, in kerio::web::SearchQuery query, in kerio::web::KId mlId);

   /**
    * Parse CSV file in format 'Email, FullName' and return list of members.
    *
    * @param members - ML members and/or moderators
    * @param fileId - ID of the uploaded file
    * @param mlToImport - unique ML identifier or empty string if XML does not exist yet
    */
   void getMlUserListFromCsv(out MLMemberImporteeList members, in string fileId, in kerio::web::KId mlToImport);

   /**
    * Obtain all suffixes of mailing list. These are forbidden in a name of mailing list to avoid of misbehaviour during
    * processing of special commands of mailing list.
    *
    * @param suffixes - list of suffixes
    */
   void getSuffixes(out kerio::web::StringList suffixes);

   /**
    * Obtain a list of potential mailing list archive rights targets.
    *
    * @param list - trustee targets
    * @param query - query attributes and limits
    * @param domain - domain restriction
    */
   void getTrusteeTargetList(out TrusteeTargetList list, out long totalItems, in kerio::web::SearchQuery query, in kerio::web::KId domainId);

   /**
    * Remove mailing lists.
    *
    * @param errors - error message list
    * @param mlIds - list of global identifiers of MLs to be deleted
    */
   void remove(out kerio::web::ErrorList errors, in kerio::web::KIdList mlIds);

   /**
    * Remove member(s)/moderator(s) from a mailing list.
    *
    * @param errors - appropriate error messages
    * @param members - ML members and/or moderators
    * @param mlId - unique ML identifier
    */
   void removeMlUserList(out kerio::web::ErrorList errors, in UserOrEmailList members, in kerio::web::KId mlId);

   /**
    * Create a new mailing list.
    *
    * @param errors - error message list
    * @param mlIds - ML global identifiers
    * @param pattern - pattern to use for new values
    */
   void set(out kerio::web::ErrorList errors, in kerio::web::KIdList mlIds, in Ml pattern);
};

}; }; };//end of namespace