Skip to content

Latest commit

 

History

History
380 lines (301 loc) · 19.2 KB

set-up-notification-workflow.md

File metadata and controls

380 lines (301 loc) · 19.2 KB
titledescriptionms.servicems.topicms.datems.authorauthorms.custom
Workflow automation after API registration - Azure API Center
Learn how to set up a notification workflow to set API status in your organization's API center using Azure Logic Apps and Microsoft Teams.
azure-api-center
how-to
10/18/2024
danlep
dlepow

Set up a notification workflow after an API is registered in Azure API Center

This article shows how to set up an automated notification workflow for updating the status of an API after it's registered in your organization's API center. Adapt this example to automate workflows for other types of events in your API center.

Setting up a notification workflow can be useful for several reasons:

  • Real-time updates - Receive alerts immediately when certain events occur, such as API registration or API definition updates. Quickly address issues or take further actions based on these events.
  • Automation - Save time and reduce manual monitoring. For example, set up alerts for when a new API is registered, an API definition changes, or API analysis reports are generated.
  • Improved user experience - By integrating notifications, keep users informed about the status of their requests or actions. This can include approval processes for your APIs, changing custom metadata based on criteria.
  • Collaboration - Send notifications to different team members based on their roles (for example, API administrator, API developer), ensuring that the right people are informed and can take appropriate actions.

In this simplified example:

  • Registering an API in your API center triggers an event that runs an Azure Logic Apps workflow.
  • The workflow sends a notification in Microsoft Teams to a designated individual.
  • The individual decides the status of the API registration directly from the notification in Microsoft Teams.
  • The workflow updates the API status metadata in the API registration based on the individual's decision. API status is a custom metadata property which you set up in your API center.

You can adapt this example to meet your organization's notification and governance requirements for your API center. You can also trigger a similar automated cloud workflow in Power Automate.

Prerequisites

Step 1. Add a custom metadata property in your API center

The example workflow in this article sets the value of an example custom metadata property in your API center for the status of an API registration.

To create a custom api-status property in your API center:

  1. In the Azure portal, navigate to your API center.
  2. In the left menu, under Assets, select Metadata > + New metadata.
  3. In the Details tab, enter the following details:
    1. In Title, enter api-status.
    2. In Type, select Predefined choices.
    3. Add the following predefined choices: new, pending, approved. Select Next.
  4. In the Assignments tab, next to APIs, select Optional.
  5. Optionally make assignments to Deployments and Environments. Select Next.
  6. Review the configuration and select Create.

Step 2. Enable a managed identity in your logic app

For this scenario, the logic app uses a managed identity to access the Azure API center. Depending on your needs, enable either a system-assigned or user-assigned managed identity. For configuration steps, see Authenticate access and connections to Azure resources with managed identities in Azure Logic Apps.

:::image type="content" source="media/set-up-notification-workflow/managed-identity-logic-app.png" alt-text="Screenshot of configuring managed identity in the portal.":::

Step 3. Assign permissions to the managed identity

Assign the logic app managed identity the necessary permissions to access the API center. For this scenario, assign the Contributor role to the managed identity.

  1. In the Azure portal, navigate to your API center and select Access control (IAM).
  2. Select + Add > Add role assignment.
  3. Select Privileged administrator roles and then select Contributor. Select Next.
  4. On the Members page, in Assign access to, select Managed identity > + Select members.
  5. On the Select managed identities page, search for and select the managed identity of the logic app. Click Select and then Next.
  6. Review the role assignment, and select Review + assign.

Step 4. Configure logic app workflow

This section provides the manual steps to configure an event subscription that triggers a logic app workflow when an API is registered in your API center.

Step 4.1. When a resource event occurs

Configure a workflow step to trigger the logic app workflow when an event occurs in the API center.

  1. In the portal, navigate to your logic app.

  2. In the left menu, under Development tools, select Logic app designer.

  3. Select Add a trigger.

  4. Search for Azure Event Grid, and select the When a resource event occurs trigger.

  5. In the When a resource event occurs pane:

    1. In Resource type, select Microsoft.ApiCenter.Services.
    2. In Subscription, select your subscription.
    3. In Resource Name, enter the full resource name of your API center, in the following form: /subscriptions/<subscription ID>/resourceGroups/<resource group nam>/providers/Microsoft.ApiCenter/services/<API Center name>.
    4. In Event Type Item - 1, enter or select Microsoft.ApiCenter.ApiAdded.

:::image type="content" source="media/set-up-notification-workflow/when-resource-event-occurs.png" alt-text="Screenshot of When a resource event occurs action in the portal.":::

Step 4.2. Initialize variable - subjectvar

Add a workflow step to initialize a variable that stores the ID of the API that's registered.

  1. Select Add an action.
  2. In the search box, enter Variables.
  3. Under Variables, select Initialize variable.
  4. In the Initialize variable pane:
    1. In Name, enter subjectvar.
    2. In Type, select String.
    3. In Value, enter / and select Insert dynamic content.
    4. Under When a resource event occurs, select Subject.

:::image type="content" source="media/set-up-notification-workflow/initialize-subjectvar-variable.png" alt-text="Screenshot of initializing subjectvar variable in the portal.":::

Step 4.3. Initialize variable - versionvar

Add a workflow step to initialize a variable to store the version of the API Center management API. This version is needed for the HTTP requests in the workflow.

Tip

Initializing a variable for the version makes it easy to change the value later, as the management API gets updated.

  1. Select Add an action.
  2. In the search box, enter Variables.
  3. Under Variables, select Initialize variable.
  4. In the Initialize variable pane:
    1. In Name, enter versionvar.
    2. In Type, select String.
    3. In Value, enter ?api-version=2024-03-01.

:::image type="content" source="media/set-up-notification-workflow/initialize-versionvar-variable.png" alt-text="Screenshot of initializing versionvar variable in the portal.":::

Step 4.4. HTTP action to get API details

Add a workflow step to make an HTTP GET request to get API details from the API center.

  1. Select Add an action.
  2. In the search box, enter HTTP.
  3. Under HTTP, select HTTP.
  4. In the HTTP pane:
    1. In URI, enter https://management.azure.com/ (including the trailing forward slash). After the forward slash, enter /, select Insert dynamic content, and then select the variables subjectvar and versionvar, in that order.
    2. In Method, select GET.
    3. Under Advanced parameters, select Authentication.
      1. In Authentication type, select Managed Identity.
      2. In Managed identity, select System-assigned managed identity.
      3. In Audience, enter https://management.azure.com/.

:::image type="content" source="media/set-up-notification-workflow/http-request-get.png" alt-text="Screenshot of HTTP GET request action in the portal.":::

Step 4.5. Parse JSON action

Add a workflow step to parse the JSON output of the preceding HTTP request.

  1. Select Add an action.
  2. In the search box, enter Parse JSON.
  3. Under Data operations, select Parse JSON.
  4. In the Parse JSON pane:
    1. In Content, enter / and select Insert dynamic content.
    2. Under HTTP, select Body.
    3. In Schema, enter the following: 
      { "type": "object", "properties": { "type": { "type": "string" }, "properties": { "type": "object", "properties": { "title": { "type": "string" }, "kind": { "type": "string" }, "description": { "type": "string" }, "lifecycleStage": { "type": "string" }, "externalDocumentation": { "type": "array" }, "contacts": { "type": "array" }, "customProperties": { "type": "object", "properties": {} } } }, "id": { "type": "string" }, "name": { "type": "string" }, "systemData": { "type": "object", "properties": { "createdAt": { "type": "string" }, "lastModifiedAt": { "type": "string" } } } } }

:::image type="content" source="media/set-up-notification-workflow/parse-json.png" alt-text="Screenshot of parse JSON action in the portal.":::

Step 4.6. Post adaptive card to Teams

Add a workflow step to post the notification as an adaptive card in Microsoft Teams.

  1. Select Add an action.

  2. In the search box, enter Teams.

  3. Under Microsoft Teams, select Post adaptive card and wait for a response. If prompted, sign in to your Microsoft Teams account.

  4. In the Post adaptive card and wait for a response pane:

    1. In Post as, select Flow bot.
    2. In Post in, select an appropriate option for your Teams setup. For testing, you can select Chat with Flow bot.
    3. In Message, enter the following text for an adaptive card. Modify the text as needed. 
      { "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.4", "body": [ { "type": "TextBlock", "text": "Hi API Admin,", "weight": "Bolder", "size": "Medium" }, { "type": "TextBlock", "text": "A new API has been registered.", "wrap": true }, { "type": "TextBlock", "text": "API Title: **{{apiTitle}}**", "wrap": true }, { "type": "TextBlock", "text": "Please provide the status for this API:", "wrap": true }, { "type": "Input.ChoiceSet", "id": "apiStatus", "style": "expanded", "choices": [ { "title": "New", "value": "new" }, { "title": "Pending", "value": "pending" }, { "title": "Approved", "value": "approved" } ], "isRequired": true, "errorMessage": "Please select a status." } ], "actions": [ { "type": "Action.Submit", "title": "Submit" } ] }

  5. Select the text {{apiTitle}} in the message and delete it. Enter / and select Insert dynamic content. Under Parse JSON, select Body title to replace the selected text with the dynamic content.

  6. In Recipient, enter the email address of the individual who receives notifications.

:::image type="content" source="media/set-up-notification-workflow/post-adaptive-card.png" alt-text="Screenshot of post adaptive card to Teams action in the portal.":::

Step 4.7. Initialize variable - statusvar

Add a workflow step to initialize the value of a variable that stores the API status value returned from the Teams adaptive card.

  1. Select Add an action.
  2. In the search box, enter Variables.
  3. Under Variables, select Initialize variable.
  4. In the Initialize variable pane:
    1. In Name, enter statusvar.
    2. In Type, select String.
    3. In Value, enter @body('Post_adaptive_card_and_wait_for_a_response')?['data']?['apiStatus'].

:::image type="content" source="media/set-up-notification-workflow/initialize-statusvar-variable.png" alt-text="Screenshot of initializing statusvar variable in the portal.":::

Step 4.8. HTTP action - update API properties in Azure API Center

Add a workflow step to make an HTTP PUT request to update the API properties in your API center.

  1. Select Add an action.
  2. In the search box, enter HTTP.
  3. Under HTTP, select HTTP.
  4. In the HTTP pane:
    1. In URI, enter https://management.azure.com/ (including the trailing forward slash). After the forward slash, enter /, select Insert dynamic content, and then select the variables subjectvar and versionvar, in that order.
    2. In Method, select PUT.
    3. In Body, enter the following: 
      { "properties": { "customProperties": { "api-status": "@variables('statusvar')" }, "title": "@body('Parse_JSON')?['properties']?['title']", "description": "@body('Parse_JSON')?['properties']?['description']", "lifecycleStage": "@body('Parse_JSON')?['properties']?['lifecycleStage']", "kind": "@body('Parse_JSON')?['properties']?['kind']" } }
    4. Under Advanced parameters, select Authentication.
      1. In Authentication type, select Managed Identity.
      2. In Managed identity, select System-assigned managed identity.
      3. In Audience, enter https://management.azure.com/.

:::image type="content" source="media/set-up-notification-workflow/http-request-put.png" alt-text="Screenshot of HTTP PUT request action in the portal.":::

Step 4.9. Save the workflow

Save the workflow in the Logic app designer. When the workflow is complete, it should look similar to the following image:

:::image type="content" source="media/set-up-notification-workflow/logic-app-designer-workflow.png" lightbox="media/set-up-notification-workflow/logic-app-designer-workflow-large.png" alt-text="Screenshot of complete workflow in Logic app designer in the portal.":::

Confirm that the event subscription is provisioned successfully in your API center. It might take a few minutes for the event subscription to be provisioned.

  1. In the Azure portal, navigate to your API center.
  2. In the left menu, select Events > Event Subscriptions.
  3. Check that the logic app is listed under Name, and the Endpoint is Webhook.

:::image type="content" source="media/set-up-notification-workflow/logic-app-event-subscription.png" alt-text="Screenshot of a logic app event subscription in the portal.":::

Step 5. Test the event subscription

Test the event subscription by registering an API in your API center:

  1. In the Azure portal, navigate to your API center.

  2. Register an API in your API center. After the API is registered:

    • The event subscription triggers the logic app workflow.
    • The logic app workflow runs and sends a notification to the individual in Microsoft Teams.

  3. In Microsoft Teams, view the adaptive card, make an API status selection, and select Submit. :::image type="content" source="media/set-up-notification-workflow/teams-adaptive-card.png" alt-text="Screenshot of adaptive card in Microsoft Teams.":::

    The logic app workflow updates the api-status property in the API registration in your API center.

  4. In your API center, view the API details to see the updated value for the custom api-status property.

    :::image type="content" source="media/set-up-notification-workflow/view-api-custom-property.png" alt-text="Screenshot of updated API registration in the portal.":::

View the logic app run history

To get details about the logic app run and troubleshoot any issues:

  1. In the Azure portal, navigate to your logic app.
  2. In the left menu, under Development Tools, select Run History.
  3. Select the run to see the details of each step.

Related content

close