Views:

Overview

The North52 BPA Data Packager functionality allows you to easily move data stored in records from one Dynamics 365 CE/Dataverse instance to another.  This is a common scenario when deploying changes for Dynamics Portals. 


In this article we describe how you build a Data Package which you can use to deploy a Web Form for a custom entity from a development instance to another instance. The business scenario is that you would like your customers to be able to register products they have purchased. The customer will need to be signed into the portal and can create a new Product Registration by selecting from a list of Products and entering the serial number of the product they have purchased. 

Data Package Setup

Prerequisite

This article assumes you have imported and executed the Data Package as per the steps in the Data Packager - How To - Import and Execute article. This will have created the necessary portal configuration records to be used for creating the new Data Package in this tutorial.

Create Solution

Before we create a Data Package, the best practice is to create a Dynamics 365 Solution which will hold the Data Package records. 

  • Go to https://make.powerapps.com/
  • Ensure you are in the correct environment
  • Click on Solutions in the sidebar
  • Click the New button
  • Enter Product Registration Data Package for the Display Name
  • Select a Publisher
  • Enter 1.0.0.0 in the Version field
  • Click Save and Close

Create the Data Package

  • Navigate to the North52 App and select Data Packager > Data Packages
  • Click the New button
    • Set the Name to Product Registrations - Data Package
    • Expand Deployment Settings
    • Select Product Registration Data Package as the Deployment Solution
  • Click Save

Add data to the Data Package

To ensure that records get created in the target system in the correct order we need to work out the what records we need to move and any dependencies they have on each other. The record types and order in which we need to add them to the Data Package is as follows:

  1. Entity Permissions
  2. Entity Permission Web Role associations
  3. Entity Form
  4. Entity Form Metadata
  5. Entity List
  6. Web Page
    • Note: When adding the Web Page record the Data Package recognises that there is a reference to the Web Page in the Entity List Data Package sheet and then automatically:
      • Removes the reference to the Web Page record in the Entity List sheet by placing a 'NoOp' (No Operation) value in place of the GUID
      • Adds a new sheet after the Web Page sheet to update the Entity List record with the reference to the Web Page (which by now has been created)
  7. Web Link

Setup

When creating Data Packages there are a number of fields that we don't need or necessarily want to bring into our Data Package, for example createdon, modifiedon, etc. There is a calculation called DP - Configuration - ExcludeFields which can be found on the Global Calculations sheet which has a comma separated list of these excluded fields. When working with Web Pages additional fields should be excluded called adx_authorid (lookup to Contact entity) unless the Contacts on both the source and target instances are identical, and adx_createdbyusername and adx_modifiedbyusername.

  • Select the Global Calculations sheet
  • Select the DP - Configuration - ExcludeFields Calculation Value cell (B2)
  • Click the + button in the top right of the sheet to expand the editor for cell B2
  • Add a comma followed by adx_authorid,adx_createdbyusername,adx_modifiedbyusername inside the closing single quote
  • Close the editor
  • Click Save

Entity Permissions and Entity Permission Web Role associations

  • Select the Explore tab
  • Choose Entity Permission from the dropdown list
    • Type Product reg in the Search records... input box and press Enter
    • Select the checkbox beside the Records node to select both Entity Permission records
    • Click the lightning bolt button
    • A new Data Package sheet named Entity Permission is added:
      • Two rows representing the data of the two selected Entity Permission records are also added to the sheet
    • Expand the first record node by clicking on the triangle icon
      • Once the loading has completed, expand the Related (N:N) node
      • Then expand the adx_entitypermission_webrole node
      • Select the checkbox for the many to many relationship record denoted by the GUID
    • Expand the second record node by clicking on the triangle icon
      • Once the loading has completed, expand the Related (N:N) node
      • Then expand the adx_entitypermission_webrole node
      • Select the checkbox for the many to many relationship record denoted by the GUID
    • Click the lightning bolt button
    • A new Data Package sheet named adx_entitypermission_webrole is added
      • Two rows representing the data of the two selected Entity Permission Web Role relationship records are also added to the sheet
  • Click Save

Entity Form and Entity Form Metadata

  • On the Explore tab choose Entity Form from the dropdown list
    • Select the checkbox beside the (Community Portal) Product Registration node
    • Click the lightning bolt button
    • A new Data Package sheet named Entity Form is added
      • One row representing the data of the selected Entity Form record is also added to the sheet
    • Expand the (Community Portal) Product Registration record node by clicking on the triangle icon
      • Once the loading has completed, expand the Related (1:N) node
      • Then expand the adx_entityformmetadata : adx_entityform node
      • Select the checkbox for the one to many relationship record denoted by the GUID
      • Click the lightning bolt button
      • A new Data Package sheet named Entity Form Metadata is added
        • One row representing the data of the selected Entity List record is also added to the sheet
  • Click Save

Entity List

  • On the Explore tab choose Entity List from the dropdown list
    • Select the checkbox beside the (Community Portal) Product Registrations node
    • Click the lightning bolt button
    • A new Data Package sheet named Entity List is added
      • One row representing the data of the selected Entity List record is also added to the sheet
      • This Entity List record has an attribute Web Page for Create which is a lookup to a Web Page record which has not been created yet, so we will need to do an update to this record after the Web Pages are created. We will address this with further steps below.
  • Click Save

Web Page

  • On the Explore tab choose Web Page from the dropdown list
    • Type Product reg in the Search records... input box and press Enter
      • Having the Web Pages listed with the Root pages first (denoted by the word Root in brackets) is preferable as it means one less update needs to be done, however it is not necessary as the Data Packager will take care of the updates automatically. Placing the cursor in the search box and pressing Enter again will reverse the order of the records:
    • Select the checkbox beside the Records node to select all of the Web Pages
    • Click the lightning bolt button
      • A new Data Package sheet named Web Page is added
        • Four rows representing the data of the selected Web Page records are also added to the sheet
      • A new Data Package sheet named Web Page-SR-Update is added (SR stand for self-referencing)
        • Self-referencing look up attributes (Parent Page and Root Web Page) in the Web Page sheet are replaced with a 'NoOp' (No Operation) value in place of the GUID
        • This sheet update the Web Page records with the relevant reference to specific Web Pages which were created by the previous sheet 
      • A new Data Package sheet named Entity List-Web Page-BD-Update is added (BD stands for bidirectional) 
        • The reference to the Web Page record in the Entity List sheet is also removed by placing a 'NoOp' (No Operation) value in place of the GUID
        • This sheet updates the Entity List record with a reference to the Web Page which was created by the Web Page sheet
  • Click Save

Web Link

  • On the Explore tab choose Web Link from the dropdown list
    • Select the checkbox beside the Product Registrations node
    • Click the lightning bolt button
    • A new Data Package sheet named Web Link is added (this will be placed to the right of the previously selected sheet. If the Web Link sheet is not after the Web Page-SR-Update sheet, drag it so that it is)
      • One row representing the data of the selected Web Link record is also added to the sheet
  • Click Save

Disabling Plug-ins and Processes

Often when importing data you need to disable Plug-ins and Processes to avoid necessary or unwanted logic being applied as the records are created. For this example we are creating all necessary records with complete data so therefore do not want any Plug-ins or Processes to execute on the entities we are working with.

To add the capability to disable and then re-enable Plug-ins and Processes:

  • Select Snippets > DP Setup Processes
    • This will add two sheets Deactivate and Activate, and the supporting Global Calculations and Global Actions to the Data Package
    • The Deactivate sheet references two Global Actions: Deactivate Plug-ins and Deactivate Processes
    • The Activate sheet references two Global Actions: Activate Plug-ins and Activate Processes
  • Select the Global Calculation sheet
    • Replace the Calculation Value for Plugin - EntitiesToDisableEnableCsv with: 
      'adx_entityform,adx_entityformmetadata,adx_entitylist,adx_webpage,adx_entitypermission,adx_entitypermission_webrole,adx_weblink'
  • Click Save

Data Package xCache records

For Data Package optimization, some of the data in the Data Package is referenced to xCache records. These xCache records are created automatically as data is added to the package (see the rules defining which data goes to xCache in the section DP - Configuration - TextFieldsToXCache on this article)

  • Navigate to the North52 App and select Business Process Activities > xCache
  • Change the view to Active Data Package N52 xCache
  • Filter the category by the Data Package short code to view all records related to your Data Package
  • Open the xCache record to see the value - in the Value Information tab

Export Data Package

The Data Package is now ready to be exported for use in a target instance.

  • Go to https://make.powerapps.com/
  • Click on Solutions in the sidebar
  • Select or open the Product Registration Data Package solution containing your Data Package records
  • Click the Export button to export the solution (you can use either unmanaged or managed solutions to export Data Packages)
  • Once exported the Data Package is ready to be imported into another instance