Custom Connectors: Actions, Triggers, and Parameters

1. The Anatomy of a Connector Definition

After configuring the General and Security tabs, you land on the Definition tab. This is where you bring your connector to life.

Here, you will define two primary components:

• Actions: These are the operations the connector can perform, initiated by a user or another process. They are the "verbs" of your connector, corresponding directly to API calls like GET /users/{id} or POST /orders. Actions can be used in both Power Apps and Power Automate.
• Triggers: These are events that start a Power Automate flow. For example, a flow could be triggered "When a new file is added" in a custom storage system. Triggers are only for Power Automate.

2. Defining Actions: The Core of Your Connector

Actions are the most common component you'll create. Let's walk through the process of defining one.

The most efficient way to define an action is using the Import from sample feature. This lets Power Platform infer the parameters and response schema directly from a sample API call.

Step-by-Step: Creating an Action

Let's break down the process you just read about.

1. General Information: You start by providing metadata for your action:

   • Summary: A short, user-friendly description of what the action does (e.g., "Get my user profile"). This appears as the action title in Power Automate/Apps.
   • Description: A more detailed explanation.
   • Operation ID: A unique internal name for the action, like a method name in C#. It must be unique within the connector (e.g., GetUserProfile).
   • Visibility: Controls how the action appears to the end-user (none, advanced, internal). internal is useful for helper actions that shouldn't be exposed directly.

2. Request: This defines the API call itself.

   • Click Import from sample.
   • Verb: Select the HTTP method (GET, POST, PUT, DELETE, etc.).
   • URL: Paste the full request URL, including any query parameters (e.g., https://api.example.com/v1/users?status=active).
   • Headers: Add any required headers (e.g., Content-Type).
   • Body: For POST or PUT requests, paste a sample JSON body.

   The platform will parse this information to identify path parameters (like {id} in /users/{id}), query parameters, and the body schema.

3. Response: This defines the structure of the data returned by the API.

   • Click Add default response.
   • Paste a sample JSON response from the API.
   • Click Import.

   This step is crucial. Defining the response creates a schema that Power Apps and Power Automate use to understand the output. It's what populates the "Dynamic content" list in Power Automate and allows you to reference output properties with dot notation (e.g., MyConnector.MyAction().User.DisplayName) in Power Apps.

A Practical Demonstration

The following video provides an excellent demonstration of creating both a simple GET action and a more complex POST action with a request body, and then refining the parameters.

3. Defining Triggers: Starting Automated Workflows

While actions are initiated by a user, triggers start a flow automatically in response to an event. There are two types.

A. Polling Triggers

This is the most common type of trigger. It works by having Power Automate call your API at a regular interval (e.g., every 5 minutes) to check for new items.

To implement a polling trigger, your API needs an endpoint that can return items created or modified since a certain point in time. For example, GET /invoices?modified_since={timestamp}.

When you configure the polling trigger, you specify:

• The action that fetches the new data.
• The parameter in that action that will receive the timestamp or token from the previous poll (the "trigger state").
• The array in the response that contains the new items. Power Automate will run the flow once for each item in this array.

B. Webhook Triggers

Webhooks (or "push" triggers) are more efficient. Instead of Power Automate polling your service, your service notifies Power Automate when an event occurs.

To implement a webhook trigger, your API must have a specific contract:

1. An endpoint to register a webhook (a POST request), where Power Automate can send a callback URL.
2. An endpoint to unregister a webhook (a DELETE request), which Power Automate calls when the flow is turned off or deleted.

When the event happens on your backend, your service makes a POST request to the stored callback URL with the event payload. This is a more advanced pattern that requires control over the source API's architecture.

4. Hands-On Lab Example

The best way to solidify these concepts is to see them in a practical lab context. The official PL-400 labs include an excellent exercise where you build a custom connector for an Azure Function.

This lab exercise perfectly illustrates the workflow: create the connector, configure security, and then use the Definition tab to define a POST action, importing the request body and the expected response structure from sample JSON.

Conclusion

You have now learned how to use the Definition tab to give your custom connector its purpose. By defining actions and triggers, you expose an API's functionality to the Power Platform, enabling powerful new integrations and automations.

Key Takeaways:

• Actions are user-initiated operations that map to API endpoints; they are the core functions of your connector.
• Triggers are events that automatically start a Power Automate flow. They can be Polling (periodic checks) or Webhook (push notifications).
• Using Import from sample for both the Request and Response is the most effective way to build your definitions.
• Defining a Response is critical for making the output data available as structured objects and dynamic content in apps and flows.
• Refining parameters (setting default values, visibility, etc.) is key to creating a polished, user-friendly connector.

What's Next

We have defined the basic structure and behavior of our connector's operations. But what if we need to modify the request or response in flight? For example, what if we need to add a timestamp to every outgoing request or reformat a date in the response?

In our next lesson, we will explore this by learning how to implement policy templates to modify the behavior of a custom connector at runtime. This adds another layer of powerful, no-code transformation capabilities to your connectors.