|
| 1 | +--- |
| 2 | +languages: |
| 3 | +- javascript |
| 4 | +products: |
| 5 | +- power-platform |
| 6 | +- power-apps |
| 7 | +page_type: sample |
| 8 | +description: "This project contains samples that demonstrates how to use client-side JavaScript to perform data operation with the Dataverse Web API" |
| 9 | +--- |
| 10 | +# Web API Data operations Samples (Client-side JavaScript) |
| 11 | + |
| 12 | +This project provides a common [Single Page Application (SPA)](https://developer.mozilla.org/docs/Glossary/SPA) runtime experience for multiple client-side JavaScript samples that use the Dataverse Web API. See the table of samples in the [Demonstrates](#demonstrates) section for details. |
| 13 | + |
| 14 | +This sample requires a `.env` file that contains configurations to run the sample. The steps to get the values for this configuration are described in [Quickstart: Web API with client-side JavaScript and Visual Studio Code](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/quick-start-js-spa). If you have trouble connecting with this sample, try connecting with the simpler quick start sample. |
| 15 | + |
| 16 | + |
| 17 | +## Prerequisites |
| 18 | + |
| 19 | +| Prerequisite | Description | |
| 20 | +|--------------|-------------| |
| 21 | +| **Privileges to create an Entra App registration** | You can't run this sample application without a Microsoft Entra app registration to enable it.<br /><br /> Complete the steps in [Quickstart: Web API with client-side JavaScript and Visual Studio Code](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/quick-start-js-spa) to get an `.env` file you can use to run this sample application.| |
| 22 | +| **Visual Studio Code** | If Visual Studio Code isn't installed on your computer, you must [download and install Visual Studio Code](https://code.visualstudio.com/download) to run this sample. | |
| 23 | +| **Node.js** | Node.js is a runtime environment that allows you to run JavaScript on the server side. This sample creates a SPA application that runs JavaScript on the client side in a browser rather than the Node.js runtime. But [Node Package Manager (npm)](https://www.npmjs.com/) is installed with Node.js, and you need npm to install Parcel and the MSAL.js library. See [Install Node.js](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/quick-start-js-spa#install-nodejs) for instructions.| |
| 24 | +| **Parcel** | Modern web applications typically have a lot of dependencies on open source libraries distributed using npm as well as scripts that need to be managed and optimized during the build process. These tools are usually called 'bundlers'. The most common one is [webpack](https://webpack.js.org/). This application uses [Parcel](https://parceljs.org/) because it offers a simplified experience.| |
| 25 | +| **Web Technologies** | Knowledge of HTML, JavaScript, and CSS are required to understand how this quickstart works. Understanding how to [make network requests with JavaScript](https://developer.mozilla.org/docs/Learn_web_development/Core/Scripting/Network_requests) is essential. | |
| 26 | + |
| 27 | + |
| 28 | +## How to run the sample |
| 29 | + |
| 30 | +1. Clone or download the [PowerApps-Samples](https://github.com/microsoft/PowerApps-Samples) repository. |
| 31 | +1. Open the `dataverse/webapi/JS/SPASample` folder using Visual Studio Code. |
| 32 | +1. At the root of the `SPASample` folder, create a `.env` configuration file based on the `.env.example` file provided. Follow the steps in [Register a SPA application](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/quick-start-js-spa#register-a-spa-application) to get values to replace the `CLIENT_ID` and `TENANT_ID` placeholder values. Set the `BASE_URL` to the URL for the Dataverse environment you want to connect to. See [Create the .env file](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/quick-start-js-spa#create-the-env-file) for more details. |
| 33 | +1. Open a terminal window in Visual Studio Code. |
| 34 | +1. Type `npm install` and press <kbd>Enter</kbd> to install the `devDependencies` and `dependencies` items from the `package.json` file. These include `[parcel](https://www.npmjs.com/package/parcel)`, `[dotenv](https://github.com/motdotla/dotenv#readme)`, the `[@azure/msal-browser](https://www.npmjs.com/package/@azure/msal-browser)` library and others. |
| 35 | +1. Type `npm start` and press <kbd>Enter</kbd> to start the local web server on port 1234. |
| 36 | + |
| 37 | + You should expect output to the terminal that looks like this: |
| 38 | + |
| 39 | + ``` |
| 40 | + Server running at http://localhost:1234 |
| 41 | + Built in 1.08s |
| 42 | + ``` |
| 43 | + |
| 44 | +1. Press <kbd>Ctrl</kbd> + click the [http://localhost:1234](http://localhost:1234) link to open your browser. |
| 45 | +1. In your browser, select the **Login** button. |
| 46 | + |
| 47 | + The **Sign in to your account** dialog opens. |
| 48 | + |
| 49 | +1. Select the account that has access to Dataverse. |
| 50 | + |
| 51 | + The first time you access using a new application (client) ID value, you see this **Permissions requested** dialog: |
| 52 | + |
| 53 | +  |
| 54 | + |
| 55 | +1. Select **Accept** on the **Permissions requested** dialog. |
| 56 | + |
| 57 | + You are now logged in and can select from the available samples to run them and view the output. |
| 58 | + |
| 59 | +  |
| 60 | + |
| 61 | +1. Click the button to run the sample you want and observe the output. Other samples can't run until a running sample completes. |
| 62 | + |
| 63 | + While the sample runs, open the browser developer tools and observe the network traffic. |
| 64 | + |
| 65 | + |
| 66 | +## Demonstrates |
| 67 | + |
| 68 | +This sample provides a shell where multiple samples can run in a common application. This table describes each of the samples currently available: |
| 69 | + |
| 70 | +|Sample|FileName|Description| |
| 71 | +|---|---|---| |
| 72 | +|**Template**|`TemplateSample.js`|This sample demonstrates the common interface that samples in this application exposes. New samples can be created by copying the `TemplateSample.js` file, renaming the file and implementing new logic in the sample. [Learn more about the sample interface](#sample-interface)| |
| 73 | +|**Basic Operations**|`BasicOperationsSample.js`|This sample implements the operations specified by the [Web API Basic Operations Sample](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/web-api-basic-operations-sample).| |
| 74 | +|**Query Data**|`QueryDataSample.js`|This sample implements the operations specified by the [Web API query data sample](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/web-api-query-data-sample).| |
| 75 | +|**Conditional Operations**|`ConditionalOperationsSample.js`|This sample implements the operations specified by the [Web API Conditional Operations Sample](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/web-api-conditional-operations-sample).| |
| 76 | +|**Functions and Actions**|`FunctionsAndActions.js`|This sample implements the operations specified by the [Web API Functions and Actions Sample](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/web-api-functions-actions-sample).| |
| 77 | +|**Batch Operations**|`BatchSample.js`|This sample demonstrates the `DataverseWebAPI.Client.Batch` method by creating several account records in and outside changeset included batch operation as described by [Execute batch operations using the Web API](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/execute-batch-operations-using-web-api) | |
| 78 | + |
| 79 | + |
| 80 | +## Sample interface |
| 81 | + |
| 82 | +Each sample is defined as a [JavaScript Class](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Classes) which has a constructor that requires a `DataverseWebAPI.Client` instance and a reference to a `container` element in the UI where it will write output. |
| 83 | + |
| 84 | +Samples may import from other libraries. All of them import the `Util.js` library because it includes methods to write to the UI. The **Functions and Actions** sample also includes the `src\solutions\IsSystemAdminFunction_1_0_0_0_managed.js` library because it contains the base64 encoded contents of a solution that the sample needs to import. |
| 85 | + |
| 86 | +Each sample has the following public methods: |
| 87 | + |
| 88 | +|Method|Description| |
| 89 | +|---|---| |
| 90 | +|`SetUp`|Responsible for creating any data necessary for the code that will be included in the `Run` method. Adds any new records created to the `#entityStore` array to be referenced in the `Run` method and deleted in the `CleanUp` method.| |
| 91 | +|`Run`|Contains the code demonstrating the data operations included in the sample.<br />Adds any new records created to the `#entityStore` array to be deleted in the `CleanUp` method.<br />Each operation is defined by a private asynchronous method so that this method can manage the operations within a try/catch block. If any errors occur, the `CleanUp` method is called to delete any record created before the error.| |
| 92 | +|`CleanUp`|Responsible for deleting any records referenced by the `#entityStore` array items.| |
| 93 | + |
| 94 | +## Clean up |
| 95 | + |
| 96 | +Each sample will make every effort to delete any records created by the sample. If an error occurs during the `Run` method, the `CleanuUp` method is used to delete any records up to that point. |
| 97 | + |
| 98 | +You should delete the Entra application registration if you aren't planning to use it anymore. |
0 commit comments