Migration from Public Preview

Nima Kamoosi, Senior Program Manager, Microsoft, zondag 13 november 2016

Microsoft PowerApps and Common Data Service have been released as Generally Available (GA). Many of you have been using the Common Data Service and PowerApps in Public Preview, however, even though you will be able to access your existing apps, flows, and Common Data Service databases in Preview, these resources will not be automatically upgraded to the new release due to compatibility issues. Instead we are sharing instructions on how to work with these resources, as well as how to manually migrate them to a GA environment.

Access to Preview resources

With the GA release, we will be introducing the concept of environments. An organization can have many environments, each of which will contain exactly one database. Your Preview database, including its entity definitions, data, and any apps built against it will be moved into a separate legacy environment called “{Your name}’s environment”. The legacy environment will not provide any of the new GA functionality (like picklists or translation sets), however, apps, flows and entities will remain functional as before.

Migration guide

You can use the following topics to move data, entity definitions, apps, and flows from a legacy environment to a new environment. Each of the sections in this blog covers a step in the migration process. Please review all sections and perform the steps that apply to your migration process.

Preparing for migration

If you do not already have a new environment, you will have to manually create one from the PowerApps admin center. See Environments administration for more details. Assuming that your apps are actively being used in your organization, you will need to plan for a downtime window, starting from when you start moving your apps to a new environment, until they become ready to use. It is common to notify users of the downtime. You may have to modify the app slightly to disable access and display a message such as "Unavailable due to maintenance." This prevents app users from committing data to the legacy database, while it’s being moved to a new environment.

App migration

You can save apps on local storage as files, using the PowerApps Studio application, or using the PowerApps Web Studio. Later, each app can then be imported back into a new environment. Data sources may become invalid as a result of the move between environments. This means that you will have to delete and recreate data sources after migrating the app. For detailed information, see Environment and tenant app migration for more information.

Use the following detailed steps for each app that you want to move to the new environment:

Open PowerApps Studio.
1. If not already installed on your machine, obtain it from the Windows Store and log in.
Select the legacy environment.
1. Go to the File tab, and then go to the Account pane.
2. Ensure that the legacy environment name is selected under Environment. If not, click Change, select the legacy environment, and click OK.
Open the app from the legacy environment.
1. On the Open pane, find your source app, and click the Edit icon. The app will open in edit mode.
Save the app to file.
1. Go back to the File tab, and then navigate to the Save as pane.
2. Select This computer, and save the file locally.
Switch to new environment.
1. Go to the File tab, and then navigate to the Account pane.
2. Ensure that the new environment name is selected under Environment. If not, click Change, select the new environment, and click OK.
Open the app file.
1. In the Open pane, click the Browse button on the top right, select the file that you saved previously, and click OK.
Verify entities.
1. Ensure that the database entities and fields used by the app are also present in the current environment. Follow the instructions in the entity migration section below for more details.
Recreate data sources.
1. Go to PowerApps Studio, the Content tab, and click Data sources.
2. In the Data Sources pane, for each data source, repeat the following steps:

i. Delete the data source, and click Add data source.

ii. If the connection for this data source does not exist, recreate it by clicking New connection, selecting the connection, and clicking Connect.

iii. Recreate the data source by selecting the connection and configuring the data source. For example, when adding an entity data source, select Common Data Model and the corresponding entity.

Save your app to the new environment.
1. Go back to the File tab, and then navigate to the Save as pane.
2. Select The cloud, and click Save.

Flow migration

If you’re currently using flows then you will not be able to migrate to the GA features at this time, if you would like to preserve your flows. We will be working to add this feature in a future release and will update this blog when we do.

Entity migration

Custom entities and customizations to standard entities can be moved by exporting resources into a package from your source environment, after which you can import the package into a target environment. This will move all changes made to entities in the preview environment, with the exception of changes caused by schema differences between the two releases. You may have to recreate lookup fields, because the new experience requires creating relations. Refer to the "Standard entity" section to learn more about the differences between the two releases.

Export entities from a legacy environment
1. On admin.powerapps.com, select the legacy environment by name.
2. Select Export resources on the environment header.
3. When the export completes, use your browser to download the package file in .pkg format.
Import package into a new environment
1. On admin.powerapps.com, select the new environment by name.
2. Click or tap Import resources on the environment header.
3. On the import dialog, select Browse and select the package file in .pkg format.
4. Select Import.

Data import and export

Data can be migrated using the Common Data Service data import and export capability, for more information and detailed steps see Import or export data from the CDS.

Follow these general steps, for each entity used by your apps:

Export data from the legacy environment.
1. On powerapps.com, click or tap Entities in the left navigation pane.
2. Next to New entity, click or tap the ellipsis, and then click or tap Export data.
3. Select the corresponding entity, and then click or tap Export to Excel.
4. When Export Completed appears, click or tap Download exported data to download the data.
Make adjustments for modified standard entities.
1. If you are using standard entities, and if any of these standard entities or fields have been changed since Preview you may have to take a few steps to prepare the data for import, or to map the data during import. Please see the standard entity changes section below for more details.
Import data into new environment.
1. On powerapps.com, expand the Common Data Service section and click or tap Entities in the left navigation pane.
2. Next to New entity, click or tap the ellipsis, and then click or tap Import data.
3. Select the entity that you want to import data into, and then click or tap Next.
4. Select the data file saved from previous steps.
5. Click Import.

Finalizing the migration process

The new environments support setting up role based security. Refer to Configure database security for more information about the choice between an open or restricted database. If you choose to configure role based security, you can create permission sets, create roles, and assign users to them as a part of finalizing the migration process.

Standard entity changes

We have made changes to the standard entities, some of which may affect your migration plan. These changes may affect how you recreate custom entities in the new environment. These changes may also affect how you map fields during the data import process.

Entity name changes and deprecations

A few standard entities have been renamed, specifically the ones shown in the following table. You can use this mapping to import data from an old entity to the new entity. If the entity is deprecated, you will need to manually recreate it as a custom entity.

Preview entity	Replacement entity
Accounts	Account
Budget	(Deprecated)
Contacts	Contact
Contractor	Worker
Customer	Account
Donor	Account
Employee	Worker
Expense	(Deprecated)
Member	Person
OrderLines	SalesOrderLine
Orders	SalesOrder
Products	Product
Supplier	Vendor
Volunteer	Worker

Entity to picklist conversions

A few of the entities have been converted into picklists. For these entities, you need to make sure the items in the picklist reflect the data that you have in the corresponding entity from your preview environment. If these names match, the values will import correctly. See the following table for a complete list of entities:

Preview entity	Replacement picklist
Currency	Currency Code
UnitOfMeasure	Unit of Measure
Units	Unit of Measure

Lookup fields referencing any of the above entities, must be recreated as picklist fields and reference the appropriate picklist. Standard entities were already updated as described above, see the following list for details. Affected custom entities need to be manually updated.

Entity

Opportunity

Product

ProductVendor

PurchaseOrder

PurchaseOrderCharge

PurchaseOrderLine

PurchaseOrderLineCharge

PurchaseOrderLineTax

PurchaseOrderTax

SalesInvoice

SalesInvoiceCharge

SalesInvoiceLine

SalesInvoiceLineCharge

SalesInvoiceLineTax

SalesInvoiceTax

SalesOrder

SalesOrderCharge

SalesOrderLine

SalesOrderLineCharge

SalesOrderLineTax

SalesOrderTax

UnitConversion

VendorInvoice

VendorInvoiceCharge

VendorInvoiceLine

VendorInvoiceLineCharge

VendorInvoiceLineTax

VendorInvoiceTax