# Apex Actions

This guide documents the Apex Actions (Invocable Methods) provided by the Suger Salesforce App. These actions can be used in Salesforce Flows, Process Builder, and other automation tools to integrate co-sell workflows.

## Overview

Suger provides five Apex Actions for co-sell automation:

| Action | Description | Supported Partners |
| ------ | ----------- | ------------------ |
| Check If Opportunity Shared | Check if an opportunity has been shared as a referral | AWS, Azure, GCP |
| Co-Sell | Share an opportunity with a cloud partner (waits for completion, backfills to Salesforce) | AWS, Azure, GCP |
| Co-Sell (Fire and Forget) | Share an opportunity without waiting for completion | AWS, Azure, GCP |
| Process Inbound Co-Sell Referral | Accept or decline an inbound referral | Azure only |
| Update Referral-Opportunity Linkage | Link a referral to an opportunity | AWS, Azure, GCP |

---

## Check If Opportunity Shared

**API Name:** `CosellCheckSharedOppApexAction`

**Label:** Check If Opportunity Shared

**Description:** Check if an opportunity has already been shared as a co-sell referral with a specific partner or any partner.

### Supported Partners

AWS, Azure, GCP, or ANY (checks all partners)

### Inputs

| Parameter | Type | Required | Description |
| --------- | ---- | :------: | ----------- |
| Opportunity ID | Id | Yes | Salesforce Opportunity ID to check |
| Partner | String | No | Partner to check: `AWS`, `AZURE`, `GCP`, or `ANY`. Defaults to `ANY` if not specified |

### Outputs

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Success | Boolean | Whether the operation completed successfully |
| Has Been Shared | Boolean | Whether the opportunity has been shared with the specified partner |
| Message | String | Descriptive message about the result |

### Example Use Cases

- Prevent duplicate referral submissions by checking if an opportunity was already shared
- Conditionally show/hide co-sell buttons based on sharing status
- Validate before triggering co-sell automation

---

## Co-Sell (Share Opportunity)

**API Name:** `CosellShareReferralAsyncApexAction`

**Label:** Co-Sell

**Description:** Share an opportunity with a co-sell partner. This action creates a new referral in the cloud partner's system and backfills the referral record to Salesforce.

### Supported Partners

AWS, Azure, GCP

### Inputs

| Parameter | Type | Required | Description |
| --------- | ---- | :------: | ----------- |
| Partner | String | Yes | Cloud partner: `AWS`, `AZURE`, or `GCP` |
| Opportunity ID | Id | No | Salesforce Opportunity ID to share. Required unless **Referral Payload (JSON)** is provided |
| Referral Payload (JSON) | String | No | A complete referral payload as a JSON string (the same envelope used by the [Create a Referral API](/cosell/cosell-referral-api)). When provided, the field-mapping preview is skipped and this payload is submitted as-is |

### Outputs

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Success | Boolean | Whether the referral was created successfully |
| Message | String | Error message if the operation failed |
| Referral ID | Id | Salesforce Referral record ID (if successful) |
| External Referral ID | String | Suger Referral ID (returned even on partial failure) |

### Behavior

1. Validates user has write permission for the specified partner
2. Builds the referral payload — from the supplied **Referral Payload (JSON)** if provided, otherwise from the opportunity via field mapping
3. Creates the referral in the cloud partner's system via Suger
4. Polls for workflow completion (up to ~12 seconds)
5. Backfills the referral record to Salesforce

:::note
Provide **either** an Opportunity ID or a Referral Payload (JSON). If both are set, the payload is submitted and the Opportunity ID is used only to link the referral to that CRM record. This action performs HTTP callouts and may take several seconds to complete, so on a record-triggered Flow place it on the **Run Asynchronously** path. The external referral ID is returned even if later steps fail, allowing for manual recovery.
:::

---

## Co-Sell (Fire and Forget)

**API Name:** `CosellShareReferralAction`

**Label:** Co-Sell (Fire and Forget)

**Description:** Share an opportunity with a co-sell partner **without waiting** for the create to finish. The action returns as soon as the create workflow starts — it does not poll for completion or backfill a Salesforce `Referral__c` record. Use it when you don't need the result in the same Flow run.

### Supported Partners

AWS, Azure, GCP

### Inputs

| Parameter | Type | Required | Description |
| --------- | ---- | :------: | ----------- |
| Partner | String | Yes | Cloud partner: `AWS`, `AZURE`, or `GCP` |
| Opportunity ID | Id | No | Salesforce Opportunity ID to share. Required unless **Referral Payload (JSON)** is provided |
| Referral Payload (JSON) | String | No | A complete referral payload as a JSON string (the same envelope used by the [Create a Referral API](/cosell/cosell-referral-api)). When provided, the field-mapping preview is skipped and this payload is submitted as-is |

### Outputs

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Success | Boolean | Whether the create workflow started successfully |
| Message | String | Error message if the operation failed |
| Referral ID | String | Suger Referral ID — the external referral ID (no Salesforce record is created) |
| Partner | String | The partner the referral was shared with |

### Behavior

1. Validates user has write permission for the specified partner
2. Builds the referral payload — from the supplied **Referral Payload (JSON)** if provided, otherwise from the opportunity via field mapping
3. Creates the referral in the cloud partner's system via Suger and returns immediately

:::note
Provide **either** an Opportunity ID or a Referral Payload (JSON) (same precedence as **Co-Sell**). Unlike **Co-Sell**, this action does not wait for the partner or backfill a Salesforce record — `Success = true` means the create workflow was submitted, not that the partner accepted it. Look the referral up in Suger by the returned Referral ID to confirm the final status. On a record-triggered Flow, place it on the **Run Asynchronously** path (it performs an HTTP callout).
:::

---

## Process Inbound Co-Sell Referral

**API Name:** `CosellProcessInboundReferralApexAction`

**Label:** Process Inbound Co-Sell Referral

**Description:** Accept or decline an inbound co-sell referral from a cloud partner.

### Supported Partners

**Azure only** - AWS and GCP inbound referrals must be processed through their respective partner portals or the Suger UI.

### Inputs

| Parameter | Type | Required | Description |
| --------- | ---- | :------: | ----------- |
| Partner | String | Yes | Must be `AZURE` |
| Referral ID | String | Yes | Suger Referral ID (not the Salesforce record ID) |
| Decision | String | Yes | `ACCEPT` or `DECLINE` |
| Reason | String | No | Reason for declining (only applicable when declining) |

### Outputs

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Success | Boolean | Whether the operation completed successfully |
| Message | String | Error message if the operation failed |

### Behavior

**When accepting:**
- Updates the referral status to `Active` with substatus `Accepted`
- Invokes the pre-acceptance webhook (if configured)

**When declining:**
- Updates the referral status to `Closed` with substatus `Declined`
- Sets the status reason with the provided decline reason

:::warning
This action only supports Azure referrals. Attempting to use it with AWS or GCP will return an error.
:::

---

## Update Referral-Opportunity Linkage

**API Name:** `CosellUpdateReferralLinkageApexAction`

**Label:** Update Referral-Opportunity Linkage

**Description:** Link or update the linkage between a referral and a Salesforce opportunity. This is useful for manually associating referrals with opportunities or updating the linkage after the initial creation.

### Supported Partners

AWS, Azure, GCP, Suger (partner-to-partner co-sell)

### Inputs

| Parameter | Type | Required | Description |
| --------- | ---- | :------: | ----------- |
| Partner | String | Yes | Partner: `AWS`, `AZURE`, `GCP`, or `SUGER` |
| Opportunity ID | Id | Yes | Salesforce Opportunity ID to link |
| Referral ID | String | Yes | Suger Referral ID to update |

### Outputs

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| Success | Boolean | Whether the linkage was updated successfully |
| Message | String | Error message if the operation failed |

### Behavior

1. Validates user has write permission for the specified partner
2. Fetches the referral from Suger
3. Updates the `salesforceOpportunityId` field on the referral
4. For Azure referrals, also updates the `externalReferenceId` in the Microsoft referral set

---

## Permission Requirements

All Apex Actions require appropriate co-sell permissions:

| Action | Required Permission |
| ------ | ------------------- |
| Check If Opportunity Shared | None (read-only check) |
| Co-Sell | `Write_AWS_Referral`, `Write_Azure_Referral`, or `Write_GCP_Referral` (based on partner) |
| Co-Sell (Fire and Forget) | `Write_AWS_Referral`, `Write_Azure_Referral`, or `Write_GCP_Referral` (based on partner) |
| Process Inbound Referral | `Write_Azure_Referral` |
| Update Referral Linkage | `Write_AWS_Referral`, `Write_Azure_Referral`, `Write_GCP_Referral`, or `Write_Suger_Referral` (based on partner) |

Users with the `Create_Referral` permission have write access to all partners.

---

## Using Apex Actions in Flows

To use these actions in a Salesforce Flow:

1. Add an **Action** element to your flow
2. Search for the action by its label (e.g., "Co-Sell" or "Check If Opportunity Shared")
3. Configure the input parameters
4. Store the output values in flow variables for decision logic or display

### Example Flow: Auto-Share Opportunity

```text
1. [Trigger] Opportunity Stage = "Closed Won"
2. [Action] Check If Opportunity Shared (Partner: AWS)
3. [Decision] Has Been Shared = false?
   - Yes → [Action] Co-Sell (Partner: AWS)
   - No → [End]
4. [Decision] Success = true?
   - Yes → [Update Record] Set custom field "AWS Referral Created" = true
   - No → [Create Task] "Review failed AWS co-sell submission"
```

---

## Error Handling

All actions return a `Success` boolean and `Message` string. Common error scenarios:

| Error | Cause | Resolution |
| ----- | ----- | ---------- |
| "unsupported partner: X" | Invalid partner value | Use `AWS`, `AZURE`, or `GCP` (case-sensitive) |
| "only Azure is supported" | Using Process Inbound with non-Azure partner | Use Azure partner or process through partner portal |
| Permission denied | User lacks required custom permission | Assign appropriate permission set |
| "Referral not found" | Invalid referral ID | Verify the Suger referral ID is correct |
| "No response from Suger" | API connectivity issue | Check Suger integration status |

:::tip
Always check the `Success` output before proceeding with downstream logic. Store the `Message` output for debugging failed operations.
:::