External notifications

Applies to: Configuration Manager (current branch)

In a complex IT environment, you may have an automation system like Azure Logic Apps. Customers use these systems to define and control automated workflows to integrate multiple systems. You could integrate Configuration Manager into a separate automation system through the product's SDK APIs. But this process can be complex and challenging for IT professionals without a software development background.

Starting in version 2107, you can enable the site to send notifications to an external system or application. This feature simplifies the process by using a web service-based method. You configure subscriptions to send these notifications. These notifications are in response to specific, defined events as they occur. For example, status message filter rules.

Note

The external system or application defines and provides the methods that this feature calls.

When you set up this feature, the site opens a communication channel with the external system. That system can then start a complex workflow or action that doesn't exist in Configuration Manager.

Starting in version 2111, use the Configuration Manager console to create or edit subscriptions for external notifications. This article now focuses on that experience. If you're using version 2107, see Configuration Manager version 2107.

Prerequisites

• Create the subscription on the top-level site of the hierarchy. This site is either a standalone primary site, or a central administration site (CAS). You can view and modify an existing subscription on any site in a hierarchy.

• The site's service connection point needs to be in online mode. For more information, see About the service connection point.

• Currently, this feature only supports Azure Logic Apps as the external system. An active Azure subscription with rights to create a logic app is required.

  The service connection point needs to communicate with the notification service, for example Azure Logic Apps. For more information, see Internet access requirements.

• To create an event type for an application approval request, the site needs an app that requires approval and is deployed to a user collection. For more information, see Deploy applications and Approve applications.

Permissions

You can configure the following permissions to the NotificationSubscription object: Read, Delete, Modify, Create.

• The Full administrator default security role has these permissions.
• The Read only analyst default security role has the Read permission.

In version 2107, users also need the All security scope. In version 2111 and later, you can't scope the subscription objects. If needed, you can use scopes on the Site object, to which users need at least read permission.

Other permissions may be required for custom roles. Use the following table to understand what's needed:

Action	Alerts: Read	Site: Read	Notify: Read	Notify: Modify	Notify: Create	Notify: Delete	Site: Manage SFR
View subscription	X		X
Modify subscription	X	X	X	X
Create subscription Note 1	X	X	X		X
Delete subscription	X		X			X
Create new SFR	X	X	X	Note 2	Note 2		X
Add existing SFR	X	X	X	Note 2	Note 2
Add app approval	X	X	X	Note 2	Note 2

The above table uses the following shorthand:

• Notify: Notification subscription objects
• SFR: Status filter rule

Note 1: Top-level site in hierarchy

Create the subscription on the top-level site of the hierarchy. This site is either a standalone primary site, or a CAS. You can view and modify an existing subscription on any site in a hierarchy.

Note 2: Modify and Create permissions for event actions

When managing events on the subscription, the permissions to Modify or Create on the Notification subscription object depend upon whether you need to modify or create the event. For example, if you have the Create permission, then you can add a status filter rule to the subscription. If you don't have the Modify permission, then you can't make changes to the subscription events.

Create an Azure logic app and workflow

Use the following process to create a sample app in Azure Logic Apps to receive the notification from Configuration Manager.

Note

This process is provided as an example to help you get started. It's not intended for production use.

1. Sign in to the Azure portal.

2. In the Azure search box, enter logic apps, and select Logic Apps.

3. Select Add and choose Consumption. This action creates a new logic app.

4. On the Basics tab, specify the project details as necessary for your environment: subscription name, resource group, logic app name, and region.

5. Select Review + create. On the validation page, confirm the details that you provided, and select Create.

6. Under Next steps, select Go to resource.

7. Under the section to Start with a common trigger, select When a HTTP request is received.

8. At the bottom of the trigger editor, select Use sample payload to generate schema.

9. Paste the following sample payload:

   {
       "EventID":0,
       "EventName":"",
       "SiteCode":"",
       "ServerName":"",
       "MessageID":0,
       "Source":"",
       "EventPayload":""
   }
   

10. Select Done and then select Save.

11. Copy the generated URL for the logic app. You'll use this URL later when you create the subscription in Configuration Manager.

    Note

    The URL from Azure for the logic app includes the secret key. When saved in Configuration Manager, it's protected the same as any other password or secret key. If your environment uses a proxy server or other network inspection device, there's a risk that it will log this URL and expose the secret key. Control access to such systems, and be prepared to renew the secret key for the logic app in the Azure portal. You can also set an expiration date for the secret key in the Azure portal. For more information, see Secure your logic apps.

12. To add a new step in the designer, select + New Step. Choose an appropriate action when it receives a notification from Configuration Manager. For example:

    • To send an email, use the Office 365 Outlook connector.
    • To post a message to Teams, use the Microsoft Teams connector.

    Sign in if necessary and complete the required information for the action. For more information, see the Create logic apps quickstart in the Azure Logic Apps documentation.

Notification schema

These notifications use the following standardized schema:

{
    "properties": {
        "EventID": {
            "type": "integer"
        },
        "EventName": {
            "type": "string"
        },
        "EventPayload": {
            "type": "string"
        },
        "MessageID": {
            "type": "string"
        },
        "ServerName": {
            "type": "string"
        },
        "SiteCode": {
            "type": "string"
        },
        "Source": {
            "type": "string"
        }
    },
    "type": "object"
}

Create an event

There are two types of events that are currently supported:

• The site raises a status message that matches conditions specified in a status filter rule for external notification. You can create a new rule or use an existing one.

• A user requests approval for an application in Software Center.

Note

In a hierarchy, the scope of events depends upon the event type:

• Application approval events only happen at primary sites.
• Status filter rules apply to the site where you create the rule using the Create external service notification event wizard.
  • If you run the wizard to create the event while connected to the CAS, it only triggers on matching events from the CAS.
  • To subscribe to events raised by a child primary site, connect to the primary site. Modify the notification subscription to create a new status filter rule for the child primary site.

Use the following process to create an event:

1. In the Configuration Manager console, connect to the top-level site of the hierarchy. This site is either a standalone primary site, or a CAS.

2. Go to the Monitoring workspace, expand Alerts, and select the External service notifications node.

3. In the ribbon, select Create subscription.

4. In the New Subscription window, specify a Name for the subscription to identify it in the Configuration Manager console. The maximum length is 254 characters. Optionally add a Description.

5. For the External service URL value, paste the URL of the Azure Logic App that you previously copied.

6. Select the gold asterisk to add a new event to the subscription.

   1. In the Create External Service Notification Event wizard, on the Event type page, select one of the following event types:

      • New status filter rule: Create a new status filter rule to use for this event. Specify a name for the status filter rule, and then configure the filter criteria. For more information about criteria for status message rules, see Use the status system.

        Important

        Be cautious with the type of status filter rule that you create. For external notifications, the site can process 300 status messages every five minutes. If your rule allows more messages than this limit, it will cause a backlog on the site. Create rules with narrow filters for specific scenarios. Avoid generic rules that allow a lot of messages.

      • Existing status filter rule: Reuse a status filter rule for external notification that already exists. It doesn't display all status filter rules, only the rules that you created using this wizard.

      • User submits application request: Send an external notification for application approval requests.

Manage events

After you create a subscription, use the External service notifications node to do the following actions:

• Properties: Edit the name, description, or events for a subscription. You can't edit the external service URL.

• Delete: Remove a subscription.

Note

You can view and modify an existing subscription on any site in a hierarchy.

When you select a subscription, the details pane shows information about the events that have happened.

Trigger an event

The process to trigger an event depends upon the type of subscription:

• For a status filter rule, trigger an event for the site component. For example, use the Configuration Manager Service Manager to restart the component.

• For an app approval request, use Software Center to request an app that requires approval. For more information, see Software Center user guide.

Monitor the workflow

Configuration Manager Console

Starting in version 2309, when Azure Logic Apps generate notifications or alerts related to specific events or conditions, Configuration Manager can now capture and display these notifications. This integration enables the monitoring of Azure Logic App notifications directly within the Configuration Manager console, providing a centralized location for tracking critical events, taking appropriate actions and maintain a high level of operational efficiency. 

To use this feature a valid Microsoft Entra Web app is required. Please deploy the Azure services for Administration Service Management under Administration\Overview\Cloud Services\Azure Services. If the service is already deployed, admin can use the existing web application to view Run details from Azure logic app.

For more information, see Configure Azure services for use with Configuration Manager.

Use the following process to view Run Details of subscription:

1. In the Configuration Manager console click Monitoring.
2. In the Monitoring workspace, click External Service Notifications and select the desired subscription.
3. Click on Show Details.
4. In the dialog box, Select the Azure Environment, Microsoft Entra tenant name from the drop down and SignIn using your Azure Admin Account.
5. Select the Subscription ID and enter the Resource group name and Workflow name.
6. Click on Get Run Details button to view the Run Details.

Azure Portal

Within five minutes, the event triggers the logic app workflow. Check the status of the workflow in the Azure portal. Navigate to the Runs history page of the logic app.

For more information, see Monitor run status, review trigger history, and set up alerts for Azure Logic Apps.

Troubleshoot

Use the following Configuration Manager log files on the site server to help troubleshoot this process:

• ExternalNotificationsWorker.log: Check if the queue has been processed and notifications are sent to external system.
• statmgr.log: Check if the status filter rules have been processed without errors

Known issues

If you create a status filter rule, you'll see it in the site's list of Status filter rules in the Configuration Manager console. If you make a change on the Actions tab of the rule properties, the external notification won't work.

After you recover a central administration site (CAS), delete and recreate the subscription.

Tip

Before you remove a CAS, recreate the subscriptions at the child primary site.

Configuration Manager version 2107

Important

This section and the PowerShell script only apply to version 2107. In version 2111 and later, use the Configuration Manager console to create and manage events.

Other prerequisites for version 2107

To create the objects in Configuration Manager version 2107, you need to use the PowerShell script SetupExternalServiceNotifications.ps1. Use the following script sample to properly get the PowerShell script to use for this feature:

$FileName = ".\SetupExternalServiceNotifications.ps1"
Invoke-WebRequest https://aka.ms/cmextnotificationscript -OutFile $FileName
(Get-Content $FileName -Raw).Replace("`n","`r`n") | Set-Content $FileName -Force
(Get-Content $FileName -Raw).TrimEnd("`r`n") | Set-Content $FileName -Force

Note

SetupExternalServiceNotifications.ps1 is digitally signed by Microsoft. This script sample downloads the file and fixes the line breaks to preserve the digital signature.

Create an event in version 2107

There are two types of events that are supported in version 2107:

• The site raises a status message that matches conditions specified in a status filter rule.

• A user requests approval for an application in Software Center.

Create a status message event in version 2107

1. On the site server, run SetupExternalServiceNotifications.ps1. Since you're running it on the site server, enter y to continue.

2. Select option 2 to create a new status filter rule.

3. Specify a name for the new status filter rule.

4. Select message-matching criteria for the rule, and specify values to match. Specify 0 to not use a criterion.

   The following criteria are available:

   • Source: Client, SMS Provider, Site Server
   • Site code
   • System
   • Component
   • Message type: Milestone, Detail, Audit
   • Severity: Informational, Warning, Error
   • Message ID
   • Property
   • Property value

   For more information about criteria for status message rules, see Use the status system.

   Important

   Be cautious with the type of status filter rule that you create. For external notifications, the site can process 300 status messages every five minutes. If your rule allows more messages than this limit, it will cause a backlog on the site. Create rules with narrow filters for specific scenarios. Avoid generic rules that allow a lot of messages.

5. Rerun the PowerShell script. Select option 3 to create a new subscription.

6. Specify a name and description for the subscription. Then specify the logic app URL that you previously copied from the Azure portal.

7. Select the new status filter rule.

8. Select 0 to exit the script.

Create an app approval event in version 2107

Note

This event type requires an application that requires approval and is deployed to a user collection. For more information, see Deploy applications and Approve applications.

1. On the site server, run SetupExternalServiceNotifications.ps1. Since you're running it on the site server, enter y to continue.

2. Select option 3 to create a new subscription.

3. Specify a name and description for the subscription. Then specify the logic app URL that you previously copied from the Azure portal.

4. Select the appropriate event for an application request.

5. Select 0 to exit the script.

Remove a subscription in version 2107

If you need to delete a subscription, use the following process:

1. Run the SetupExternalServiceNotifications.ps1 script with option 1 to list the available subscriptions. Note the subscription ID, which is an integer value.

2. Use the NotificationSubscription API of the administration service. Make a DELETE call to the URI https://<SMSProviderFQDN>/AdminService/v1.0/NotificationSubscription/<Subscription_ID>.

   For more information, see How to use the administration service in Configuration Manager.

After you remove the subscription, the site doesn't send notifications to the external system.

Script usage in version 2107

When you run SetupExternalServiceNotifications.ps1, it detects whether it's running on a site server:

• Y: Continue on the current server
• N: Specify the FQDN of a site server to use

If the script doesn't detect a site server, it prompts for an FQDN.

The following actions are then available:

• 0: Skip/continue
• 1: List available subscriptions
• 2: Create a status filter rule to expose status messages
• 3: Create a subscription. This option is only available for the top-level site.

Note

This script is only supported for sites running version 2107 or later.

Next steps

Use the status system

Configure alerts