# onDetails

## Summary

**optional** `function onDetails(lookupObject, options, callback)`

| **Parameters** | Description                                                                                       |
| -------------- | ------------------------------------------------------------------------------------------------- |
| lookupObject   | An object containing the lookup object for which the `onDetails` request is made                  |
| options        | An options object with key value pairs representing the requesting user's options and their value |
| callback       | A Node.js style callback which should return the updated `data` property of the `lookupObject`    |

If implemented, the `onDetails` method is used to add additional details and summary tag information to a lookup result. This method is called anytime a user clicks on a summary block to expand it and view details. The `onDetails` hook is used to make integrations more efficient by only querying for an expanded set of details information when a user clicks to view the details. It should be used anytime the details information requires an "expensive" lookup.

The `onDetails` method should return a new `data` object made up of a `details` object and a `summary` tag array via the `callback`.

## Parameters

The following is an explanation of the `onDetails` parameters.

### lookupObject

`function onDetails(`**`lookupObject`**`, options, callback)`

The `lookupObject` parameter is an object containing the previously returned lookup result for this entity. The object contains the entity, and data properties of the previous object.  The `lookupObject` has the following structure:

{% code title="lookupObject" %}

```javascript
{
    entity: {object}
    displayValue: {string},
    isVolatile: {boolean},
    isCached: {boolean},
    data: {
        summary: {Array},
        details: {Object}
    }
 }
```

{% endcode %}

#### **entity**

The entity object provides information about the entity for which details are being requested. Note that this [entity object](https://app.gitbook.com/s/-Lh_cZ5hPHbBZ3JwBZFU/build-an-integration/main/main-module.md/#entity_object) is the same entity object passed into the `doLookup` method as part of that methods `entities` array.

#### **displayValue**

A string value that is used to display the given entity. Note that by default this is equal to the `entity.value` property.

#### **isVolatile**

A boolean value indicating whether the lookupObject should be cached or not. If true, the lookup result will not be cached (even when the cached is enabled). If false, the lookup result will be cached. Note that this value defaults to `false` when not specified.

#### **isCached**

A boolean value indicating whether or not the lookupObject was served out of the cache.

#### **data.details**

The details object for this lookupObject.

#### **data.summary**

An array of strings that represent tags to be rendered in the summary block.

```javascript
// Example lookup object
{
    entity: {
        value: '56.2.3.2'
        type: 'IP',
        types: ['IP', 'IPv4'],
        isIPv4: true
        ...//additional entity object properties
    },
    displayValue: '56.2.3.2',
    isVolatile: false,
    isCached: false,
    data: {
        details: {
           severity: 90,
           confidence: 'high',
           source: 'Internet'
        }
        summary: ['malicious']
    }
 }
```

### options

`function onDetails(lookupObject,`` `**`options`**`, callback)`

The second parameter to the `onDetails` method is the `options` object which contains the values for the integration options as set in the integration `config.js`. Note that for per-user settings the value in the `options` object will reflect the value of the user requesting the lookup.

The key in the `options` object is the same value of the `key` property set in the integration `config.js` file.

{% code title="Options Object" %}

```javascript
{
    "apiKey": "lkasjdioajsdoij12lk3j1lk23j12",
    "lookupHashes": true,
    "throttleLookups": false
}
```

{% endcode %}

### callback(error, results)

`function onDetails(lookupObject, options,`` `**`callback`**`)`

The callback must be called before execution of the `onDetails` method completes. The callback accepts two parameters.

The first parameter is an error which can either be a string literal or an [error object](https://docs.polarity.io/integrations/build-an-integration/main/dolookup/error-objects). In the case of a string literal the returned string is displayed as an error in the notification window as well as tracked as an error in the integration.

{% hint style="info" %}
If you have no error to return you should return `null` for the `error` parameter.
{% endhint %}

The second parameter is the `data` parameter. The data parameter is the new `data` object for this lookupResult. The `data` parameter is an object that contains a `details` object and `summary` array.

```javascript
//callback parameters
callback(error, data);
```

## Examples

The following is a snippet of example code that shows how you can add additional summary tags to the `lookupObject` as well as set details to be returned to the overlay window.

Note that in this example, we are replacing any existing data in the `lookupObject.data.details` object. In addition, we are preserving the existing summary tags by pushing the new tags onto the existing summary array. If we replaced the `summary` array entirely then we would lose any existing tags for the entity.

```javascript
function onDetails(lookupObject, options, cb) {
    // Add additional summary tags
    lookupObject.data.summary.push("New Tag 1");
    lookupObject.data.summary.push("New Tag 2");

    // Add a new details object
    lookupObject.data.details = {
        // set your new details here
    };

    // Return the modified data object
    cb(null, lookupObject.data);
}
```

In cases where you don't want to replace the existing details information you can simply add a new property to the existing details and return that information. Note that in this example we are not modifying the summary tags and simply passing back the existing tags.

```javascript
function onDetails(lookupObject, options, cb) {
    // Add new information to the details without overriding any existing information
    lookupObject.data.details.newData = {
        newKey: "this is some new data"
    };

    // Return the modified data object
    cb(null, lookupObject.data);
}
```