Hello, everyone!
Welcome back to our blog series on automation and API capabilities within Microsoft Configuration Manager. In our previous posts, we explored various aspects such as the SMS Provider, Windows Management Instrumentation (WMI), and PowerShell Cmdlets. Today, we'll delve into the final chapter of this series, where we'll cover the Administration Service and its crucial role in extending Configuration Manager's capabilities.
Administration Service - General
The Administration Service is an essential component that provides API interoperability access over HTTPS. It is based on the Open Data (OData) v4 protocol, which enables seamless integration with other systems and facilitates automation tasks.
Administration Service – Prerequisites (History)
To utilize the Administration Service, there are a few prerequisites to consider:
In versions 2006 and earlier, you need to enable the Web Server (IIS) role on your Windows server. However, starting from version 2010, this role is no longer required.
In version 2107 and later, the SMS Provider requires .NET version 4.6.2, with version 4.8 being recommended. In versions 2103 and earlier, the role requires .NET 4.5 or later.
Secure HTTPS communication is essential, so you may need to enable and configure a trusted certificate for secure communication (HTTPS/eHTTP).
To access the Administration Service, your user account needs to have administrative privileges in Configuration Manager. If you plan to use the Administration Service via a cloud management gateway, you'll need a synchronized account in Azure Active Directory (Hybrid-Identity).
Please note that the Administration Service does not support proxy servers.
How to set up the admin service - Configuration Manager | Microsoft Learn
Administration Service – Calling REST Methods
The beauty of REST is its language-agnostic nature. Whether you prefer PowerShell, Python, C#, or any other language capable of sending web requests, you can interact with the Administration Service. The communication transport in this case is HTTPS, in contrast to WMI or PowerShell, which use WMI-RPC.
When calling REST methods, we rely on built-in HTTP methods such as GET, POST, PATCH, PUT, and DELETE. You can refer to the detailed list of HTTP request methods available on the Mozilla Developer Network (MDN) website (HTTP request methods - HTTP | MDN (mozilla.org)).
To construct the request, you'll need:
- A Uniform Resource Identifier (URI) that points to the web service hosting the Administration Service.
- A version or route to specify the desired API version.
- The resource or entity you wish to read from or write to.
- Optional query parameters to filter the results or execute specific methods.
Administration Service – URI Routes
The Administration Service in Microsoft Configuration Manager provides two routes:
- Administration Service > WMI > SQL:
- Example URI: `https://<SMSProviderFQDN>/AdminService/wmi/<ClassName>`
- This route allows direct interaction with the SQL backend through WMI, enabling additional tasks and flexibility.
- Administration Service > OData/SQL:
- Example URI: `https://<SMSProviderFQDN>/AdminService/v1.0/<Entity>`
- This route, based on OData v4, is used for new implementations, such as installing or uninstalling applications from the Microsoft Endpoint Manager Portal (Intune) in conjunction with the Tenant Attach feature.
Please note that the administration service class names are case-sensitive.
Administration Service – v1.0 OData
The v1.0 OData route plays a crucial role in new implementations and supports interactions with the Administration Service. One notable use case is triggering blade actions, which initiate specific tasks.
- Admin triggers a blade action.
- The CMGatewayNotificationWorker is notified about the request.
- The request is forwarded to the Administration Service.
- The Administration Service calls SQL views to process the request.
- The result is returned via OData and forwarded to the CMGatewayNotificationWorker, which uploads it to the MEM-Portal.
- The admin can view the result in the portal.
You can access the metadata of the v1.0 OData route through a web browser using the following URL: `https://<SMSProvider.FQDN>/AdminService/v1.0/$metadata`.
To interact with the Administration Service, you can load the DLL `microsoft.configurationmanager.objectlibrary.dll` from the CMRestProvider installation directory. This DLL contains the definitions and corresponding SQL views for each entity.
Administration Service – v1.0 OData Navigation Properties
For some entities, there are additional navigation properties available. For instance, when requesting information about a device, you can retrieve the resource collection membership for that specific device using the navigation property.
Navigation Properties for the Entity Device:
A call against https://<SMSProv.FQDN>/AdminService/v1.0/Device will give us Properties of the SQL-View vSMS_CombinedDeviceResources of each ResourceID.
With the Navigation Property you can request the ResourceCollectionMembership for a specific Device
https://<SMSProv.FQDN>/AdminService/v1.0/Device(ResourceID)/ResourceCollectionMembership
Administration Service – v1.0 OData Functions/Actions
Entities in the Administration Service can also have functions and actions associated with them. Actions run specific tasks, while functions provide return types for action execution.
To initiate an action or function, you must send a POST request with the AdminService prefix and the action/function name.
Administration Service – WMI
While the v1.0 OData route is designed for new functionalities, you can still use the existing WMI SMS Provider to achieve additional tasks. Starting with MECM 2111, it is possible to define an odata.type with the request body, which is necessary when a method references a specific data type.
Administration Service – WMI Static Method True
When calling a static WMI method, you need to navigate to the class and execute the method on the class level.
https://<SMSProv.FQDN>/AdminService/wmi/[ClassName].[Method]
Administration Service – WMI Static Method False
For non-static WMI methods, you need to call the instance of a class, followed by the AdminService prefix and the method name.
https://<SMSProv.FQDN>/AdminService/wmi/[ClassName](Instance)/AdminService.[Method]
Administration Service – WMI New Instance
Creating new instances requires sending a POST request to the WMI class with the required properties. It is also possible to use the AdminService for referring to property classes like SMS_MachineSettings and SMS_MachineVariable, which can have references.
Administration Service – WMI OData.Type
With MECM 2111, you can define an OData.Type in your request body. This is necessary for scenarios where WMI methods require a specific type to be executed. One example is adding a collection membership rule for the SMS_Collection class.
In such a Scenario it is necessary to provide the Type.
[PropertyName] = @{“odata.type”=“#AdminService.[ReferenceClass]”;
[PropName] = [PropValue]…
Administration Service – Reference Assemblies
The main idea behind a REST-API is that you can use any tool or language which is capable of sending a WebRequest to get/set data (Powershell, C#, Python, Perl,…)
With the Microsoft Configuration Manager Console installed, you can load the following Assemblies to interact with the Administration Service:
AdminUI.WqlQueryEngine.dll
AdminUI.ODataQueryEngine.dll
microsoft.configurationmanager.cloudbase.dll
AdminUI.WqlQueryEngine.dll
This Reference will give us a Connection to the WMI/WQL-Manager of the SMS Provider
$WMIConnectionManager = [Microsoft.ConfigurationManagement.ManagementProvider.WqlQueryEngine.WqlConnectionManager]::new()
[void]$WMIConnectionManager.Connect($CMProviderFQDN)
AdminUI.ODataQueryEngine.dll
This Reference will give us a Connection to the Administration Service
$ODataConnectionManager = [Microsoft.ConfigurationManagement.ManagementProvider.ODataQueryEngine.ODataConnectionManager]::new($WMIConnectionManager.NamedValueDictionary,$WMIConnectionManager)
[Void]$ODataConnectionManager.Connect($CMProviderFQDN)
Microsoft.Configurationmanager.Cloudbase.dll
This Reference is the Interface where we call the WebRequest Methods against the Administration Service:
Through this you can build your own Functions to start activities:
Using the ODataConnectionManager also takes care of the admin service communication for intranet scenarios, both HTTPS and Enhanced HTTP.
Administration Service – Logging
Activities performed against the Administration Service are logged in the AdminService.Log file on your Site Server. It provides information about the requests and responses, including any HTTP error codes encountered.
Here we see an activity to an Entity where the Get-Method is not allowed (HTTP 405):
For detailed HTTP-Error-Code description have look at this Microsoft Article:
HTTP status code overview - Internet Information Services | Microsoft Docs
Conclusion:
In this blog post, we covered the important fundamentals of the Administration Service within the context of Microsoft Configuration Manager and provided additional information. We explored the various routes, calling REST methods, and interacting with the service through WMI. By understanding these concepts, you can leverage the power of the Administration Service to extend the capabilities of Configuration Manager in your code projects. We hope this blog series has been helpful in enhancing your understanding and guiding you in future endeavors.
Thank you for following along, and we wish you success in your automation journey with Microsoft Configuration Manager!
Disclaimer
The sample scripts are not supported under any Microsoft standard support program or service. The sample scripts are provided AS IS without warranty of any kind. Microsoft further disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the sample scripts and documentation remains with you. In no event shall Microsoft, its authors, or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages.