Difference between revisions of "Freeside:3:Documentation:Developer/FS/part export/magicmail"

From Freeside
Jump to: navigation, search
(Edit via perl MediaWiki framework (1.13))
 
(No difference)

Latest revision as of 06:15, 4 May 2015

NAME

FS::part_export::magicmail

SYNOPSIS

MagicMail integration for Freeside

REQUIRES

Net::HTTPS::Any

XML::Simple

URI::Escape

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

FS::part_export

AUTHOR

Jonathan Prykop jonathan@freeside.biz