Microsoft Intune

Overview

Microsoft Intune is a cloud-based service that helps you manage access for users and devices, including mobile devices, desktop computers, and virtual endpoints. It streamlines the management of apps and devices across your organization.

D3 SOAR is providing REST operations to function with Microsoft Intune.

Microsoft Intune is available for use in:

D3 SOAR	V14.5.21.0+
Category	Endpoint Protection
Deployment Options	Option II, Option IV

Connection

To connect to Microsoft Intune from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Default
Tenant ID	The tenant ID to authenticate the API connection.	f6I-*-*-MgP
Grant Type	The grant type to authenticate the API connection.	Client Credentials
Grant Type: Client Credentials
Client ID	The client ID to authenticate the API connection.	Waz***WWv
Client Secret	The client secret to authenticate the API connection.	EiQ***Sv4
API Version	The version of the API to use for the connection.	v1.0
Grant Type: Authorization Code
Client ID	The client ID to authenticate the API connection.	WC********JWv
Client Secret	The client secret to authenticate the API connection.	EiJQ******aSv4
Authorization Code	The authorization code for OAuth2.0 authentication. Click the "Get Authorization" button on the Connection page to automatically generate an authorization code.	ucF********IuM
Callback URL	The callback URL is used for OAuth2.0 with the grant type of authorization code. Add this URL to your app's Redirect URIs. In the Azure portal, navigate to Microsoft Entra ID Protection > App Registrations > Your App > Authentication.	https://***/Auth2Callback.aspx
Refresh Token	The refresh token for authentication with the grant type of authorization code. Click the "Get Refresh Token" button on the Connection page to automatically generate a refresh token. This parameter is read-only and Auto-generated.	MxN********hp0
API Version	The version of the API to use for the connection.	v1.0

Reader Note

The Microsoft Graph API for Intune requires an active Intune license for the tenant.

Permission Requirements

Each endpoint in the Microsoft Intune API requires a certain permission scope. The following are required scopes for the commands in this integration:

Reader Note

Application permissions are the permissions required if the connection was authenticated using the Client Credentials grant type.
Delegated permissions are the permissions required if the connection was authenticated using the Authorization Code grant type.

Command	Application Permissions	Delegated Permissions
Get Managed Device	DeviceManagementManagedDevices.Read.All, DeviceManagementManagedDevices.ReadWrite.All	DeviceManagementManagedDevices.Read.All, DeviceManagementManagedDevices.ReadWrite.All
List Managed Devices	DeviceManagementManagedDevices.Read.All, DeviceManagementManagedDevices.ReadWrite.All	DeviceManagementManagedDevices.Read.All, DeviceManagementManagedDevices.ReadWrite.All
Test Connection	N/A	N/A

Configuring Microsoft Intune to Work with D3 SOAR

Log in to the Azure Portal (https://portal.azure.com/).
Navigate to the top search bar, then search and select App registrations.
If you already have created apps, you can use one of them. Skip to step 5 to obtain the Client ID & Tenant ID. If you do not have an app, click + New registration to create one.
Register the application.
1. Enter an application Name.
2. For Supported account types, select Accounts in this organizational directory only (<Your Directory Name> only - Single tenant).
3. Click Register.
In the App Overview tab, copy and save the Application(client) ID and Directory(tenant) ID. They will be required to build the integration connection in D3 SOAR. Navigate to Client credentials, then click Add a certificate or secret.
Click + New Client Secret. Enter a Description for the client secret, and select a client secret expiry period using the Expires dropdown menu. Click Add.
Note: The client ID will not be able to access the API resources after the client secret expires. You must renew the client secret to keep the client ID active.
Copy and save the Secret Value. It will be required to build the integration connection in D3 SOAR. Note: The created Client Secret can only be viewed once. Store it in a secure location before leaving the page.
Configure the Redirect URIs. Click Authentication on the left navigation menu, then Add URI. Input the D3 SOAR redirect URI (see step 6 of Configuring D3 SOAR to Work with Microsoft Intune). Click Save.
Configure the API permissions. Click API permissions on the left navigation menu, then + Add a permission. Select Microsoft Graph, then search and select the required Delegated permissions and Application permissions. After selecting the required permissions, click Add permissions. See Permission Requirements for the required permissions for each command in this integration.

Reader Note

Delegated permissions are the permissions required if the connection was authenticated using the Authorization Code grant type.
Application permissions are the permissions required if the connection was authenticated using the Client Credentials grant type.

Some permissions may need to be granted admin consent for your directory (d3uat in the sample screenshot) to use. Ensure Grant admin consent for <Your Directory> is checked.

You may see Not granted for <Your Directory> in the status column. Those are the ungranted permissions you want to use. After successfully granting permissions, a green checkmark will appear under the permission status column for the corresponding permissions. If your login account does not have admin privileges, ask your admin to grant consent.

Configuring D3 SOAR to Work with Microsoft Intune

Log in to D3 SOAR.
Find the Microsoft Intune integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Microsoft Intune in the search box to find the integration, then click it to select it.
4. Click + New Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Microsoft Intune.
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add your desired description for the connection.
6. Configure User Permissions: Defines which users have access to the connection.
7. Active: Check the tick box to ensure the connection is available for use.
8. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  Grant Type: Client Credentials
  1. Input the Tenant ID. See step 5 of Configuring Microsoft Intune to Work with D3 SOAR.
  2. Input the Client ID. See step 5 of Configuring Microsoft Intune to Work with D3 SOAR.
  3. Input the Client Secret. See step 6 of Configuring Microsoft Intune to Work with D3 SOAR.
  4. Input the API Version. The default value is v1.0.
  
  Grant Type: Authorization Code
  1. Input the Tenant ID. See step 5 of Configuring Microsoft Intune to Work with D3 SOAR.
  2. Input the Client ID. See step 5 of Configuring Microsoft Intune to Work with D3 SOAR.
  3. Input the Client Secret. See step 6 of Configuring Microsoft Intune to Work with D3 SOAR.
  4. Click Get Authorization. You will be redirected to Azure and asked to log in with your credentials. Note: You must be logged in to an admin account to grant approval. If you use a non-admin account, you will only be able to send a request for approval to your admin.
  5. Click Get Refresh Token. The refresh token will be automatically generated and filled into the field. No further action is required.
  6. Copy and paste the Callback URL into the created app's authentication page on Azure. See step 8 of Configuring Microsoft Intune to Work with D3 SOAR.
  7. Input the API Version. The default value is v1.0. Note: Some commands require the beta version of the API.
9. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
  To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
10. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
Test the connection.
1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

Microsoft Intune includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Microsoft Intune API, please refer to the Microsoft Intune API reference.

Reader Note

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Microsoft Intune to Work with D3 SOAR for details.

Get Managed Device

Returns properties and relationships of the specified managed devices.

Reader Note

The parameter Mange Device IDs is required to run this command.

Run the List Managed Devices command to obtain Manage Device IDs.

Input

Input Parameter	Required /Optional	Description	Example
Manage Device IDs	Required	The IDs of the managed devices to return corresponding properties and relationships. Manage Device IDs can be obtained using the List Managed Devices command.	["***************************************"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "@odata.context": "https://graph.microsoft.com/v*.*/***",
        "id": "***************************************",
        "userId": "***************************************",
        "deviceName": "***************************************",
        "managedDeviceOwnerType": "personal",
        "enrolledDateTime": "2021-10-12T20:16:31.7922176Z",
        "lastSyncDateTime": "2021-10-21T14:34:03.7051633Z",
        "operatingSystem": "Windows",
        "complianceState": "compliant",
        "jailBroken": "Unknown",
        "managementAgent": "mdm",
        "osVersion": "***.***.***.***",
        "easActivated": true,
        "easDeviceId": "***************************************",
        "easActivationDateTime": "2021-10-12T20:19:09.7694187Z",
        "azureADRegistered": true,
        "deviceEnrollmentType": "windowsAutoEnrollment",
        "activationLockBypassCode": null,
        "emailAddress": "*****@*****.com",
        "azureADDeviceId": "***************************************",
        "deviceRegistrationState": "registered",
        "deviceCategoryDisplayName": "",
        "isSupervised": false,
        "exchangeLastSuccessfulSyncDateTime": "0001-01-01T00:00:00Z",
        "exchangeAccessState": "none",
        "exchangeAccessStateReason": "none",
        "remoteAssistanceSessionUrl": "",
        "remoteAssistanceSessionErrorDetails": "",
        "isEncrypted": false,
        "userPrincipalName": "*****@*****.com",
        "model": "OptiPlex 7080",
        "manufacturer": "Dell Inc.",
        "imei": null,
        "complianceGracePeriodExpirationDateTime": "2021-10-12T20:16:37.7194Z",
        "serialNumber": "*****",
        "phoneNumber": null,
        "androidSecurityPatchLevel": null,
        "userDisplayName": "sysint",
        "configurationManagerClientEnabledFeatures": null,
        "wiFiMacAddress": null,
        "deviceHealthAttestationState": null,
        "subscriberCarrier": "",
        "meid": null,
        "totalStorageSpaceInBytes": 509093085184,
        "freeStorageSpaceInBytes": 353625964544,
        "managedDeviceName": "sysint_Windows_10/12/2021_8:16 PM",
        "partnerReportedThreatState": "unknown",
        "iccid": "",
        "udid": "",
        "notes": null,
        "ethernetMacAddress": "***************************************",
        "physicalMemoryInBytes": 0,
        "deviceActionResults": []
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
        "@odata.context": "https://graph.microsoft.com/v*.*/***",
        "id": "***************************************",
        "userId": "***************************************",
        "deviceName": "***************************************",
        "managedDeviceOwnerType": "personal",
        "enrolledDateTime": "2021-10-12T20:16:31.7922176Z",
        "lastSyncDateTime": "2021-10-21T14:34:03.7051633Z",
        "operatingSystem": "Windows",
        "complianceState": "compliant",
        "jailBroken": "Unknown",
        "managementAgent": "mdm",
        "osVersion": "***.***.***.***",
        "easActivated": true,
        "easDeviceId": "***************************************",
        "easActivationDateTime": "2021-10-12T20:19:09.7694187Z",
        "azureADRegistered": true,
        "deviceEnrollmentType": "windowsAutoEnrollment",
        "activationLockBypassCode": null,
        "emailAddress": "*****@*****.com",
        "azureADDeviceId": "***************************************",
        "deviceRegistrationState": "registered",
        "deviceCategoryDisplayName": "",
        "isSupervised": false,
        "exchangeLastSuccessfulSyncDateTime": "0001-01-01T00:00:00Z",
        "exchangeAccessState": "none",
        "exchangeAccessStateReason": "none",
        "remoteAssistanceSessionUrl": "",
        "remoteAssistanceSessionErrorDetails": "",
        "isEncrypted": false,
        "userPrincipalName": "*****@*****.com",
        "model": "OptiPlex 7080",
        "manufacturer": "Dell Inc.",
        "imei": null,
        "complianceGracePeriodExpirationDateTime": "2021-10-12T20:16:37.7194Z",
        "serialNumber": "*****",
        "phoneNumber": null,
        "androidSecurityPatchLevel": null,
        "userDisplayName": "sysint",
        "configurationManagerClientEnabledFeatures": null,
        "wiFiMacAddress": null,
        "deviceHealthAttestationState": null,
        "subscriberCarrier": "",
        "meid": null,
        "totalStorageSpaceInBytes": 509093085184,
        "freeStorageSpaceInBytes": 353625964544,
        "managedDeviceName": "sysint_Windows_10/12/2021_8:16 PM",
        "partnerReportedThreatState": "unknown",
        "iccid": "",
        "udid": "",
        "notes": null,
        "ethernetMacAddress": "***************************************",
        "physicalMemoryInBytes": 0,
        "deviceActionResults": []
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "managedDeviceIds": [
        "***************************************"
    ],
    "azureADDeviceIds": [
        "***************************************"
    ],
    "deviceNames": [
        "***************************************"
    ],
    "userPrincipalNames": [
        "*****@*****.com"
    ],
    "easDeviceIds": [
        "***************************************"
    ],
    "serialNumbers": [
        "*****"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

@ODATA.CONTEXT	ID	USERID	DEVICENAME	MANAGEDDEVICEOWNERTYPE	ENROLLEDDATETIME	LASTSYNCDATETIME	OPERATINGSYSTEM	COMPLIANCESTATE	JAILBROKEN	MANAGEMENTAGENT	OSVERSION	EASACTIVATED	EASDEVICEID	EASACTIVATIONDATETIME	AZUREADREGISTERED	DEVICEENROLLMENTTYPE	ACTIVATIONLOCKBYPASSCODE	EMAILADDRESS	AZUREADDEVICEID	DEVICEREGISTRATIONSTATE	DEVICECATEGORYDISPLAYNAME	ISSUPERVISED	EXCHANGELASTSUCCESSFULSYNCDATETIME	EXCHANGEACCESSSTATE	EXCHANGEACCESSSTATEREASON	REMOTEASSISTANCESESSIONURL	REMOTEASSISTANCESESSIONERRORDETAILS	ISENCRYPTED	USERPRINCIPALNAME	MODEL	MANUFACTURER	IMEI	COMPLIANCEGRACEPERIODEXPIRATIONDATETIME	SERIALNUMBER	PHONENUMBER	ANDROIDSECURITYPATCHLEVEL	USERDISPLAYNAME	CONFIGURATIONMANAGERCLIENTENABLEDFEATURES	WIFIMACADDRESS	DEVICEHEALTHATTESTATIONSTATE	SUBSCRIBERCARRIER	MEID	TOTALSTORAGESPACEINBYTES	FREESTORAGESPACEINBYTES	MANAGEDDEVICENAME	PARTNERREPORTEDTHREATSTATE	ICCID	UDID	NOTES	ETHERNETMACADDRESS	PHYSICALMEMORYINBYTES	DEVICEACTIONRESULTS
https://graph.microsoft.com/v./***	***************************************	***************************************	***************************************	personal	2021-10-12T20:16:31.7922176Z	2021-10-21T14:34:03.7051633Z	Windows	compliant	Unknown	mdm	*...*	True	***************************************	2021-10-12T20:19:09.7694187Z	True	windowsAutoEnrollment	None	***@***.com	***************************************	registered		False	0001-01-01T00:00:00Z	none	none			False	***@***.com	OptiPlex 7080	Dell Inc.	None	2021-10-12T20:16:37.7194Z	*****	None	None	sysint	None	None	None		None	509093085184	353625964544	sysint_Windows_10/12/2021_8:16 PM	unknown			None	***************************************	0	[]

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Managed Device failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Intune portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Manage Device IDs Not Found.

Error Sample Data

Get Managed Device failed.

Status Code: 404.

Message: Manage Device IDs Not Found.

List Managed Devices

Lists properties and relationships of the specified managed devices.

Input

Input Parameter

Required /Optional

Description

Example

Filter

Optional

The filter expression to filter results.

Note:

Syntax: The most common expression is <property> <operator> <value>.

Operators: See Use the $filter query parameter to filter a collection of objects - Microsoft Graph for more information about the available operators to use in the filter expression.

The and operator performs a logical conjunction on two or more statements. The or operator is a conditional operator used between statements to test the validity of each statement.

Different operators are supported for different properties, please check the valid operators to use.

startswith(deviceName, 'D')

Top

Optional

The maximum number of results to return. If this parameter is not defined, all managed devices will be returned.

2

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "@odata.context": "https://graph.microsoft.com/v*.*/***",
        "@odata.count": 1,
        "value": [
            {
                "id": "***************************************",
                "userId": "***************************************",
                "deviceName": "***************************************",
                "managedDeviceOwnerType": "personal",
                "enrolledDateTime": "2021-10-12T20:16:31Z",
                "lastSyncDateTime": "2021-10-21T14:34:03Z",
                "operatingSystem": "Windows",
                "complianceState": "compliant",
                "jailBroken": "Unknown",
                "managementAgent": "mdm",
                "osVersion": "***.***.***.***",
                "easActivated": true,
                "easDeviceId": "***************************************",
                "easActivationDateTime": "0001-01-01T00:00:00Z",
                "azureADRegistered": true,
                "deviceEnrollmentType": "windowsAutoEnrollment",
                "activationLockBypassCode": null,
                "emailAddress": "*****@*****.com",
                "azureADDeviceId": "***************************************",
                "deviceRegistrationState": "registered",
                "deviceCategoryDisplayName": "Unknown",
                "isSupervised": false,
                "exchangeLastSuccessfulSyncDateTime": "0001-01-01T00:00:00Z",
                "exchangeAccessState": "none",
                "exchangeAccessStateReason": "none",
                "remoteAssistanceSessionUrl": null,
                "remoteAssistanceSessionErrorDetails": null,
                "isEncrypted": false,
                "userPrincipalName": "*****@*****.com",
                "model": "OptiPlex 7080",
                "manufacturer": "Dell Inc.",
                "imei": "",
                "complianceGracePeriodExpirationDateTime": "2021-10-12T20:16:37Z",
                "serialNumber": "*****",
                "phoneNumber": "",
                "androidSecurityPatchLevel": "",
                "userDisplayName": "sysint",
                "configurationManagerClientEnabledFeatures": null,
                "wiFiMacAddress": "",
                "deviceHealthAttestationState": null,
                "subscriberCarrier": "",
                "meid": "",
                "totalStorageSpaceInBytes": 509093085184,
                "freeStorageSpaceInBytes": 353625964544,
                "managedDeviceName": "sysint_Windows_10/12/2021_8:16 PM",
                "partnerReportedThreatState": "unknown",
                "iccid": null,
                "udid": null,
                "notes": null,
                "ethernetMacAddress": null,
                "physicalMemoryInBytes": 0,
                "deviceActionResults": []
            }
        ]
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
        "id": "***************************************",
        "userId": "***************************************",
        "deviceName": "***************************************",
        "managedDeviceOwnerType": "personal",
        "enrolledDateTime": "2021-10-12T20:16:31Z",
        "lastSyncDateTime": "2021-10-21T14:34:03Z",
        "operatingSystem": "Windows",
        "complianceState": "compliant",
        "jailBroken": "Unknown",
        "managementAgent": "mdm",
        "osVersion": "***.***.***.***",
        "easActivated": true,
        "easDeviceId": "***************************************",
        "easActivationDateTime": "0001-01-01T00:00:00Z",
        "azureADRegistered": true,
        "deviceEnrollmentType": "windowsAutoEnrollment",
        "activationLockBypassCode": null,
        "emailAddress": "*****@*****.com",
        "azureADDeviceId": "***************************************",
        "deviceRegistrationState": "registered",
        "deviceCategoryDisplayName": "Unknown",
        "isSupervised": false,
        "exchangeLastSuccessfulSyncDateTime": "0001-01-01T00:00:00Z",
        "exchangeAccessState": "none",
        "exchangeAccessStateReason": "none",
        "remoteAssistanceSessionUrl": null,
        "remoteAssistanceSessionErrorDetails": null,
        "isEncrypted": false,
        "userPrincipalName": "*****@*****.com",
        "model": "OptiPlex 7080",
        "manufacturer": "Dell Inc.",
        "imei": "",
        "complianceGracePeriodExpirationDateTime": "2021-10-12T20:16:37Z",
        "serialNumber": "*****",
        "phoneNumber": "",
        "androidSecurityPatchLevel": "",
        "userDisplayName": "sysint",
        "configurationManagerClientEnabledFeatures": null,
        "wiFiMacAddress": "",
        "deviceHealthAttestationState": null,
        "subscriberCarrier": "",
        "meid": "",
        "totalStorageSpaceInBytes": 509093085184,
        "freeStorageSpaceInBytes": 353625964544,
        "managedDeviceName": "sysint_Windows_10/12/2021_8:16 PM",
        "partnerReportedThreatState": "unknown",
        "iccid": null,
        "udid": null,
        "notes": null,
        "ethernetMacAddress": null,
        "physicalMemoryInBytes": 0,
        "deviceActionResults": []
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "managedDeviceIds": [
        "***************************************"
    ],
    "azureADDeviceIds": [
        "***************************************"
    ],
    "deviceNames": [
        "***************************************"
    ],
    "userPrincipalNames": [
        "*****@*****.com"
    ],
    "easDeviceIds": [
        "***************************************"
    ],
    "serialNumbers": [
        "*****"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

ID	USERID	DEVICENAME	MANAGEDDEVICEOWNERTYPE	ENROLLEDDATETIME	LASTSYNCDATETIME	OPERATINGSYSTEM	COMPLIANCESTATE	JAILBROKEN	MANAGEMENTAGENT	OSVERSION	EASACTIVATED	EASDEVICEID	EASACTIVATIONDATETIME	AZUREADREGISTERED	DEVICEENROLLMENTTYPE	ACTIVATIONLOCKBYPASSCODE	EMAILADDRESS	AZUREADDEVICEID	DEVICEREGISTRATIONSTATE	DEVICECATEGORYDISPLAYNAME	ISSUPERVISED	EXCHANGELASTSUCCESSFULSYNCDATETIME	EXCHANGEACCESSSTATE	EXCHANGEACCESSSTATEREASON	REMOTEASSISTANCESESSIONURL	REMOTEASSISTANCESESSIONERRORDETAILS	ISENCRYPTED	USERPRINCIPALNAME	MODEL	MANUFACTURER	IMEI	COMPLIANCEGRACEPERIODEXPIRATIONDATETIME	SERIALNUMBER	PHONENUMBER	ANDROIDSECURITYPATCHLEVEL	USERDISPLAYNAME	CONFIGURATIONMANAGERCLIENTENABLEDFEATURES	WIFIMACADDRESS	DEVICEHEALTHATTESTATIONSTATE	SUBSCRIBERCARRIER	MEID	TOTALSTORAGESPACEINBYTES	FREESTORAGESPACEINBYTES	MANAGEDDEVICENAME	PARTNERREPORTEDTHREATSTATE	ICCID	UDID	NOTES	ETHERNETMACADDRESS	PHYSICALMEMORYINBYTES	DEVICEACTIONRESULTS
***************************************	***************************************	***************************************	personal	2021-10-12T20:16:31Z	2021-10-21T14:34:03Z	Windows	compliant	Unknown	mdm	*...*	True	***************************************	0001-01-01T00:00:00Z	True	windowsAutoEnrollment	None	***@***.com	***************************************	registered	Unknown	False	0001-01-01T00:00:00Z	none	none	None	None	False	***@***.com	OptiPlex 7080	Dell Inc.		2021-10-12T20:16:37Z	*****			sysint	None		None			509093085184	353625964544	sysint_Windows_10/12/2021_8:16 PM	unknown	None	None	None	None	0	[]

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Managed Devices failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Intune portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid filter clause.

Error Sample Data

List Managed Devices failed.

Status Code: 400.

Message: Invalid filter clause.

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

SAMPLE DATA

CODE

Successful

Error Handling

If the Return Data is partially successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the responses from the third-party API calls including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Intune portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Application with identifier 'xxx' was not found in the directory 'xxx'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 403.

Message: Application with identifier 'xxx' was not found in the directory 'xxx'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant.