Freeside:4:Documentation:Developer/FS/part export/magicmail
Contents
NAME
FS::part_export::magicmail
SYNOPSIS
MagicMail integration for Freeside
REQUIRES
DESCRIPTION
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 Methods
_export_insert
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.
_export_delete
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.
_export_replace
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.
_export_suspend
Hook that is called when service is suspended. To avoid confusion, don't use for anything else.
_export_unsuspend
Hook that is called when service is unsuspended. To avoid confusion, don't use for anything else.
Freeside Methods
These methods are specific to freeside, used to translate freeside customers/services/exports into magicmail accounts/users/packages.
cust_account_id
Accepts either $cust_main or $svc_acct. Returns MagicMail account_id for this customer under this export.
cust_magic_services
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.
cust_magic_packages
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.)
sync_magic_packages
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.
Helper Methods
These methods combine account, user and package information through multiple API requests.
get_accounts_and_users
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.
get_master_user
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.
request
#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|XML::Simple#XMLin|"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.
Account Methods
Make individual account-related API requests.
add_account
Accepts $account_id and the following options:
first_name
last_name
phone
memo
Returns a hashref containing the created account details.
get_account
Accepts $account_id. Returns a hashref containing account details. Returns nothing without setting error if account is not found.
get_accounts
No input. Returns a hashref, keys are account_id, values are hashrefs of account details.
update_account
Accepts $account_id and the same options as "add_account". Updates an existing account. Returns a hashref containing the updated account details.
suspend_account
Accepts $account_id. Sets account status to suspended. Returns a hashref containing the updated account details.
activate_account
Accepts $account_id. Sets account status to active. Returns a hashref containing the updated account details.
delete_account
Accepts $account_id. Sets account status to deleted. Returns a hashref containing the updated account details.
purge_account
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.
User Methods
Make individual user-related API requests.
add_user
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.
get_user
Accepts $username. Returns a hashref containing user details. Returns nothing without setting error if user is not found.
get_users
Accepts $account_id. Returns a hashref, keys are username, values are hashrefs of user details.
update_user
Accepts $account_id, $username and the same options as "add_user". Updates an existing user. Returns a hashref containing the updated user details.
make_master_user
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.
suspend_user
Accepts $username. Sets user status to suspended. Returns a hashref containing the updated user details.
activate_user
Accepts $username. Sets user status to active. Returns a hashref containing the updated user details.
delete_user
Accepts $username. Sets user status to deleted. Returns a hashref containing the updated user details.
purge_user
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.
Package Methods
Make individual package-related API requests.
assign_package
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.
get_packages
Accepts $username. Returns a hashref of packages assigned to this user, keys are package names and values are hashrefs of details about those packages.
remove_package
Accepts $username and $package. Removes package from user. No meaningful return value.
Domain Methods
Make individual account-related API requests.
add_domain
Accepts $account_id and $domain. Creates domain for that account.
get_domain
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.
get_domains
Accepts $account_id. Returns hasref of domains for that account, keys are domains, values are hashrefs of info about each domain.
remove_domain
Accepts $domain. Removes domain. No meaningful return value.
Email Address Methods
Make individual emailaddress-related API requests.
add_email_address
Accepts $username and $address. Adds address for that user. Returns hashref of details for new address.
get_email_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.
get_email_addresses
Accepts $username. Returns hasref of email addresses for that account, keys are domains, values are hashrefs of info about each domain.
remove_email_address
Accepts $address. Removes address. No meaningful return value.
Error Methods
Used to track errors during a request, for precision control over when and how those errors are returned.
error
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.
check_for_error
Accepts $result returned by "request". Sets error if $result does not exist or contains an error message. Returns "error".
error_init
Resets error message in object to blank string. Should only be used at the start of "Hook Methods". No meaningful return value.
error_warn
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.
debug
Returns true if debug is set, either as an export option or in the module code.
rollback
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".
SEE ALSO
AUTHOR
Jonathan Prykop jonathan@freeside.biz
