Use Cases

From Freeside
Jump to: navigation, search

Freeside Use Cases


This document contains detailed descriptions of how Freeside is intended to be used, as an aid to designing parts of the application.

Some of the actions and options described in this document may not yet be implemented in Freeside's stable or development branches. (This is particularly true of some CRM tasks, domain registration, web hosting, and dedicated/virtual server hosting.)

When modifying this document, please:

  • Correct things that are just plain wrong.
  • If the document describes a process as other than the way you do it, and the other way is valid, please document both alternatives.
  • Use numbered lists to reflect the order of actions; also use numbered lists for enumerated alternatives as you can then refer to an alternative by number when discussing this document on the e-mail lists or IRC.

Use Cases


  • The otaker, or order taker, i.e. the Freeside operator.
  • The customer, or person acting as the customer's agent.


  • CRM: customer relationship management, i.e. e-mails, faxes, or letters to the customer.

New customer

New customer orders service in person or by phone, etc.

  1. Customer calls and says they want web hosting.
  2. Otaker confirms they are not an existing customer.
  3. Otaker enters new customer screen, takes customer details. (Error condition: may be existing customer.)
  4. Otaker proceeds to order first package.

Ordering web hosting

  1. Otaker asks customer which domain name they want to use, enters into Freeside, confirms spelling.
  2. Freeside determines if that domain is registered.
    1. if already registered, Otaker asks if customer owns that domain
      1. if so, Otaker asks if customer wants to transfer it to our registrar.
        1. if so, Freeside initiates a transfer request?
        2. if not, Freeside marks domain as registered externally.
      2. if not, Otaker asks customer for another domain name.
    2. if unregistered, Otaker asks if customer wants to register it and confirms spelling of domain name. Also confirms annual costs. (Option: auto-renewal.)
      1. if so, Freeside initiates registration.
      2. if not, order cannot proceed as we cannot host an unregistered domain?
  3. If customer registered or transfered a domain, Otaker tells customer credentials for their domain management account. For some registrars, customer credentials are required before registration or transfer can be initiated.
  4. Freeside generates domain registration e-mail to customer.
  5. Freeside sets up DNS if required by hosting account type, i.e. DNS is not managed by hosting account server.
    1. Hosting account specifies DNS template to use.
    2. DNS template specifies if IP address is to be allocated at this point.
    3. IP allocation may be manual or automated.
    4. Freeside displays completed template to Otaker.
    5. IP pool may be empty, aborting process.
    6. Customer may order special settings if not allowed to set manually.
    7. Freeside may create primary DNS hosting, secondary, or both.
  6. If hosting requires an owning account, Otaker asks customer for user name and password for owning account.
    1. If user declines to specify password, Otaker uses password generator.
    2. If user name taken, Otaker asks for different user name.
    3. If password weak, Otaker asks for different password.
  7. Freeside creates owning account, if any.
  8. Otaker asks customer which hosting plan they want; this controls quotas and capabilities. Otaker confirms monthly cost with customer.
  9. If hosting requires credentials, Otaker asks customer for user name and password for control panel account. (User name may be fixed!)
  10. Freeside creates hosting account using export. (Abend: no more accounts can be created due to limit on server and no more servers can be allocated from a pool.)
  11. If hosting account requires a site administrator, Otaker asks customer for user name and password for site administrator.
  12. Freeside creates site administrator account, if any.
  13. If optioned for charge-on-order, Freeside attempts to charge customer at this point.
  14. Process complete. Otaker thanks customer for order and states when site will be available.


  1. Factor out credential collection. Credentials may consist of user names & passwords, just passwords, e-mail addresses and passwords, etc.
  2. Factor out domain registration. Customers may order additional domains for:
    1. Domain speculation. Domain is parked.
    2. Domain aliases for existing web sites.
  3. Factor out DNS settings. ISP may sell primary or secondary DNS service.
  4. Self-service hosting order: same process with CGI script validation taking the role of the Otaker. Rate limit domain availability checks. Option: provide name variation checking, i.e. check other TLDs and variations of SLDs.
  5. Online hosting order: same process as for self-service, except that it's a new customer. Variation: check domain availability before forcing customer to create an account.
  6. Customer orders dedicated server instead of hosting package. IP set allocated for server. Reverse DNS set up. Server initialization process started (OS installation, etc.). Customer told expected delivery time. Customer asked for root password unless automatically allocated. Abend: out of IP addresses, out of servers in pool; these may just extend delivery time.
  7. Customer orders hosting reseller account instead of hosting package. Similar to ordering hosting account except that you just need credentials for logging into reseller interface. Plan selection may be required if more than one reseller plan is offered. Reseller package may include own IP block or use shared IPs.
  8. Customer orders virtual private server instead of dedicated server: Freeside creates the virtual server instead of allocating it from a pool; Xen might be create-on-demand using files, or allocate-from-pool if using partitions if these cannot be created on the fly.
  9. Customer orders managed server instead of dedicated server. Doesn't get a root password?
  10. Customer orders e-mail hosting: requires a domain name (optional if ISP sells e-mail hosting under its own domains, i.e., DNS, control panel login.
  11. Customer orders shared hosting (rare). No domain registration is required. Subdomain must be free for customer's use. Policies for subdomain availability are likely to be similar to those for user name availability. Subdomain name suggestion may be useful if the desired subdomain is already taken.

Domain Registration with a registrar that requires a client user name and password

Some registries/registrars require the creation of a client account for managing a domain portfolio. The ISP will have credentials, but must assign credentials to each customer:

  • A customer can use the same credentials for all domains at the same registrar.
  • A customer could have different credentials, and a different client account, for each domain in his/her portfolio.
  • A customer could be registering domains for friends and family, and wish to have several client accounts for portions of his/her domain portfolio.
  • Where an ISP registers domains through multiple registries/registrars, customers may find it easier to use the same credentials for all registrars.
  1. Prior to initiating domain registration or transfer, Freeside will search the customer account for existing registrar/registry client accounts and display a list.
  2. Otaker will always be able to create a new registry/registrar client account (if the registry/registrar requires it) by providing a new credential set.

Customer changes DNS, user name, password, etc. through hosting control panel.

  1. Freeside agent running on hosting server updates Freeside billing server with change. For Apache, this can be importing the /etc/shadow, /var/named/chroot/var/named/(slaves)/domain.tld, etc.

Daily domain registration tasks

  1. check for failed transfers
  2. check for domains transferred out
  3. check for auto-renewals performed.
Transfer request fails
  1. CRM: tell customer transfer has failed and what to do. Provide URL to re-initiate the transfer.
Domain transferred out
  1. Mark domain as registered externally in Freeside.
  2. Report transfer out in daily activity.
  3. Perform check for "no longer hosted with us."
Check for auto-renewals

(Not sure how you do this; may not be possible with a given registrar.)

  1. Invoice customer for renewal.

Customer moves hosting without telling us ("no longer hosted with us")

Net::DNS reports that DNS no longer points at our servers.

  1. Cancel customer account with corresponding reason?
  2. CRM: send termination letter.

Manual domain renewal

(Customer renews through SelfService or by phone or by URL.)

  1. Freeside renews domain for specified period.
    1. Unable to do at that time due to API connection failure. Queue it up for later?
    2. Customer credit card charge fails (authorize, renew, capture?)
  2. CRM: renewal confirmation letter.

Customer cancels hosting account

  1. Otaker asks if cancellation is immediate or to be scheduled on given date. Answer can include "when the domain expires." Note that the domain expiration date and the day it stops working are different.
  2. On cancellation date, Freeside...
    1. Backs up the hosting site, logs, and all databases.
    2. Deletes the site, logs, and associated databases.
    3. Cancels any DNS service for the site.
    4. Switches any associated domain registrations to lapse. Or, deletes the registrations.
    5. Parks the registered domains.
    6. CRM: tells the customer that cancellation has been performed.
    7. Deletes any associated e-mail accounts.


  1. Customer cancels dedicated server. On cancellation date, Freeside...
    1. Backs up server?
    2. Reformats server? Or just powers it down?
    3. Returns IP addresses to the pool.
    4. Removes DNS settings.
    5. Returns server to the pool.
  2. Customer cancels virtual server. Same as dedicated, except Freeside may delete the server immediately.