Apex Actions

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

Overview

Fours provides eight Apex Actions for co-sell and offer automation:

ActionDescriptionSupported Partners
Check If Opportunity SharedCheck if an opportunity has been shared as a referralAWS, Azure, GCP
Co-SellShare 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 completionAWS, Azure, GCP
Process Inbound Co-Sell ReferralAccept or decline an inbound referral (Azure referral or AWS engagement invitation)Azure, AWS
Update Referral LinkageLink a referral to an opportunity and/or an accountAWS, Azure, GCP, Fours
Update AWS ReferralUpdate business fields on an AWS co-sell referralAWS only
Update Offer CRM LinkageLink a marketplace offer to an opportunity, an account and/or a quoteAWS, Azure, GCP, Snowflake, Oracle
Manage Offer ContactsList a marketplace offer’s contacts, add contacts, remove them, or send them the offer notificationAWS, Azure, GCP, Snowflake, Oracle

How an action reaches the cloud partner

Every action runs the same three-system path: your Flow calls an Apex method in the managed package, the package calls Fours over HTTP, and Fours talks to the cloud partner. Where the actions differ is what happens after Fours accepts the request — whether the Flow waits for the partner, and whether a Salesforce record comes back in the same run.


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

ParameterTypeRequiredDescription
Opportunity IDIdYesSalesforce Opportunity ID to check
PartnerStringNoPartner to check: AWS, AZURE, GCP, or ANY. Defaults to ANY if not specified

Outputs

ParameterTypeDescription
SuccessBooleanWhether the operation completed successfully
Has Been SharedBooleanWhether the opportunity has been shared with the specified partner
MessageStringDescriptive 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

ParameterTypeRequiredDescription
PartnerStringYesCloud partner: AWS, AZURE, or GCP
Opportunity IDIdNoSalesforce Opportunity ID to share. Required unless Referral Payload (JSON) is provided
Referral Payload (JSON)StringNoA complete referral payload as a JSON string (the same envelope used by the Create a Referral API). When provided, the field-mapping preview is skipped and this payload is submitted as-is

Outputs

ParameterTypeDescription
SuccessBooleanWhether the referral was created successfully
MessageStringError message if the operation failed
Referral IDIdSalesforce Referral record ID (if successful)
External Referral IDStringFours 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 Fours
  4. Polls for workflow completion (up to ~12 seconds)
  5. Backfills the referral record to Salesforce

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

ParameterTypeRequiredDescription
PartnerStringYesCloud partner: AWS, AZURE, or GCP
Opportunity IDIdNoSalesforce Opportunity ID to share. Required unless Referral Payload (JSON) is provided
Referral Payload (JSON)StringNoA complete referral payload as a JSON string (the same envelope used by the Create a Referral API). When provided, the field-mapping preview is skipped and this payload is submitted as-is

Outputs

ParameterTypeDescription
SuccessBooleanWhether the create workflow started successfully
MessageStringError message if the operation failed
Referral IDStringFours Referral ID — the external referral ID (no Salesforce record is created)
PartnerStringThe 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 Fours and returns immediately

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 and AWS. For AWS the action processes a pending engagement invitation — the inbound form an AWS-originated referral arrives in. GCP inbound referrals must still be processed through the partner portal or the Fours UI.

Inputs

ParameterTypeRequiredDescription
PartnerStringYesAZURE or AWS
Referral IDStringYesFours Referral ID (not the Salesforce record ID)
DecisionStringYesACCEPT or DECLINE
ReasonStringNoReason for declining (only applicable when declining). For AWS this is passed to Partner Central, which requires a single line of at most 80 characters

Outputs

ParameterTypeDescription
SuccessBooleanWhether the operation completed successfully
MessageStringError message if the operation failed

Behavior

Azure — when accepting:

  • Updates the referral status to Active with substatus Accepted
  • Invokes the pre-acceptance webhook (if configured)

Azure — when declining:

  • Updates the referral status to Closed with substatus Declined
  • Sets the status reason with the provided decline reason

AWS — when accepting:

  • Accepts the engagement invitation in AWS Partner Central (ACE)
  • Returns as soon as AWS takes the request. AWS creates the opportunity asynchronously, so the referral’s status and opportunity fields are filled in shortly afterwards by the inbound sync, not by this action

AWS — when declining:

  • Rejects the engagement invitation in AWS Partner Central and sets the referral to REJECTED
  • The decline reason is recorded on the Fours referral and sent on to AWS Partner Central. When no reason is given, AWS is sent Other
  • If auto-delete is enabled for the org, the linked CRM records are removed

AWS — when AWS refuses the accept or decline:

  • The action returns Success = false with the error in Message
  • The failure is also recorded on the referral: the invitation’s status badge reads Update Failed: followed by the reason until a later accept or decline succeeds. The referral’s own status is not changed

Update Referral Linkage

API Name: CosellUpdateReferralLinkageApexAction

Label: Update Referral Linkage

Description: Link a referral to a Salesforce opportunity, an account, or both. Use it to associate a referral with CRM records by hand, or to correct the linkage after the referral was created.

Supported Partners

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

Inputs

ParameterTypeRequiredDescription
PartnerStringYesPartner: AWS, AZURE, GCP, or SUGER. Case-insensitive
Referral IDStringYesFours Referral ID to update
Opportunity IDIdNoSalesforce Opportunity ID to link. At least one of Opportunity ID or Account ID is required
Account IDIdNoSalesforce Account ID to link. At least one of Opportunity ID or Account ID is required

Outputs

ParameterTypeDescription
SuccessBooleanWhether the linkage was updated successfully
MessageStringNo changes; skipped. when the referral already holds the IDs you supplied; the reason on failure; otherwise empty

Behavior

  1. Rejects an unsupported partner, and rejects a request that supplies neither Opportunity ID nor Account ID — opportunityId or accountId is required — before spending a callout
  2. Validates the user has write permission for the specified partner
  3. Fetches the referral from Fours
  4. Returns Success = true with No changes; skipped. when the referral already holds the IDs you supplied. An ID you did not supply never counts as a difference, so re-running an account-only link is a no-op rather than a write
  5. Writes salesforceOpportunityId and salesforceAccountId — only the ones you supplied
  6. For Azure with an Opportunity ID, also updates externalReferenceId in the Microsoft referral set, so the link reaches Microsoft Partner Center

Update AWS Referral Fields

API Name: CosellUpdateAwsReferralApexAction

Label: Update AWS Referral

Description: Update business fields on an existing AWS co-sell referral. Only the fields you supply are changed — leave a field out and it keeps its current value. A referral belonging to another partner is refused.

Supported Partners

AWS

Inputs

ParameterTypeRequiredDescription
Referral IDStringYesFours Referral ID to update
APN ProgramsStringNoSemicolon-separated APN program names, e.g. Migration Acceleration Program;Well-Architected. Values must come from the AWS APN Program picklist. Model Provider PARC is accepted only on a referral AWS originated. Pass an empty value to remove every program
Next StepStringNoNext step on the opportunity, up to 255 characters
Target Close DateDateNoMust be a future date (after today, UTC). AWS freezes this once the opportunity is Launched
Customer Business ProblemStringNoThe customer’s situation and the problem they need solved, 20 to 2,000 characters
Additional CommentsStringNoFree-text notes on the opportunity, up to 255 characters

Outputs

ParameterTypeDescription
SuccessBooleanWhether the referral was updated
MessageStringThe fields updated on success, or the reason it was refused
APN ProgramsStringThe full program list on the referral after the update, semicolon-separated
Referral StatusStringThe referral status as it stood before this update, e.g. ACTIVE or ACTION_REQUIRED. Fours recomputes the status while saving, and the push to AWS can change it again after that — re-read the referral if a Flow must branch on the new value

Behavior

  1. Validates that at least one field was supplied — every field is optional, but a request that sets none is refused rather than costing two callouts to write the referral back unchanged — and that the user has write permission for the partner
  2. Validates every supplied value before any callout and refuses the whole update if one fails: APN Programs must all be on the AWS APN Program picklist (an unrecognized value is rejected by AWS and blocks every later change to that referral), Target Close Date must be in the future, and the text fields must be within the lengths above. Fours would otherwise keep the old value or truncate silently, so it is caught here instead
  3. Fetches the referral from Fours
  4. Refuses a referral that belongs to another partner — the caller passes only a referral ID, so the referral’s own partner decides
  5. Refuses the update unless AWS has the opportunity at Approved or Action Required; AWS accepts changes in no other review status
  6. Refuses the update when the opportunity is Launched or Closed Lost, because AWS does not accept changes after close
  7. Refuses Model Provider PARC unless AWS originated the referral — AWS rejects it on a partner-originated opportunity, and that rejection blocks every later change to the referral. It stays editable on an inbound referral
  8. Applies only the supplied fields and sends the complete referral back to Fours, which pushes it to AWS asynchronously

APN Programs replace the full list rather than adding to it — AWS treats the field as a set. Send every program the referral should end up with.

Clearing APN Programs. Pass an empty value (in Flow, the Blank Value (Empty String) resource) to remove every program. This is the only field that can be cleared — the others are left untouched when blank, because AWS either requires them or enforces a minimum length. Note the current limitation: the empty set is stored in Fours, but it does not yet reach AWS, so the programs can reappear on the next inbound sync. Clearing at AWS is tracked separately.

Each request in a Flow collection gets its own result, so one bad row does not stop the others.


Update Offer CRM Linkage

API Name: OfferUpdateCrmLinkageApexAction

Label: Update Offer CRM Linkage

Description: Link a marketplace offer to a Salesforce opportunity, an account, a quote, or any combination after the offer exists. Use it from CPQ or quote-driven Flows, or to repair an offer that was created without a link.

Supported Partners

AWS, Azure, GCP, Snowflake, Oracle

Inputs

ParameterTypeRequiredDescription
Offer Record IDTextYesThe Offer record to link
Opportunity IDTextNoOpportunity to link. Leave blank to keep the current link
Account IDTextNoAccount to link. Leave blank to keep the current link
Quote IDTextNoQuote or Salesforce CPQ quote to link. When the request or the offer already names an opportunity, the quote must belong to it. Leave blank to keep the current link

Set at least one of Opportunity ID, Account ID or Quote ID. The inputs take 15- or 18-character record IDs as text, so a Screen Flow can pass a blank text field straight through.

Outputs

ParameterTypeDescription
SuccessBooleanWhether the operation was successful
MessageStringLinked. on success, noting any link it replaced (for example Linked. Replaced opportunity 006… with 006…. Kept quote 0Q0… from before.); No changes; skipped. when the offer already has these links; otherwise the reason it was refused
Linked OffersStringThe offers this action has linked so far in the transaction, including this one and offers that were already linked, comma-separated, each as Name (Fours offer ID)

A Flow Loop calls the action once per offer, so each call only sees its own offer. Use the last call’s Linked Offers after the loop to report the run. A record-triggered Flow that saves many records at once runs as one transaction, so the list covers all of them.

A blank ID is left alone, not cleared. Leaving Opportunity ID, Account ID or Quote ID empty keeps whatever Fours already holds, so a Flow that sets only the quote cannot wipe the offer’s opportunity. To remove an opportunity link, use Unlink in the Opportunity section of the offer page; this action cannot unlink.

Behavior

  1. Validates the inputs before any callout: each ID must be a valid record ID of the right type (an Account ID in the Opportunity ID input is refused), and at least one link is set
  2. Checks that the user has offer write permission for the offer’s marketplace
  3. Refuses an opportunity or quote link on a public offer (a default or free-trial listing offer). Any buyer can purchase a public offer, so it never belongs to one deal. An account link is still allowed
  4. Refuses a quote that belongs to a different opportunity than the offer’s: the Opportunity ID in the request (checked with the inputs, before any callout), or, when none is given, the opportunity Fours holds for the offer, falling back to the Offer record’s Opportunity only when Fours holds none. Fours comes first because the Offer record shows this action’s own link changes only after the next sync
  5. Reads the offer from Fours, sets the supplied links, and saves the offer’s details back, so everything else on the offer is kept. Skips the update when the offer already carries the same links
  6. Fours syncs the offer back to Salesforce: the Offer record’s Opportunity is updated, and its Account follows the opportunity’s account, or the linked account when there is no opportunity

When it fails

Each request in a Flow collection gets its own result, so one bad row does not stop the others. There are two kinds of failure:

  • The link is refused (an invalid input, a public offer, a quote from another opportunity, an Offer record that hasn’t synced its Fours offer ID yet, or Fours rejecting the link with Fours refused the link: …): Success = false with the reason in Message. Nothing was changed. Add a Decision on Success if the Flow should react.
  • The run fails when Fours cannot do the work: the offer no longer exists in Fours, Fours is unreachable, the user lacks offer write permission, or the transaction runs out of Salesforce limits. The whole Flow run fails, so its fault path or Salesforce’s Flow error email tells you. Offers linked before that point stay linked, and the error lists them. Run the Flow again once the cause is fixed; leave out the offers already linked, since each one is still read from Fours.

Large batches. A Flow loop calls the action once per offer, and each call uses two callouts and three queries (four when it links a quote). One transaction therefore links about 30 offers, or about 25 with quotes; an asynchronous path allows up to about 50. To link more, split the offers across runs and leave out offers that are already linked.

One writer per offer at a time. Saving reads the offer and writes its details back, so two Flows linking the same offer at the same moment can overwrite each other’s link. Run the Flow again for that offer if a link is missing.


Manage Offer Contacts

API Name: OfferManageContactsApexAction

Label: Manage Offer Contacts

Description: List the contacts on a marketplace offer, add contacts, remove them, or send them the offer notification, which is what the Notify button on the offer page does. Use it from a Flow, from Apex, or from any tool that runs invocable actions.

Supported Partners

AWS, Azure, GCP, Snowflake, Oracle

Inputs

ParameterTypeRequiredDescription
Offer Record IDTextYesThe Offer record (a 15- or 18-character Salesforce record ID)
ActionTextYesadd, remove, notify or preview
Contact EmailsTextNoContact email addresses, separated by commas, semicolons or spaces, at most 100. Needed for add and remove. For notify, leave blank to notify every contact on the offer. Not used by preview
Contact NameTextNoUsed by add only: the name Fours gives the contact it creates. Use it with a single email. A contact Fours already has keeps its name

Contact Emails is optional because notify with no emails means every contact on the offer, as the Notify button does, and preview always lists every contact. add and remove are refused with the reason in Message when it is blank.

Outputs

ParameterTypeDescription
SuccessBooleantrue when no contact failed. A skipped contact is not a failure
MessageStringThe counts, for example 1 succeeded, 1 skipped, 0 failed., or for preview the number of contacts, for example Contacts on the offer: 2., or the reason the request was refused
Contact ResultsStringA JSON list with one entry per contact: email, contactId (the Fours contact ID), name (filled by preview), status (SUCCESS, SKIPPED or ERROR) and reason

For example, preview on an offer with one contact returns this in Contact Results:

[
  {
    "email": "jane@example.com",
    "contactId": "hPWrkAWNZ",
    "name": "Jane Doe",
    "status": "SUCCESS",
    "reason": "On the offer."
  }
]

An offer with no contacts returns Success = true, Contacts on the offer: 0. and an empty list, [].

Behavior

  1. Validates the inputs before any callout: the action name, the Offer Record ID, that add and remove name at least one contact, that add, remove and notify name at most 100 (preview ignores Contact Emails), and that a Contact Name for add comes with only one email
  2. Checks the user’s permission (see Permission Requirements)
  3. Reads the offer and its contacts from Fours, and matches each email to a contact. Emails are not case-sensitive
  4. preview: lists every contact on the offer with its email, Fours contact ID and name, whatever the offer’s status. It sends nothing and changes nothing
  5. add: adds each contact to the offer. A contact already on the offer is skipped. Fours looks up each email among your organization’s contacts and creates a contact for an email it does not know yet, named with Contact Name when given
  6. remove: removes each contact from the offer. A contact that is not on the offer is skipped
  7. notify: sends the offer notification, with these rules:
    • The offer must be in PENDING_ACCEPTANCE; any other status refuses the whole request
    • A contact that is not on the offer gets ERROR and is not notified
    • A contact notified in the last 5 minutes gets SKIPPED, so a repeated run does not send the email twice
    • Each send appears in the offer’s Offer Status History, as it does for the Notify button

When it fails

Each request gets its own result, and within a request each contact gets its own, so one bad contact does not stop the others.

  • The request is refused (an invalid input, an Offer record that hasn’t synced its Fours offer ID yet, a missing permission, an offer that is not pending for notify, a notify with no Contact Emails on an offer that has no contacts, a request that starts after the transaction has used up its Salesforce limits, or Fours being unreachable): Success = false with the reason in Message, and no Contact Results. The no-contacts and limits refusals read The offer has no contacts to notify. and Salesforce limits reached. Run the action again on fewer offers.
  • A contact fails: Success = false, and that contact’s entry in Contact Results has status ERROR with the reason. The other contacts are still processed.

Large batches. add and remove use one callout per contact, and notify uses one for the whole request, on top of the callouts that read the offer and its contacts. A contact that would exceed the transaction’s Salesforce limits gets ERROR with a message to run the action again for it.


Permission Requirements

All Apex Actions require the matching co-sell or offer permissions:

ActionRequired Permission
Check If Opportunity SharedNone (read-only check)
Co-SellWrite_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 ReferralWrite_Azure_Referral or Write_AWS_Referral (based on partner)
Update Referral LinkageWrite_AWS_Referral, Write_Azure_Referral, Write_GCP_Referral, or Write_Suger_Referral (based on partner)
Update Referral FieldsWrite_AWS_Referral
Update Offer CRM LinkageWrite_AWS_Offer, Write_Azure_Offer, Write_GCP_Offer, Write_SNOWFLAKE_Offer, or Write_ORACLE_Offer (based on the offer’s marketplace)
Manage Offer ContactsNotify_Offer_Contacts for notify and preview, Modify_Offer_Contacts for add and remove, or the same offer write permission as Update Offer CRM Linkage

Users with the Create_Referral permission have write access to all partners, and users with Create_Offer can link offers on every marketplace.


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

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:

ErrorCauseResolution
“unsupported partner: X”Invalid partner valueUse AWS, AZURE, or GCP — plus SUGER on Update Referral Linkage. Match the spelling exactly: only Update Referral Linkage and Update AWS Referral normalize the case for you
“opportunityId or accountId is required”Update Referral Linkage called with both IDs emptySupply an Opportunity ID, an Account ID, or both
“only AWS and Azure are supported”Using Process Inbound with a partner other than AZURE or AWSUse AZURE or AWS, or process through the partner portal
“Engagement invitation not found”Process Inbound on an AWS referral that is not an inbound engagement invitationOnly AWS-originated inbound referrals carry an invitation to accept
“Engagement invitation is not pending, current status: X”The AWS invitation was already accepted, rejected or has expiredNothing to do — check the referral’s current state in Fours
Permission deniedUser lacks required custom permissionAssign appropriate permission set
“Referral not found”Invalid referral IDVerify the Fours referral ID is correct
“No response from Fours”API connectivity issueCheck Fours integration status
“No fields supplied. Set at least one of: …”Update Referral Fields called with every field emptySet at least one field; a blank string counts as empty
“Not a valid value for APN Programs: X”A program name not on the AWS APN Program picklistUse the picklist values exactly; the whole update is refused, nothing was sent
”… must be a future date” / ”… must be at least/most N characters”A value Fours would silently drop or truncateFix the value; nothing was sent
“Opportunity is Launched. AWS does not accept updates after close…”Referral is Launched or Closed LostNo update is possible after close
”… failed to create (status CREATE_FAILED) and cannot be edited via update …”Update AWS Referral was called on a referral whose creation failed (CREATE_FAILED); Fours refuses updates to itResubmit the referral instead: open it in Salesforce and use Re-submit on its detail page, which sends it through create again under the same referral ID
“A public offer can be bought by any buyer, so it cannot be linked to an opportunity or quote”Update Offer CRM Linkage on a default or free-trial offerLink only an account, or link the buyer’s entitlement instead
“Salesforce limits reached after linking N offers in this run: … run the Flow again on fewer offers …”Too many offers in one transaction for Update Offer CRM LinkageRun the Flow again on fewer offers, leaving out the ones the error lists
“Quote … belongs to a different opportunity (…) than the offer’s opportunity (…)”Update Offer CRM Linkage with a quote from another dealUse a quote from the offer’s opportunity, or set the matching Opportunity ID
“Offer record has no Fours offer ID. Sync offers in Salesforce, then run the Flow again.”Update Offer CRM Linkage on an Offer record that hasn’t finished syncingSync offers, then run the Flow again
“Offer … no longer exists in Fours. Sync offers in Salesforce, then run the Flow again.”The Offer record points at an offer Fours has deletedSync offers, then run the Flow again
“Fours could not update offer … right now”Fours was unreachableRun the Flow again later; contact Fours support if it keeps failing
“You do not have permission to update X offers. Ask your Salesforce admin for the Write X Offer or Create Offer permission.”Update Offer CRM Linkage run by a user without offer write access for that marketplaceAssign a permission set that grants it
”… is not a valid Salesforce record ID”An input holds text that is not a record IDPass a 15- or 18-character record ID, or leave the input blank

Spotted something wrong or out of date on this page? Tell us and we'll correct it.