> For the complete documentation index, see [llms.txt](https://docs.onum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onum.com/listeners/listener-integrations/pull-data-from-http-endpoints/pull-data-from-microsoft-apis/pull-data-from-the-microsoft-graph-api/message-traces.md).

# Message traces

## Overview

Get a list of message traces through the [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/) using the **HTTP Pull** Listener.

## HTTP Pull Listener configuration

In Falcon Onum, go to the **Listeners** area and click **New Listener > HTTP Pull**. Give a name to your new Listener and enter the following data:

### Parameters

Add the following parameter:

* **Name** - `tenant_id`
* **Value** - Enter your Microsoft tenant ID.

### Secrets

You must define these credentials in Onum:

* `client_id` will reference your Microsoft Graph client ID.
* `client_secret` will reference your Microsoft Graph client secret.

To do it, click **Add element** and enter a **Name** for the secret (in this case, `client_id`). Then, click the **Value** field and select **New secret** to create a new one:

* Give the secret a **Name**.
* Turn off the **Expiration date** option.
* Click **Add new value** and paste the secret corresponding to the value.
* Click **Save**.

You can now select the secret you just created in the **Value** field list. Repeat the process for the `client_secret`.

{% hint style="info" %}
Learn more about secrets in Onum in [this article](/settings/organization-settings/secrets-management.md).
{% endhint %}

### Setup

After entering the required parameters and secrets, you can choose to manually enter the rest of configuration fields, or simply paste the given YAML:

{% tabs %}
{% tab title="Config as YAML" %}
Toggle **ON** the **Config as YAML** option to enable a free text field where you can paste the following YAML:

```yaml
withTemporalWindow: true
temporalWindow:
  duration: 5m
  offset: 5m
  tz: UTC
  format: RFC3339
withAuthentication: true
authentication:
  type: token
  token:
    request:
      method: POST
      url: https://login.microsoftonline.com/${parameters.tenant_id}/oauth2/token
      headers:
        - name: Content-Type
          value: application/x-www-form-urlencoded
        - name: Accept
          value: application/json
      bodyType: urlEncoded
      bodyParams:
        - name: client_id
          value: '${secrets.client_id}'
        - name: client_secret
          value: '${secrets.client_secret}'
        - name: resource
          value: https://graph.microsoft.com
        - name: grant_type
          value: client_credentials
    tokenPath: ".access_token"
    authInjection:
      in: header
      name: Authorization
      prefix: 'Bearer '
      suffix: ''
withEnumerationPhase: false
collectionPhase:
  paginationType: "responseBodyLink"
  responseBodyLinkSelector: .["@odata.nextLink"]
  request:
    responseType: json
    method: "GET"
    url: "https://graph.microsoft.com/v1.0/admin/exchange/tracing/messageTraces"
    headers:
      - name: Accept
        value: "application/json"
      - name: Content-Type
        value: "application/json"
    queryParams: 
      - name: $filter
        value: receivedDateTime ge ${temporalWindow.from} and receivedDateTime le ${temporalWindow.to}
      - name: $top
        value: 5000
  output:
    select: ".value"
    map: "."
    outputMode: "element"
```

{% endtab %}

{% tab title="Manually configure" %}
**Temporal Window**

Toggle **ON** to add a temporal window for events. This repeatedly shifts the time window over which data is collected.

* **Duration** - `5m`
* **Offset** - `5m`
* **Format** - `RFC3339`

**Authentication**

Toggle **ON** and configure these parameters:

* **Type**<mark style="color:$primary;">**\***</mark> - `Token`

**Token Retrieve Based Authentication**

* **Request**
  * **Method**<mark style="color:$primary;">**\***</mark> - `POST`
  * **URL**<mark style="color:$primary;">**\***</mark> - `https://login.microsoftonline.com/${parameters.tenant_id}/oauth2/v2.0/token`
* **Headers**
  * **Name** - `Content-Type`
  * **Value** - `application/x-www-form-urlencoded`
  * **Name** - `Accept`
  * **Value** - `application/json`
* **Body Type**<mark style="color:$primary;">**\***</mark> - `URLEncoded`
* **Body Params**
  * **Name** - `client_id`
  * **Value** - `${secrets.client_id}`
  * **Name** - `client_secret`
  * **Value** - `${secrets.client_secret}`
  * **Name** - `resource`
  * **Value** - `https://graph.microsoft.com`
  * **Name** - `grant_type`
  * **Value** - `client_credentials`
* **Token path**<mark style="color:$primary;">**\***</mark> - `.access_token`
* **Auth Injection**
  * **In**<mark style="color:$primary;">**\***</mark> - `Header`
  * **Name**<mark style="color:$primary;">**\***</mark> - `Authorization`
  * **Prefix** - `'Bearer '`
  * **Suffix** - `''`

**Collection Phase**

* **Pagination Type**<mark style="color:red;">**\***</mark> - `Next Link at Response Body`
* **Selector**<mark style="color:$primary;">**\***</mark> - `.["@odata.nextLink"]`

**Request**

* **Response Type**<mark style="color:$primary;">**\***</mark> - `JSON`
* **Method**<mark style="color:$primary;">**\***</mark> - `GET`
* **URL**<mark style="color:$primary;">**\***</mark> - `https://graph.microsoft.com/v1.0/admin/exchange/tracing/messageTraces`

**Headers**

* **Name** - `Accept`
* **Value** - `application/json`
* **Name** - `Content-Type`
* **Value** - `application/json`

**Query Params**

* **Name** - `$filter`
* **Value** - `receivedDateTime ge ${temporalWindow.from} and receivedDateTime le ${temporalWindow.to}`
* **Name** - `$top`
* **Value** - `5000`

**Output**

* **Select**<mark style="color:$primary;">**\***</mark> - `.value`
* **Map** - `.`
* **Output Mode**<mark style="color:$primary;">**\***</mark> - `element`
  {% endtab %}
  {% endtabs %}

When you're done, click **Create labels** to move on to the next step and define the required [Labels](https://app.gitbook.com/o/9sm794iTBacZSmhxRER6/s/kxZeV4nlXcIAjMGZxzLI/the-workspace/listeners/labels) if needed.