MigrationWiz 4.0 Module Usage Guide
Table of Contents Introduction... 3 Requirements... 3 APS Environment... 3 BitTitan... 3 Module Setup... 3 Deploying the RESTful Service... 3 Deploying in the APS Sandbox... 3 Deploying Using Linux Shared Hosting Module... 4 Importing the Package... 5 Creating the Service Instance... 5 Creating the POA Resource Types... 5 Creating the Service Template... 6 Setting up the Service Plan... 6 Bundling with the Mailbox License... 6 Selling as a Standalone Subscription... 7 Configuring Resellers... 8 MigrationWiz APS Package Contents... 8 MigrationWiz APS Package Branding... 9 Upgrading the Module... 9
Introduction MigrationWiz 4.0 Module for Parallels Automation helps the Parallels Automation customers to migrate their mail from a variety of mail platforms to the mail system hosted in Parallels Automation. This document provides a detailed description of the module setup process. Requirements APS Environment Our package requires the APS PHP Runtime to be installed. BitTitan Your private label portal must be set up to accept coupon codes from the end user. If your private label portal is set up to debit licenses from your account, APS will not be able to control licensing. Module Setup Deploying the RESTful Service The RESTful web service serves as a conversion point that translates the Parallels Automation requests conformant to the APS standard into the calls of the BitTitan s MigrationWiz API. The service is stateless, meaning that it does not store any information between the requests. All the incoming requests are handled on the fly, sent to the MigrationWiz API, and the responses are delivered to the Parallels Automation. This simplifies achieving the high availability and scaling up with redundant configuration - where multiple servers are handling the incoming requests. Redundancy configuration is beyond the scope of this guide. The preferred way of installation depends on your environment. Two most common options are described in the sub- sections below. Deploying in the APS Sandbox Access method: SSH Privileges required: root The APS sandbox environment provides an endpoint server (endpoint.sandboxname.vendorname.apsdemo.org, see http://doc.apsstandard.org/portal/sandbox/ for detail) that is equipped with the fast- start script for the application deployment simplification; see the Application Deployment documentation for more detail.
Operations: 1. Copy the package to the endpoint host. E.g. use the PSCP utility via Windows command line: pscp.exe - pw <password> "MigrationWiz- 4.0-94.app.zip" root@endpoint.<sandboxname>.<vendorname>.apsdemo.org:/ 2. Connect to the endpoint host with the SSH terminal (e.g. Putty) and deploy the endpoint with the endpoint.sh script: endpoint.sh migrationwiz /MigrationWiz- 4.0-94.app.zip Deploying Using Linux Shared Hosting Module Access method: Parallels Automation Provider Control Panel Privileges required: - - Website Administration: Configuration Own Domains: Admin Note: the web server where the application is deployed should have the aps- php- runtime component installed. See the PHP Runtime Library documentation for more detail. Operations: 3. Login to POA and navigate to the Hosting CP 4. Register a desired domain or subdomain (see Working with Domains section in the POA subscriber guide) 5. Add the new website on a new webspace (see Creating Apache Website on New Webspace section in the POA subscriber guide). Note: enable the SSH access to manage the webspace files. 6. Upload the package to the created webspace. E.g. use the PSCP utility via Windows command line: pscp.exe - pw <password> MigrationWiz- 4.0-94.app.zip <username>@<domainnname.tld>:/ Replace <username> and <password> with the SSH access credentials specified on the previous step; <domainname.tld> with the domain registered on step 2 above. 7. Unpack the contents of the scripts subfolder to the migrationwiz subfolder of the webspace location (typically /webspace/httpdocs/domainname.tld/migrationwiz/, where domainname.tld corresponds to the domain name selected on the step 2): unzip /migrationwiz- 4.0-94.app.zip scripts /webspace/httpdocs/<domainname.tld>/migrationwiz 8. Rename the _.htaccess file to.htaccess: mv /webspace/httpdocs/<domainname.tld>/migrationwiz/_.htaccess /webspace/httpdocs/<domainname.tld>/migrationwiz/.htaccess
Importing the Package Access method: Parallels Automation Provider Control Panel Privileges required: - Operations: APS Packages: Manage 9. Navigate to the POA menu Services / Applications 10. Click Import Package 11. Select the location of the package file and click Submit 12. Wait until the package import is complete Creating the Service Instance 13. Drill down into the Migration Wiz package 14. Switch to the Instances tab 15. Click the Install button 16. Specify the Application API end- point URI it will be http://domainname.tld/migrationwiz, where domainname.tld corresponds to the domain name selected for the RESTful web service and click Next >> 17. Specify the connection parameters provided by BitTitan: a. URL to the MigrationWiz API b. URL to the usage count API c. parameters string d. Identification token e. MigrationWiz Tab Caption This caption is set when new subscription is provisioned. If edited, only new subscriptions will get captions. You must put something here or the MigrationWiz tab will be blank. 18. Specify the UI behavior detail: a. The MigrationWiz tab caption for Customer Control Panel b. Clear Debug mode checkbox for production installations it reveals all the detail sent over the wire to MigrationWiz backend into the customer CP and the responses received; helps when troubleshooting the connectivity between the MigrationWiz module and the MigrationWiz backend. c. Check the Disable O365 Integration if there is no Office 365 APS2 Module installed in the Parallels Automation and click Next >> 19. Review the configuration and click Finish Creating the POA Resource Types 20. Create the Global Settings reference RT: a. Switch to the Resource Types tab b. Click Create and select Application Service Reference resource class c. Specify the desired resource name, e.g. MigrationWiz Global Settings, and click Next >>
d. Select the Globals type e. Select the instance created in the previous section f. Review the configuration and click Finish 21. Create the Customer Context RT: a. Click Create and select Application Service resource class b. Specify the desired resource name, e.g. MigrationWiz Customer Subscription, and click Next >> c. Select the Tenant type d. Check the Automatically provision service checkbox and click Next >> e. Review the configuration and click Finish 22. Create the Migrated Mailbox RT: a. Click Create and select Application Counter (unit) resource class b. Specify the desired resource name, e.g. MigrationWiz Migrated Mailbox, and click Next >> c. Select the migratedmailboxes resource d. Review the configuration and click Finish Creating the Service Template 23. Create a new service template as described in the POA Provider s Guide section Creating Service Template. Note: make sure to check the Autoprovisioning checkbox. 24. Select Custom type of the Service Template 25. Select the Resource Types created on the steps 20-22 above and click Next 26. Set the Limits and Home Visibility for the Resource types as follows: a. Global Settings: 1, Hidden b. Customer Context: 1, Hidden c. Migrated Mailbox: 0, Shown 27. Make sure the Service Template is Activated Setting up the Service Plan Parallels Automation does offer a great flexibility in configuring the Service Plans according to the Service Provider needs. The complete description of all the possible options is beyond the scope of this guide; please refer to the PBA documentation for the advanced configuration options. This guide focuses on the two most common scenarios: bundling the MigrationWiz service with the related mailbox resource, and selling it as a separate service. Bundling with the Mailbox License If the service provider does want to offer a bundle that unifies the hosted mailbox with the content migration service, they need to rely on the Composite Resource functionality in PBA. Perform the following steps to configure the bundles:
28. Add a new composite resource (e.g. Mailbox with Content Migration ) see the section Adding Composite Resource in the PBA Provider s Guide. 29. Do not forget to assign an appropriate Resource Category to the new composite resource, e.g. Additional Resources 30. Add the Migrated Mailbox resource type created on step 22 above to the newly created composite resource - see the section Including Resource in Composite Resource in the PBA Provider s Guide. 31. Add the mailbox resource type to the composite resource: a. For the Office 365, include the License Resource Type that corresponds to one of the offers that includes an Exchange Online mailbox (refer to the Microsoft documentation for the offer details) b. For the Hosted Exchange, include the PBA Resource that corresponds to the Mailboxes subresource of the Hosted Exchange Resource Type (e.g. Hosted Exchange/Mailboxes ) 32. Repeat the steps 28-31 for all the mailbox resources that should be bundled with the MigrationWiz content migration services. 33. Add the Resource Rates for the composite resources created on the steps 28-32 above instead of (or together with) the original mailbox resources. The partner costs for the migration services could be reflected into the setup fee of the composite resource, spread over the recurring fees (with appropriate cancellation fees) Selling as a Standalone Subscription If the service provider offers too many types of the mailbox licenses, creating a separate bundle for each of those may become impractical. Selling MigrationWiz in a standalone subscription decouples the content migration services from the mail hosting, and provides greater flexibility for the customer. Perform the following steps to configure a separate Service Plan: 28. Switch to Billing panel, locate the resource created on step 22 above in Resources section, and add it to some resource category (e.g. Additional Resources ). 29. Go to the Service Plans section in PBA; switch to the Service Templates tab, locate the Service Template created on step 23 above, and drill down into the Service Template detail screen. Go to the Plans tab, and click Add new service plan button. The recommended values for the billing settings are: a. Billing Period Type is Fixed Number of Years, and Billing Period is 1 b. Charge for Subscription is Before Billing Period c. Auto- Renewal is Before Expiration d. Renew Point (days) is 1 30. Add the 1 Year subscription period, set the Setup fee to the retail price of a single mailbox migration license, all other fees leave zero 31. Add the Resource Rate for the resource created on step 22 above, using the following settings: a. Max units: - 1 b. Included units: 1 c. Min units: 0 d. Setup fee: retail price of the single mailbox migration e. Charge per unit: yes
f. Recurring fee: 0.00 g. Overuse fee: 0.00 h. Measurable: false i. Show in Store: yes j. Show in CP: yes Configuring Resellers If there is a need to allow a reseller to sell plans containing the MigrationWiz services, reseller themselves have to be granted with enough resources. This requires extra configuration steps described in this section. Note: this issue is planned to be fixed in POA 6.0. Make sure you obtain an updated copy of this document if you are running POA 6.0 or newer. 32. Create a copy of the Service Template you created on steps 23-27 above (see the Cloning Service Template section of the Provider s Guide) 33. Edit the service template copy: a. Rename it to an easy- to- distinguish name, e.g. MigrationWiz Resources for Resellers b. Disable the autoprovisioning c. Set the limit for the MigrationWiz Mailbox resource to Unlimited 34. Create a Service Plan based on this Service Template in PBA 35. Subscribe each Reseller you want to enable for reselling the MigrationWiz services to this service plan (see Subscribing Customer to Service Plan section in the Provider s Guide) MigrationWiz APS Package Contents The APS package sources consist of the following files: # File Description 1./APP- META.xml Application metadata. All brandable strings are located in this file 2./ui/globals.html The markup for the MigrationWiz Service Connection view (Provider CP) in the read mode 3./ui/globals.edit.html The markup for the MigrationWiz Service Connection view (Provider CP) in the edit mode 4./ui/wizard.html The markup for the Customer view that loads an IFRAME with the MigrationWiz UI 5./scripts/_.htaccess The.htaccess file contents with the Apache rewrite rule directives 6./scripts/backends.php The PHP script that handles the global settings for the MigrationWiz Service Connection 7./scripts/contexts.php The PHP script that handles the interaction with Migraion Wiz Service API and Usage API 8./schemas/* The schemas generated from the scripts in the /scripts folder by
the APS build process 9./images/edit_16x16.gif The icon for the Edit button in the the MigrationWiz Service Connection view 10./images/internet- mail.png The application icon for the Home screen in the Customer CP 11./images/screenshot.png Screenshot image required for the APS certification (not shown in the PA) MigrationWiz APS Package Branding The Customer CP contains few UI items that cannot be modified by provider altering only PA settings. Both these items are encoded within the APP- META.xml: # Item APP- META.xml Tag Path 1 Application Name /application/presentation/summary 2 Application Description /application/presentation/description In order to modify those, edit the APP- META.xml and rebuild the package using the APS Command- Line tools. Upgrading the Module Upgrading the module to the new version consists of the following steps: 1. Import the package see Importing the Package section above 2. Upgrade the RESTful Service replace the webspace folder chosen for the service files deployment (see Deploying the RESTful Service section above) with the contents of the /scripts folder from the package.app.zip file Important: make sure you delete the typecache subfolder of the webspace folder with all its contents, otherwise the application will not work correctly 3. Upgrade the instance: Once the new package version appears in the Versions tab of the Application Detail View, go to the General tab, and click Upgrade instances. Select Upgrade all instances and click Next>>, then Finish. 4. Update the Service Instance settings navigate to the instance created per Creating the Service Instance, click Edit, update the setting values accordingly, and click Save Important: skipping this step might result in an undesired behavior, as the new setting values must be properly initialized.