|
| 1 | +--- |
| 2 | +title: "Web API table schema operations sample (PowerShell) (Microsoft Dataverse)| Microsoft Docs" |
| 3 | +description: "This sample demonstrates how to perform operations that change the Dataverse data structures using the Web API with PowerShell." |
| 4 | +ms.date: 05/14/2024 |
| 5 | +author: mkannapiran |
| 6 | +ms.author: kamanick |
| 7 | +ms.reviewer: jdaly |
| 8 | +search.audienceType: |
| 9 | + - developer |
| 10 | +contributors: |
| 11 | + - JimDaly |
| 12 | +--- |
| 13 | + |
| 14 | +# Web API table schema operations sample (PowerShell) |
| 15 | + |
| 16 | +[!INCLUDE[cc-terminology](../../includes/cc-terminology.md)] |
| 17 | + |
| 18 | +This PowerShell sample demonstrates how to perform operations that create and modify table, column, and relationship definitions using the Dataverse Web API. |
| 19 | + |
| 20 | +This sample implements the Dataverse operations and console output detailed in [Web API table schema operations sample](../web-api-metadata-operations-sample.md) and uses the [Dataverse Web API PowerShell Helper functions](https://github.com/microsoft/PowerApps-Samples/blob/master/dataverse/webapi/PS/README.md) to manage authentication and provide reusable functions to perform common operations. These scripts are referenced using [dot sourcing](/powershell/module/microsoft.powershell.core/about/about_scripts#script-scope-and-dot-sourcing) with the following lines: |
| 21 | + |
| 22 | +```powershell |
| 23 | +. $PSScriptRoot\..\Core.ps1 |
| 24 | +. $PSScriptRoot\..\TableOperations.ps1 |
| 25 | +. $PSScriptRoot\..\CommonFunctions.ps1 |
| 26 | +. $PSScriptRoot\..\MetadataOperations.ps1 |
| 27 | +``` |
| 28 | + |
| 29 | +> [!NOTE] |
| 30 | +> This sample should work with Windows, Linux, and macOS, but has only been tested on Windows. |
| 31 | + |
| 32 | +## Prerequisites |
| 33 | + |
| 34 | +Before running this sample, you should read these articles that explain concepts and patterns used by these samples: |
| 35 | + |
| 36 | +- [Quick Start Web API with PowerShell and Visual Studio Code](../quick-start-ps.md) |
| 37 | +- [Use PowerShell and Visual Studio Code with the Dataverse Web API](../use-ps-and-vscode-web-api.md) |
| 38 | + |
| 39 | +These articles have the same prerequisites. |
| 40 | + |
| 41 | +[!INCLUDE [cc-visual-studio-code-powershell-prerequisites](../../includes/cc-visual-studio-code-powershell-prerequisites.md)] |
| 42 | + |
| 43 | +## How to run this sample |
| 44 | + |
| 45 | +1. Clone or download the [PowerApps-Samples](https://github.com/microsoft/PowerApps-Samples) repository. |
| 46 | +1. Open the `/dataverse/webapi/PS/MetadataOperations/MetadataOperationsSample.ps1` file using Visual Studio Code |
| 47 | +1. Edit this line to use the URL of the environment you want to connect to: |
| 48 | + |
| 49 | + `Connect 'https://yourorg.crm.dynamics.com/' # change this` |
| 50 | + |
| 51 | +1. (Optional) Set the `$deleteCreatedRecords` variable to `$false` if you don't want to delete the records this sample creates. |
| 52 | +1. Press <kbd>F5</kbd> to run the sample. |
| 53 | +1. The first time you run the sample a browser window opens. In the browser window, enter or select the credentials you want to use to authenticate. |
| 54 | + |
| 55 | +To connect as a different user, run the [Disconnect-AzAccount command](/powershell/module/az.accounts/disconnect-azaccount) and try again. |
| 56 | + |
| 57 | +## Code |
| 58 | + |
| 59 | +The code for this sample is at: [PowerApps-Samples/dataverse/webapi/PS/MetadataOperations/MetadataOperationsSample.ps1](https://github.com/microsoft/PowerApps-Samples/blob/master/dataverse/webapi/PS/MetadataOperations/MetadataOperationsSample.ps1) |
| 60 | + |
| 61 | +## Demonstrates |
| 62 | + |
| 63 | +This sample has 11 regions: |
| 64 | + |
| 65 | +### Section 0: Create Publisher and Solution |
| 66 | + |
| 67 | +Operations: Create a solution record and an associated publisher record. |
| 68 | + |
| 69 | +> [!NOTE] |
| 70 | +> All solution components created in this sample will be associated to the solution so that they can be exported. For operations without a named message, this association is created using the `MSCRM.SolutionUniqueName` request header setting the solution unique name set as the value. |
| 71 | +> All names of solution components are prefixed using the publisher customization prefix. |
| 72 | +
|
| 73 | +### Section 1: Create, Retrieve and Update Table |
| 74 | + |
| 75 | +Operations: |
| 76 | + |
| 77 | +1. Create a new `sample_BankAccount` user-owned table by sending a `POST` request to `/EntityDefinitions`. |
| 78 | +1. Retrieve the created table by sending a `GET` request to `/EntityDefinitions(LogicalName='sample_bankaccount')`. |
| 79 | +1. Update the table by sending a `PUT` request to `/EntityDefinitions(LogicalName='sample_bankaccount')`. |
| 80 | + |
| 81 | +### Section 2: Create, Retrieve and Update Columns |
| 82 | + |
| 83 | +Operations: |
| 84 | + |
| 85 | +1. Attempt to retrieve a `sample_boolean` boolean column by sending a `GET` request to `/EntityDefinitions(LogicalName='sample_bankaccount')/Attributes(LogicalName='sample_boolean')`. |
| 86 | +1. If the column doesn't already exist, create a new `sample_boolean` boolean column for the `sample_BankAccount` table by sending a `POST` request to `/EntityDefinitions(LogicalName='sample_bankaccount')/Attributes`. |
| 87 | +1. Update the `sample_boolean` boolean column by sending a `PUT` request to `/EntityDefinitions(LogicalName='sample_bankaccount')/Attributes(LogicalName='sample_boolean')`. |
| 88 | +1. Update the option labels for the `sample_boolean` boolean column using the [UpdateOptionValue action](xref:Microsoft.Dynamics.CRM.UpdateOptionValue). |
| 89 | +1. Attempt to retrieve a `sample_datetime` datetime column for the `sample_BankAccount` table, and create it if it doesn't exist. |
| 90 | +1. Attempt to retrieve a `sample_decimal` decimal column for the `sample_BankAccount` table, and create it if it doesn't exist. |
| 91 | +1. Attempt to retrieve a`sample_integer` integer column for the `sample_BankAccount` table, and create it if it doesn't exist. |
| 92 | +1. Attempt to retrieve a `sample_memo` memo column for the `sample_BankAccount` table, and create it if it doesn't exist. |
| 93 | +1. Attempt to retrieve a `sample_money` money column for the `sample_BankAccount` table, and create it if it doesn't exist. |
| 94 | +1. Attempt to retrieve a `sample_choice` choice column for the `sample_BankAccount` table, and create it if it doesn't exist. |
| 95 | +1. Add a new option to the `sample_choice` column using the [InsertOptionValue action](xref:Microsoft.Dynamics.CRM.InsertOptionValue). |
| 96 | +1. Change the order of the options of the `sample_choice` column using the [OrderOption action](xref:Microsoft.Dynamics.CRM.OrderOption). |
| 97 | +1. Delete one of the options of the `sample_choice` column using the [DeleteOptionValue action](xref:Microsoft.Dynamics.CRM.DeleteOptionValue). |
| 98 | +1. Attempt to retrieve a `sample_multiselectchoice` multi-select choice column for the `sample_BankAccount` table, and create it if it doesn't exist. |
| 99 | +1. Create a new Status option for the `sample_BankAccount` table using the [InsertStatusValue Action](xref:Microsoft.Dynamics.CRM.InsertStatusValue). |
| 100 | + |
| 101 | +### Section 3: Create and use Global OptionSet |
| 102 | + |
| 103 | +Operations: |
| 104 | + |
| 105 | +1. Create a new global choice named `sample_colors` by sending a `POST` request to `/GlobalOptionSetDefinitions`. |
| 106 | +1. Retrieve the `sample_colors` global choice by sending a `GET` request to `/GlobalOptionSetDefinitions(<id value>)`. |
| 107 | +1. Create a new `sample_colors` choice column for the `sample_BankAccount` table using the `sample_colors` global choice by sending a `POST` request to `/EntityDefinitions(LogicalName='sample_bankaccount')/Attributes` and associating it to the global choice. |
| 108 | + |
| 109 | +### Section 4: Create Customer Relationship |
| 110 | + |
| 111 | +Operations: |
| 112 | + |
| 113 | +1. Create a new `sample_customerid` customer column for the `sample_BankAccount` table using the [CreateCustomerRelationships Action](xref:Microsoft.Dynamics.CRM.CreateCustomerRelationships). |
| 114 | +1. Retrieve the `sample_customerid` customer column by sending a `GET` request to `/EntityDefinitions(LogicalName='sample_bankaccount')/Attributes(LogicalName='sample_customerid')`. |
| 115 | +1. Retrieve the relationships created for the customer column by sending `GET` requests to `/RelationshipDefinitions(<id>)/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata`.`. |
| 116 | + |
| 117 | +### Section 5: Create and retrieve a one-to-many relationship |
| 118 | + |
| 119 | +Operations: |
| 120 | + |
| 121 | +1. Verify that the `sample_BankAccount` table is eligible to be referenced in a 1:N relationship using the [CanBeReferenced function](xref:Microsoft.Dynamics.CRM.CanBeReferenced). |
| 122 | +1. Verify that the `contact` table is eligible to be reference other tables in a 1:N relationship using the [CanBeReferencing function](xref:Microsoft.Dynamics.CRM.CanBeReferencing). |
| 123 | +1. Identify what other tables can reference the `sample_BankAccount` table in a 1:N relationship using the [GetValidReferencingEntities function](xref:Microsoft.Dynamics.CRM.GetValidReferencingEntities). |
| 124 | +1. Create a 1:N relationship between `sample_BankAccount` and `contact` tables by sending a `POST` request to `/RelationshipDefinitions`. |
| 125 | +1. Retrieve the 1:N relationship by sending `GET` request to `/RelationshipDefinitions(<id>)/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata`. |
| 126 | + |
| 127 | +### Section 6: Create and retrieve a many-to-one relationship |
| 128 | + |
| 129 | +Operations: |
| 130 | + |
| 131 | +1. Create a N:1 relationship between `sample_BankAccount` and `account` tables by sending `POST` a request to `/RelationshipDefinitions`. |
| 132 | +1. Retrieve the N:1 relationship by sending a `GET` request to `/RelationshipDefinitions(<id>)/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata`. |
| 133 | + |
| 134 | +### Section 7: Create and retrieve a many-to-many relationship |
| 135 | + |
| 136 | +Operations: |
| 137 | + |
| 138 | +1. Verify that the `sample_BankAccount` and `contact` tables are eligible to participate in a N:N relationship using the [CanManyToMany function](xref:Microsoft.Dynamics.CRM.CanManyToMany). |
| 139 | +1. Verify that the `sample_BankAccount` and `contact` tables are eligible to participate in a N:N relationship using the [GetValidManyToMany Function](xref:Microsoft.Dynamics.CRM.GetValidManyToMany). |
| 140 | +1. Create a N:N relationship between `sample_BankAccount` and `contact` tables by sending a `POST` request to `/RelationshipDefinitions`. |
| 141 | +1. Retrieve the N:N relationship by sending `GET` request to `/RelationshipDefinitions(<id>)/Microsoft.Dynamics.CRM.ManyToManyRelationshipMetadata`. |
| 142 | + |
| 143 | +### Section 8: Export managed solution |
| 144 | + |
| 145 | +Operations: Export the solution created in [Section 0: Create Publisher and Solution](#section-0-create-publisher-and-solution) containing the items created in this sample using the [ExportSolution Action](xref:Microsoft.Dynamics.CRM.ExportSolution). |
| 146 | + |
| 147 | +### Section 9: Delete sample records |
| 148 | + |
| 149 | +Operations: A reference to each record created in this sample was added to a list as it was created. In this sample the records are deleted in the reverse order in which they were created. |
| 150 | + |
| 151 | +### Section 10: Import and Delete managed solution |
| 152 | + |
| 153 | +Operations: |
| 154 | + |
| 155 | +1. Import the solution exported in [Section 8](#section-8-export-managed-solution) using the [ImportSolution action](xref:Microsoft.Dynamics.CRM.ImportSolution). |
| 156 | +1. Query the solution table to get the `solutionid` of the imported solution. |
| 157 | +1. Delete the imported solution using the `solutionid`. |
| 158 | + |
| 159 | +## Clean up |
| 160 | + |
| 161 | +By default this sample will delete all the records created in it. If you want to view created records after the sample is completed, change the `deleteCreatedRecords` variable to `false` and you will be prompted to decide if you want to delete the records. |
| 162 | + |
| 163 | +### See also |
| 164 | + |
| 165 | +[Use the Dataverse Web API](../overview.md)<br /> |
| 166 | +[Use the Web API with table definitions](../use-web-api-metadata.md)<br /> |
| 167 | +[Web API Samples](../web-api-samples.md)<br /> |
| 168 | +[Web API Basic Operations Sample (PowerShell)](basic-operations-powershell.md) |
| 169 | + |
| 170 | +[!INCLUDE[footer-include](../../../../includes/footer-banner.md)] |
0 commit comments