Merge pull request #1407 from MicrosoftDocs/aneesmsft-CanvasAppEmbedding-Actions

Aneesmsft canvas app embedding actions

Author: Mattp123

powerapps-docs/maker/TOC.yml

@@ -831,6 +831,8 @@
           href: ./model-driven-apps/pass-current-embedded-canvas-app.md
         - name: "Pass related records to an embedded canvas app"
           href:  ./model-driven-apps/pass-related-embedded-canvas-app.md
+        - name: "Perform predefined actions on the host form"
+          href:  ./model-driven-apps/embedded-canvas-app-actions.md
         - name: "Share an embedded canvas app"
           href:  ./model-driven-apps/share-embedded-canvas-app.md
         - name: "Embedded canvas app guidelines"

powerapps-docs/maker/model-driven-apps/embed-canvas-app-in-form.md

@@ -53,5 +53,6 @@ For guidelines on working with embedded canvas apps as well as helpful tips to t
 [Overview of canvas-app connectors for PowerApps](../canvas-apps/connections-list.md) <br />
 [Pass the current record as data context to an embedded canvas app](pass-current-embedded-canvas-app.md) <br />
 [Pass a list of related records as data context to an embedded canvas app](pass-related-embedded-canvas-app.md) <br />
+[Perform predefined actions on the host form from within an embedded canvas app](embedded-canvas-app-actions.md) <br />
 [Share an embedded canvas app](share-embedded-canvas-app.md) <br />
 [Guidelines on working with embedded canvas apps](embedded-canvas-app-guidelines.md)

powerapps-docs/maker/model-driven-apps/embedded-canvas-app-actions.md

@@ -0,0 +1,97 @@
+---
+title: "Perform actions on the host form from within an embedded canvas app | MicrosoftDocs"
+ms.custom: ""
+ms.date: 03/29/2019
+ms.reviewer: ""
+ms.service: powerapps
+ms.suite: ""
+ms.tgt_pltfrm: ""
+ms.topic: "get-started-article"
+applies_to: 
+  - "Dynamics 365 (online)"
+  - "Dynamics 365 Version 9.x"
+  - "PowerApps"
+ms.assetid: 00e62904-2ce9-4730-a113-02b1fedbf22e
+author: "Aneesmsft"
+ms.author: "matp"
+manager: "kvivek"
+tags: 
+  - "PowerApps maker portal impact"
+search.audienceType: 
+  - maker
+search.app: 
+  - "PowerApps"
+  - D365CE
+---
+# Perform predefined actions on the host form from within an embedded canvas app
+Embedded canvas apps provide the ability to perform predefined actions on the host form. These actions enable makers to navigate, refresh and save the host form. Using these actions, an embedded canvas app can act as a more integral part of the form and the model-driven app.  
+
+> [!NOTE]
+> This feature is currently in preview. <br />
+> [!INCLUDE [cc-preview-features-definition](../../includes/cc-preview-features-definition.md)] 
+
+The **ModelDrivenFormIntegration** object now includes the following new methods to enable makers to perform actions on the host form.  
+  
+### NavigateToMainForm(entityName, mainFormName, recordId)
+Navigates the host form to a main form and displays the specified record.  
+* **entityName** - A required string parameter that specifies the parent entity of the main form.  
+* **formName** - A required string parameter that specifies the name of the main form to navigate to.  
+* **recordId** - A required string parameter, that specifies the ID of the record to display in the main form.  
+ 
+Calling the NavigateToMainForm method can show the following error messages.
+  
+| Error message | Troubleshooting guidance |
+|:--------------|:-------------------------|
+|**Entity not found: *[EntityName]*** | Please check the value of the *entityName* parameter and ensure it is a valid entity name and that the user has access to it. |
+|**Form not found: *[FormName]*** | Please check the value of the *mainFormName* parameter and ensure it is a valid main form name and that the user has access to it. |
+|**There was a problem loading the record.** | Please check the value of the *recordId* parameter and ensure it is a valid record ID and that the user has access to it. |
+  
+  
+### NavigateToView(entityName, viewName)
+Navigates the host form to a view.  
+* **entityName** - A required string parameter that specifies the parent entity of the view.  
+* **viewName** - A required string parameter that specifies the name of the main form to navigate to.  
+ 
+Calling the NavigateToView method can show the following error messages.
+  
+| Error message | Troubleshooting guidance |
+|:--------------|:-------------------------|
+|**Entity not found: *[EntityName]*** | Please check the value of the *entityName* parameter and ensure it is a valid entity name and that the user has access to it. |
+|**View not found: *[ViewName]*** | Please check the value of the *viewName* parameter and ensure it is a valid view name and that the user has access to it. |
+  
+  
+### OpenQuickCreateForm(entityName)  
+Opens the default quick create form for an entity.  
+* **entityName** - A required string parameter that specifies the parent entity of the quick create form.  
+ 
+Calling the OpenQuickCreateForm method can show the following error messages.
+  
+| Error message | Troubleshooting guidance |
+|:--------------|:-------------------------|
+|**Entity not found: *[EntityName]*** | Please check the value of the *entityName* parameter and ensure it is a valid entity name and that the user has access to it. |
+  
+  
+### RefreshForm(showPrompt)  
+Refreshes the data on the host form.  
+* **showPrompt** - A required boolean parameter that indicates if a confirmation prompt should be displayed to the user before saving any unsaved data on the host form. Values should be "true" or "false".
+ 
+Calling the RefreshForm method can show the following error messages.
+  
+| Error message | Troubleshooting guidance |
+|:--------------|:-------------------------|
+|**Please use "true" or "false" as the parameter value.** | Please check the value of the *showPrompt* parameter and ensure that it is either "true" or "false". |
+  
+  
+### SaveForm()  
+Saves the data on the host form.  
+
+
+> [!NOTE]
+> If you do not see the IntelliSense for the methods to perform predefined actions in embedded canvas apps that were created prior to the functionality being made available; save, close and re-open the app. 
+
+## See also
+[Embed a canvas app on a model-driven form](embed-canvas-app-in-form.md) <br />
+[Pass the current record as data context to an embedded canvas app](pass-current-embedded-canvas-app.md) <br />
+[Pass a list of related records as data context to an embedded canvas app](pass-related-embedded-canvas-app.md) <br />
+[Share an embedded canvas app](share-embedded-canvas-app.md) <br />
+[Guidelines on working with embedded canvas apps](embedded-canvas-app-guidelines.md)

powerapps-docs/maker/model-driven-apps/embedded-canvas-app-guidelines.md

@@ -55,9 +55,10 @@ This topic provides guidelines on working with embedded canvas apps as well as h
      - To directly reference the record you can use the [First function](../canvas-apps/functions/function-first-last.md). Example: First(ModelDrivenFormIntegration.Data).Name
 -	Manually changing the App ID in the canvas app control properties is to be avoided as much as possible.
      - The App ID of the canvas app is automatically generated and filled in for you. 
-     - If for some reason you do need to manually edit it, you need to ensure that any App ID you use corresponds to an *embedded* canvas app and not just a standalone canvas app.
+     - If for some reason you do need to manually edit it, you need to ensure that any App ID you use corresponds to an *embedded* canvas app and not just a standalone canvas app. 
      - The embedded canvas app must also be created with the same data context that your model-driven form is going to send.
-     - After you have updated the App ID select **Customize** to establish the connection to the new app.
+     - After you have updated the App ID select **Customize** to open it in PowerApps Studio and establish the connection to the new app.
+     - Make a small change in the app to put it in an unsaved state, then save and publish the app.
 - When you view a model-driven form with an embedded canvas app, if you see an error message that reads "Sorry we didn't find that app" make sure that the embedded canvas app is in the same solution as the model-driven form.
 - When you view a model-driven form with an embedded canvas app, if you see an error message that reads "It looks like you don’t have access to this app. Ask its owner to share it with you" make sure that the author has shared the embedded canvas app with you. More information: [Share an embedded canvas app](share-embedded-canvas-app.md).
 
@@ -78,10 +79,12 @@ This topic provides guidelines on working with embedded canvas apps as well as h
 - When you create a new record, an embedded canvas app on a form is not displayed even after the record is saved. 
 -    The ModelDrivenFormIntegration.Data object currently does not work with the Display form and Edit form controls.
 - You can’t use the **Canvas App** privilege in a security role to grant app users access to either an embedded or standalone canvas app. For more information on sharing an embedded canvas app, please refer to: [Share an embedded canvas app](share-embedded-canvas-app.md).
-- If you write back the same data that is being displayed in the host model-driven form, the form will continue to display old data until it is refreshed. 
+- If you write back the same data that is being displayed in the host model-driven form, the form will continue to display old data until it is refreshed. An easy way to do that is to use the [RefreshForm](embedded-canvas-app-actions.md) method.
+- If you do not see the IntelliSense for the [methods to perform predefined actions](embedded-canvas-app-actions.md) in embedded canvas apps that were created prior to the functionality being made available; save, close and re-open the app. 
 
 ## See also
 [Embed a canvas app in a model-driven form](embed-canvas-app-in-form.md) <br />
 [Pass the current record as data context to an embedded canvas app](pass-current-embedded-canvas-app.md) <br />
 [Pass a list of related records as data context to an embedded canvas app](pass-related-embedded-canvas-app.md) <br />
+[Perform predefined actions on the host form from within an embedded canvas app](embedded-canvas-app-actions.md) <br />
 [Share an embedded canvas app](share-embedded-canvas-app.md)

powerapps-docs/maker/model-driven-apps/pass-current-embedded-canvas-app.md

@@ -81,5 +81,6 @@ This topic showed you how to get started with embedding a canvas app in a model-
 ## See also
 [Embed a canvas app on a model-driven form](embed-canvas-app-in-form.md) <br />
 [Pass a list of related records as data context to an embedded canvas app](pass-related-embedded-canvas-app.md) <br />
+[Perform predefined actions on the host form from within an embedded canvas app](embedded-canvas-app-actions.md) <br />
 [Share an embedded canvas app](share-embedded-canvas-app.md) <br />
 [Guidelines on working with embedded canvas apps](embedded-canvas-app-guidelines.md)

powerapps-docs/maker/model-driven-apps/pass-related-embedded-canvas-app.md

@@ -81,5 +81,6 @@ This topic showed you how to get started with the embedding a canvas app in a mo
 ## See also
 [Embed a canvas app on a model-driven form](embed-canvas-app-in-form.md) <br />
 [Pass the current record as data context to an embedded canvas app](pass-current-embedded-canvas-app.md) <br />
+[Perform predefined actions on the host form from within an embedded canvas app](embedded-canvas-app-actions.md) <br />
 [Share an embedded canvas app](share-embedded-canvas-app.md) <br />
 [Guidelines on working with embedded canvas apps](embedded-canvas-app-guidelines.md)

powerapps-docs/maker/model-driven-apps/share-embedded-canvas-app.md

@@ -42,4 +42,5 @@ Embedded canvas apps are also solution aware. By default embedded canvas apps ar
 [Embed a canvas app in a model-driven form](embed-canvas-app-in-form.md) <br />
 [Pass the current record as data context to an embedded canvas app](pass-current-embedded-canvas-app.md) <br />
 [Pass a list of related records as data context to an embedded canvas app](pass-related-embedded-canvas-app.md) <br />
+[Perform predefined actions on the host form from within an embedded canvas app](embedded-canvas-app-actions.md) <br />
 [Guidelines on working with embedded canvas apps](embedded-canvas-app-guidelines.md)