# Salesforce

{% hint style="info" %}
The following documentation is for **Salesforce v2.0.3** *(BDK)*.
{% endhint %}

## Overview

Salesforce is the world's leading customer relationship management (CRM) platform for sales and marketing automation. This integration enables automated lead management, opportunity tracking, customer communication, and sales pipeline optimization. Enhance sales productivity and customer relationship management.

## Prerequisites

### 1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

* **Salesforce**

#### How to Add the Book(s)

1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on <kbd>**Install**</kbd> or <kbd>**Add Connection**</kbd> to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.

## Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

### Connect using Consumer Key, Consumer Secret and Domain

Connect to Salesforce using client credentials OAuth flow.

| Label           | Description                             | Type        |
| --------------- | --------------------------------------- | ----------- |
| Consumer Key    | The consumer key for authentication.    | `sensitive` |
| Consumer Secret | The consumer secret for authentication. | `sensitive` |
| Domain          | The domain of the Salesforce instance.  | `text`      |

### Connect using Username, Password, Security Token and Domain

Connects to a Salesforce instance using username, password, security token and domain.

| Label          | Description                            | Type        |
| -------------- | -------------------------------------- | ----------- |
| Username       | The username for authentication.       | `text`      |
| Password       | The password for authentication.       | `sensitive` |
| Security Token | The security token for authentication. | `sensitive` |
| Domain         | The domain of the Salesforce instance. | `text`      |

### Connect using Username, Password and Security Token

Connects to a Salesforce instance using username, password and security token.

| Label          | Description                            | Type        |
| -------------- | -------------------------------------- | ----------- |
| Username       | The username for authentication.       | `text`      |
| Password       | The password for authentication.       | `sensitive` |
| Security Token | The security token for authentication. | `sensitive` |

## Procedures

### to create a report in *salesforce*

Creates a report in Salesforce.

**Input Concepts**

| Concept                                    | Description                                                        | Type                            | Required | Default Value |
| ------------------------------------------ | ------------------------------------------------------------------ | ------------------------------- | -------- | ------------- |
| [`report`](#salesforce-create-report-body) | A CreateSalesforceReportBody to create a Report with in Salesforce | `salesforce create report body` | Yes      | (no default)  |

**Output Concepts**

| Concept  | Description                  | Type   |
| -------- | ---------------------------- | ------ |
| `answer` | The id of the created report | `text` |

**Examples**

Create a basic Salesforce Report

```generic
create a json
use the above as the type json
set the type json's "type" to "Opportunity"
set the type json's "label" to "Opportunity"
create a json
use the above as the metadata json
set the metadata json's "name" to "Example Report from BDK"
set the metadata json's "description" to "A report from BDK"
set the metadata json's "report_type" to the type json
create a json
use the above as the request json
set the request json's "report_metadata" to the metadata json
create the request json in salesforce
```

Create a Report with a filter

```generic
create a json
use the above as the type json
set the type json's "type" to "Opportunity"
set the type json's "label" to "Opportunity"
create a json
use the above as the filter
set the filter's "target" to "20000"
set the filter's "column" to "AMOUNT"
set the filter's "operator" to "greaterThan"
set the filter's "is_run_page_editable" to True
set the filter's "filter_type" to "fieldValue"
use the above filters as the filters
create a json
use the above as the metadata json
set the metadata json's "name" to "Example Report from BDK"
set the metadata json's "description" to "A report from BDK"
set the metadata json's "report_type" to the type json
set the metadata json's "report_filters" to the filters
create a json
use the above as the request json
set the request json's "report_metadata" to the metadata json
create the request json in salesforce
```

### to export a report as a *excel*

Exports a report as an Excel file.

**Input Concepts**

| Concept                        | Description                                   | Type                | Required | Default Value |
| ------------------------------ | --------------------------------------------- | ------------------- | -------- | ------------- |
| [`report`](#salesforce-report) | A SalesforceReport to export as an Excel file | `salesforce report` | Yes      | (no default)  |

**Output Concepts**

| Concept  | Description                     | Type   |
| -------- | ------------------------------- | ------ |
| `answer` | The Excel file as an IO object. | `file` |

**Examples**

```generic
retrieve reports from salesforce whose Name is "BOF Report"
use the first report as the record
export the record as an excel
```

### to export a report as a table

Exports a report as a Pyarrow Table.

**Input Concepts**

| Concept                        | Description                                     | Type                | Required | Default Value |
| ------------------------------ | ----------------------------------------------- | ------------------- | -------- | ------------- |
| [`report`](#salesforce-report) | A SalesforceReport to export as a Pyarrow Table | `salesforce report` | Yes      | (no default)  |

**Output Concepts**

| Concept  | Description                                | Type    |
| -------- | ------------------------------------------ | ------- |
| `answer` | The report represented as a Pyarrow Table. | `table` |

**Examples**

```generic
retrieve reports from salesforce whose Name is "BOF Report"
use the first report as the record
export the report as a table
```

### to retrieve some (reports) from *salesforce*

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Retrieves reports from Salesforce.

**Output Concepts**

| Concept                         | Description                            | Type                |
| ------------------------------- | -------------------------------------- | ------------------- |
| [`reports`](#salesforce-report) | The reports retrieved from Salesforce. | `salesforce report` |

**Examples**

Retrieve reports from Salesforce

```generic
retrieve reports from salesforce
```

Retrieve reports from Salesforce, filtering by name

```generic
retrieve reports from salesforce whose Name is "BOF Report"
```

### to send an email in *salesforce*

Sends an email in Salesforce.

**Input Concepts**

| Concept     | Description                 | Type   | Required | Default Value |
| ----------- | --------------------------- | ------ | -------- | ------------- |
| `receivers` | The receivers of the email. | `text` | Yes      | (no default)  |
| `subject`   | The subject of the email.   | `text` | Yes      | (no default)  |
| `body`      | The body of the email.      | `text` | No       | (no default)  |

**Examples**

Send an email in Salesforce

```generic
send an email in salesforce
    the receivers are "example1@kognitos.com","example2@kognitos.com"
    the subject is "Test Subject"
    the body is "Test Body"
```

## Concepts

### Salesforce create report body

Information sent to Salesforce to create a report.

| Field Name        | Description                 | Type   |
| ----------------- | --------------------------- | ------ |
| `report_metadata` | The metadata of the report. | `json` |

### Salesforce report

A Salesforce report, modeled as the Salesforce Object (SObject)and defined as a set of data that meets certain criteria, displayed in an organized way. Specified here: <https://developer.salesforce.com/docs/atlas.en-us.object\\_reference.meta/object\\_reference/sforce\\_api\\_objects\\_report.htm>

| Field Name             | Description                                                                                            | Type                 |
| ---------------------- | ------------------------------------------------------------------------------------------------------ | -------------------- |
| `id`                   | The ID of the report.                                                                                  | `text`               |
| `owner_id`             | The ID of the owner of the report.                                                                     | `text`               |
| `name`                 | The name of the report.                                                                                | `text`               |
| `developer_name`       | The unique name of the object in the API.                                                              | `text`               |
| `description`          | The description of the report. Limit: 255 characters.                                                  | `optional[text]`     |
| `folder_name`          | The name of the folder that contains the report.                                                       | `optional[text]`     |
| `namespace_prefix`     | The namespace prefix of the report.                                                                    | `optional[text]`     |
| `format`               | Indicates the format of the report. Can have one of these values: Tabular, Summary, Matrix, or Joined. | `optional[text]`     |
| `is_deleted`           | Indicates whether the report is deleted.                                                               | `optional[boolean]`  |
| `created_date`         | The date and time when the report was created.                                                         | `optional[datetime]` |
| `created_by_id`        | The ID of the user who created the report.                                                             | `optional[text]`     |
| `last_modified_date`   | The date and time when the report was last modified.                                                   | `optional[datetime]` |
| `last_modified_by_id`  | The ID of the user who last modified the report.                                                       | `optional[text]`     |
| `last_referenced_date` | The date and time when the report was last referenced.                                                 | `optional[datetime]` |
| `last_run_date`        | The date and time when the report was last run.                                                        | `optional[datetime]` |
| `last_viewed_date`     | The date and time when the report was last viewed.                                                     | `optional[datetime]` |