Exercise - Use CLI to download a connector

  • 6 minutes

In this exercise, you'll use CLI to download a connector, validate the definition, and resolve issues. This exercise simulates what you would do to prepare for creating and certifying an open-source custom connector.

This exercise requires you to install Python and access the command prompt on the machine that you're using for the exercise.

Important

Use a test environment with Microsoft Dataverse provisioned. If you do not have one, you can sign up for the community plan.

Note

Download the following file to your local computer to complete this exercise Contoso Invoicing Triggers. Select the download button on the middle-right of the screen.

Task 1: Import the solution

In this task, you'll import an unmanaged solution that contains a Contoso Invoicing custom connector. You'll use this connector to complete the tasks in this exercise.

  1. Go to Power Apps maker portal and make sure that you are in the correct environment.

  2. Select Solutions > Import solution.

  3. Select Browse.

  4. Select the ContosoInvoicingOpenSource_1_0_0_0.zip solution and then select Open.

  5. Select Next.

  6. Select Import and then wait for the import to complete. You should get a success message after the import completes.

  7. Open the Contoso Invoicing - Open Source solution that you imported.

    You should see the Contoso Invoicing - Open Source custom connector component.

    Screenshot of solution components in Contoso Invoicing - Open Source.

Task 2: Install Microsoft Power Platform CLI

Microsoft Power Platform CLI includes the paconn command-line tool that is designed to aid Microsoft Power Platform custom connector development. The paconn tool uses Python runtime, which you'll be installing as well.

  1. Go to Download Python and select Download Python. You can use any version greater than 3.5.

  2. Select the downloaded .exe file to start installation.

  3. Select the Add Python xx to Path check box, select Install Now, and then wait for the installation to complete.

    Screenshot of the Install Python dialog box.

  4. Close the installation wizard after the installation completes.

  5. Start the command prompt and then run the following command to install paconn.

    pip install paconn

    Screenshot of the command prompt showing the install paconn command.

  6. Wait for the installation to complete.

Task 3: Download the connector locally

In this task, you'll download the connector definition files locally so that you can add the Host URL property.

  1. Run the login command.

    paconn login

  2. Copy the provided Code.

    Screenshot of the login command response with a code to copy.

  3. In a browser, sign in with the same credentials as your environment. Go to Microsoft Device Login, paste the Code that you copied, and then select Next.

  4. Provide your credentials.

  5. Select Continue.

    You should get a successful sign-in message.

    Screenshot of the successful sign-in message.

  6. Return to the command prompt, where you should see a login successful message.

  7. Run the download command.

    paconn download

  8. When prompted to select an environment, enter a number for the environment where you installed the solution and then press the Enter key.

  9. Provide the number of the Contoso Invoicing - Open Source connector and then press the Enter key.

  10. The download should complete successfully. Note the location where the connector was downloaded.

Task 4: Validate

In this task, you'll validate the connector and fix some common errors. You'll also add the required connector metadata.

  1. Copy the path where the connector was downloaded.

    Screenshot of the connector path selected in the command window.

  2. Run the validate command by using the path that you copied plus the API definition Swagger file name \apiDefinition.swagger.json.

    paconn validate --api-def [Path to apiDefinition.swagger.json]

    Screenshot of the validate command in the command window.

  3. You should get an error for a missing summary for the fourth parameter of the ListInvoices action and a missing contact property.

    Screenshot of validation errors in the command window.

  4. Fix the missing summary. Go to Power Apps maker portal and make sure that you are in the correct environment.

  5. Select Solutions and open the Contoso Invoicing - Open Source solution.

  6. Select the Contoso Invoicing - Open Source connector and then select Edit.

    An arrow pointing to the edit custom connector button.

  7. Select the Definition tab and then select the ListInvoices action.

  8. Scroll down to the Request section, select the ellipsis (Chevron) button of the toAmount parameter, and then select Edit.

    An arrow pointing to the edit parameter button.

  9. Enter To amount in the Summary field and then select Update connector.

    An arrow pointing to the Update connector button.

  10. Wait for the connector update to complete.

  11. Delete the connector that you previously downloaded (you'll add it again in a moment). Delete the connector that you downloaded from your machine.

  12. Download the connector again. Return to the command prompt and run the download command again.

    paconn download

  13. When prompted to select an environment, enter the number for the environment where you installed the solution and then press the Enter key.

  14. Provide the number of the Contoso Invoicing - Open Source connector and then press the Enter key.

  15. The download should complete successfully. Note the location where the connector was downloaded.

  16. Run the validate command by using the path that you copied plus the API definition Swagger file name \apiDefinition.swagger.json.

    paconn validate --api-def [Path to apiDefinition.swagger.json]

  17. You should now receive only one error for the missing contact parameter.

    Validation error.

  18. Go to the connector folder that you downloaded and open the apiDefinition.swagger.json file by using the text editor of your choice, such as Notepad.

    Open connector definition file.

  19. Add a contact property to the information after the description property.

    "contact": {
  "name": "Contoso Support",
  "url": "https://contosoinvoicingtest.azurewebsites.net",
  "email": "info@Contoso.com"
}

    Screenshot of the contact parameter added to the Swagger definition with a comma at the end of the description property.

  20. Add connector metadata after the information.

    "x-ms-connector-metadata": [
  {
   "propertyName": "Website",
   "propertyValue": "https://contosoinvoicingtest.azurewebsites.net"
  },
  {
   "propertyName": "Privacy policy",
   "propertyValue": "https://contosoinvoicingtest.azurewebsites.net"
  },
  {
   "propertyName": "Categories",
   "propertyValue": "Productivity"
  }
],

    Screenshot of connector metadata added after the info with a comma at the end of the info section.

  21. Select File and Save your changes.

  22. Run the validate command one more time.

    paconn validate --api-def [Path to apiDefinition.swagger.json]

  23. The connector should now get validated successfully.

Screenshot of the successful connector validation.

You've successfully prepared the connector to be created as open source and then certified. If you were building a real connector, you would go on to publish the connector to GitHub.