FS::part_export::magicmail
MagicMail integration for Freeside
This export offers basic svc_acct provisioning for MagicMail. Each customer will map to an account in MagicMail, and each svc_acct exported will map to a user/mailbox.
This module also provides generic methods for working through the MagicMail API,
and can be used as a base for more complex exports to MagicMail (just be sure to override the %info hash and the "Hook Methods".)
"Hook Methods" return an error message on failure, and a blank string on success. All other methods return a positive value (usually a hashref) on success and return nothing on failure, instead setting the error message in the export object using "Error Methods". Use "error" to retrieve this message.
Hook that is called when service is initially provisioned. To avoid confusion, don't use for anything else.
For this export, creates a MagicMail account for this customer if it doesn't exist, activates account if it is suspended/deleted, creates a user/mailbox on that account for the provisioning service, assigns package (specified by export option) to master user on account if it hasn't been, and adds the email address for the provisioning service. On error, attempts to purge any newly created account/user and remove any newly set package via "rollback".
On success, also runs "sync_magic_packages" (does not cause fatal error on failure.)
Override this method when using this module as a base for other exports.
Hook that is called when service is unprovisioned. To avoid confusion, don't use for anything else.
For this export, deletes the email address and user associated with the provisioning service. Only sets an error if this part fails; everything else simply generates warnings.
Also attempts to delete the associated account, if there aren't any more users on the account.
If deleted user was master user for account and other users exist on the account, attempts to make another user the master user.
Runs "sync_magic_packages".
If the autopurge export option is set, also purges newly deleted users/accounts.
Override this method when using this module as a base for other exports.
Hook that is called when provisioned service is edited. To avoid confusion, don't use for anything else.
Updates user info & password. Cannot be used to change user name.
Override this method when using this module as a base for other exports.
Hook that is called when service is suspended. To avoid confusion, don't use for anything else.
Hook that is called when service is unsuspended. To avoid confusion, don't use for anything else.
These methods are specific to freeside, used to translate freeside customers/services/exports into magicmail accounts/users/packages.
Accepts either $cust_main or $svc_acct. Returns MagicMail account_id for this customer under this export.
Accepts $cust_main or $svc_acct and the following options:
ignore - $svc_acct to be ignored
include - $svc_acct to be included
Returns a list services owned by the customer that are provisioned in MagicMail with the same account_prefix (not necessarily the same export.)
include is not checked for compatability with the current export. It will probably cause errors if you pass a service that doesn't use the current export.
Accepts $cust_main or $svc_acct and the same options as "cust_magic_services".
Returns list of MagicMail packages for this customer's "cust_magic_services" (ie packages that the master user for this customer should have assigned to it.)
Accepts $cust_main or $svc_acct and the same options as "cust_magic_services".
Assigns or removes packages from the master user of "cust_account_id" so that they match "cust_magic_packages". (Will only attempt to remove non-matching packages if matching packages are all successfully assigned.)
All errors will be immediately cleared by "error_warn". No meaningful return value.
These methods combine account, user and package information through multiple API requests.
Returns results of "get_accounts" with extra 'users' key for each account, the value of which is the result of "get_users" for that account.
Accepts $account_id. Returns hashref of details on master user for that account (as would be returned by "get_user".) Returns nothing without setting error if master user is not found.
#send a request to https://machine/api/v2/some/function
my $result = $export->request('POST','/some/function',%args);
Accepts $method, $path and optional %args. Sends request to server and returns server response as a hashref (converted from XML by XML::Simple.) %args can include a ForceArray key that will be passed to "XMLin" in XML::Simple; all other args will be passed in the reqest. Do not include 'client_type' in %args, and do not include '/api/v2' in $path.
Used by other methods to send requests; unless you're editing this module, you should probably be using those other methods instead.
Make individual account-related API requests.
Accepts $account_id and the following options:
first_name
last_name
phone
memo
Returns a hashref containing the created account details.
Accepts $account_id. Returns a hashref containing account details. Returns nothing without setting error if account is not found.
No input. Returns a hashref, keys are account_id, values are hashrefs of account details.
Accepts $account_id and the same options as "add_account". Updates an existing account. Returns a hashref containing the updated account details.
Accepts $account_id. Sets account status to suspended. Returns a hashref containing the updated account details.
Accepts $account_id. Sets account status to active. Returns a hashref containing the updated account details.
Accepts $account_id. Sets account status to deleted. Returns a hashref containing the updated account details.
Accepts account $id and the following options:
force - if true, purges account even if it wasn't first deleted
Purges account from system. No meaningful return value.
Make individual user-related API requests.
Accepts $account_id, $username and the following options:
first_name
last_name
memo
password
password_type - plain or encrypted
Returns a hashref containing the created user details.
Accepts $username. Returns a hashref containing user details. Returns nothing without setting error if user is not found.
Accepts $account_id. Returns a hashref, keys are username, values are hashrefs of user details.
Accepts $account_id, $username and the same options as "add_user". Updates an existing user. Returns a hashref containing the updated user details.
Accepts $username. Sets user to be master user for account. Returns a hashref containing the updated user details.
Caution: does not unmake existing master user.
Accepts $username. Sets user status to suspended. Returns a hashref containing the updated user details.
Accepts $username. Sets user status to active. Returns a hashref containing the updated user details.
Accepts $username. Sets user status to deleted. Returns a hashref containing the updated user details.
Accepts $username and the following options:
force - if true, purges user even if it wasn't first deleted
Purges user from system. No meaningful return value.
Make individual package-related API requests.
Accepts $username and $package. Assigns package to user. Returns a hashref of packages assigned to this user, keys are package names and values are hashrefs of details about those packages. Returns undef if none are found.
Accepts $username. Returns a hashref of packages assigned to this user, keys are package names and values are hashrefs of details about those packages.
Accepts $username and $package. Removes package from user. No meaningful return value.
Make individual account-related API requests.
Accepts $account_id and $domain. Creates domain for that account.
Accepts $domain. Returns hasref of domain info if it exists, or empty if it doesn't exist or permission denied. Returns nothing without setting error if domain is not found.
Accepts $account_id. Returns hasref of domains for that account, keys are domains, values are hashrefs of info about each domain.
Accepts $domain. Removes domain. No meaningful return value.
Make individual emailaddress-related API requests.
Accepts $username and $address. Adds address for that user. Returns hashref of details for new address.
Accepts $address. Returns hasref of address info if it exists, or empty if it doesn't exist or permission denied. Returns nothing without setting error if address is not found.
Accepts $username. Returns hasref of email addresses for that account, keys are domains, values are hashrefs of info about each domain.
Accepts $address. Removes address. No meaningful return value.
Used to track errors during a request, for precision control over when and how those errors are returned.
Accepts optional $message, which will be appended to the internal error message on this object if defined (use "init_error" to clear the message.) Returns current contents of internal error message on this object.
Accepts $result returned by "request". Sets error if $result does not exist or contains an error message. Returns "error".
Resets error message in object to blank string. Should only be used at the start of "Hook Methods". No meaningful return value.
Accepts optional $message, which will be appended to the internal error message on this object if defined.
Outputs "error" (if there is one) using warn, then runs "error_init". Returns blank string.
Returns true if debug is set, either as an export option or in the module code.
Accepts hashref with the following fields, use for undoing recent changes:
remove_package - arrayref of username and package to remove
purge_user - username to be forcefully purged
suspend_account - account_id to be suspended
delete_account - account_id to be deleted
purge_account - account_id to be forcefully purged
Indicated actions will be performed in the order listed above. Sets generic error message if no message is found, and returns "error".
Jonathan Prykop jonathan@freeside.biz