Share via

Web API Data operations Samples (Client-side JavaScript)

Browse code

This project provides a common Single Page Application (SPA) runtime experience for multiple client-side JavaScript samples that use the Dataverse Web API. See the table of samples in the Demonstrates section for details.

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. If you have trouble connecting with this sample, try connecting with the simpler quick start sample.

Prerequisites

Prerequisite Description
Privileges to create an Entra App registration You can't run this sample application without a Microsoft Entra app registration to enable it.

Complete the steps in Quickstart: Web API with client-side JavaScript and Visual Studio Code to get an .env file you can use to run this sample application.
Visual Studio Code If Visual Studio Code isn't installed on your computer, you must download and install Visual Studio Code to run this sample.
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) is installed with Node.js, and you need npm to install Parcel and the MSAL.js library. See Install Node.js for instructions.
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. This application uses Parcel because it offers a simplified experience.
Web Technologies Knowledge of HTML, JavaScript, and CSS are required to understand how this quickstart works. Understanding how to make network requests with JavaScript is essential.

How to run the sample

  1. Clone or download the PowerApps-Samples repository.
  2. Open the dataverse/webapi/JS/SPASample folder using Visual Studio Code.
  3. 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 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 for more details.
  4. Open a terminal window in Visual Studio Code.
  5. Type npm install and press Enter 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.
  6. Type npm start and press Enter to start the local web server on port 1234.

You should expect output to the terminal that looks like this:

Server running at http://localhost:1234
Built in 1.08s

  1. Press Ctrl + click the http://localhost:1234 link to open your browser.

  2. In your browser, select the Login button.

    The Sign in to your account dialog opens.

  3. Select the account that has access to Dataverse.

    The first time you access using a new application (client) ID value, you see this Permissions requested dialog:

    Permissions requested dialog

  4. Select Accept on the Permissions requested dialog.

    You are now logged in and can select from the available samples to run them and view the output.

    Dataverse Web API JavaScript SPA sample application

  5. Click the button to run the sample you want and observe the output. Other samples can't run until a running sample completes.

    While the sample runs, open the browser developer tools and observe the network traffic.

Demonstrates

This sample provides a shell where multiple samples can run in a common application. This table describes each of the samples currently available:

Sample FileName Description
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
Basic Operations BasicOperationsSample.js This sample implements the operations specified by the Web API Basic Operations Sample.
Query Data QueryDataSample.js This sample implements the operations specified by the Web API query data sample.
Conditional Operations ConditionalOperationsSample.js This sample implements the operations specified by the Web API Conditional Operations Sample.
Functions and Actions FunctionsAndActions.js This sample implements the operations specified by the Web API Functions and Actions Sample.
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

Sample interface

Each sample is defined as a JavaScript Class 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.

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.

Each sample has the following public methods:

Method Description
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.
Run Contains the code demonstrating the data operations included in the sample.
Adds any new records created to the #entityStore array to be deleted in the CleanUp method.
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.
CleanUp Responsible for deleting any records referenced by the #entityStore array items.

Clean up

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.

You should delete the Entra application registration if you aren't planning to use it anymore.