# Using an earlier CRM with Amazon S3 integration
**Important**
AWS Partner Central stopped accepting new requests for this type of integration in 2024. This section only applies to partners using Amazon S3.
To get started with a new custom CRM integration, refer to the [AWS Partner Central API Reference](https://docs.aws.amazon.com/partner-central/latest/APIReference/aws-partner-central-api-reference-guide.html).
**Topics**
+ [Upgrading from a CRM with Amazon S3 integration to the Partner Central API](upgrade-crm-api.md)
+ [Configuring the connector for a CRM with Amazon S3 integration](s3-config.md)
+ [Integration resources](resources.md)
+ [Lead sharing](custom-lead-sharing.md)
+ [Opportunity sharing](custom-opportunity-sharing.md)
+ [Field mapping](custom-field-mapping.md)
+ [Creating synchronization schedules](crm-connector-scheduling.md)
+ [Best practices](best-practices.md)
+ [Quotas](quotas.md)
+ [Version history](version-history.md)
+ [FAQs](faqs.md)
# Upgrading from a CRM with Amazon S3 integration to the Partner Central API
**Note**
The topics in this section assume you've completed the prerequisites for an AWS Partner Central integration, an AWS Marketplace integration, or both. For more information, refer to [Integration prerequisites](crm-integration-setting-up.md) and [Getting started](crm-integration-getting-started.md) earlier in this guide.
The steps in the following sections explain how to upgrade from an earlier CRM with Amazon S3 integration to the AWS Partner Central API. Upgrading removes the need for several ACE requirements, such as the need for an integration user, and the need to set up synchronization schedules.
**Topics**
+ [Upgrade features](api-upgrade-features.md)
+ [Set up named credentials](set-up-api-credentials.md)
+ [Add the Approval Status button to the Opportunity Lightning Record page](add-approval-status-button.md)
+ [Add the remaining buttons](add-remaining-buttons.md)
+ [Refresh the Solution Offerings tab](refresh-the-solutions-from-the-solution-offerings-tab.md)
# Upgrade features
The upgrade provides the following features:
+ You no longer need an ACE integration user permission set in Salesforce.
+ You no longer need to create a schedule for ACE opportunities in Salesforce.
+ The Partner Central API also provides a set of buttons that enable the following actions on your **Opportunity Lightning Record** page:
+ **Approval Status** – Accept or reject AWS Referred Opportunities.
**Note**
This button replaces the **Partner Acceptance Status** list. You must use the button to accept AWS-originated opportunities.
+ **Share with AWS** – Create and update opportunities.
+ **Associate or Disassociate** – Associate or disassociate an opportunity with Partner Solutions, AWS products, and AWS Marketplace offers throughout the opportunity lifecycle.
+ **Assign** – Reassign an opportunity to another user in your Partner Central account.
You add the buttons after you set up named credentials. The following topics explain how to complete those tasks.
# Set up named credentials
To upgrade to the Partner Central API, you first set up named credentials. The CRM connector uses your Salesforce organization credentials to authenticate with Partner Central.
**To set up credentials**
1. Sign in to Salesforce as a system administrator.
1. Under **Named credentials**, choose **New earlier**.
1. In the **New named credential** form, enter the values from the following table.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/partner-central/latest/crm/set-up-api-credentials.html)
1. Choose **Save**.
1. Return to the **AWSGuided setup** page. In the **Authentication details** section, choose **Review** and confirm the credentials.
# Add the Approval Status button to the Opportunity Lightning Record page
The following steps explain how to add the **Approval Status** button to your Opporuntiy Lightning Record page. The button enables you to see the status of your opportunities as they go through the approval process.
**To add the button**
1. Sign in to your Salesforce organization as a system administrator.
1. Navigate to the **Opportunity Lightning Record** page.
1. Choose the highlighted panel to open the properties pane.
1. Select **Upgrade now**.
1. Select **Migrate existing actions**, then select the page layout from which you want to upgrade the actions.
—OR—
Start from scratch and add the actions manually.
1. From the **Actions** list, choose **Approval Status**.
1. Choose **Save**.
**Note**
You only need to complete steps 4 and 5 once.
The **Approval status** button only appears in the **Opportunity Lightning Record** page for AWS-referred opportunities.
# Add the remaining buttons
You can add some or all of the buttons listed in the following steps.
**To add the buttons**
1. Sign in to your Salesforce organization as a system administrator.
1. Navigate to the **Opportunity Lightning Record Page**.
1. Choose the highlighted panel to open the properties pane.
1. Choose **Assign from Actions**, then select some or all of the following items:
+ **Share with AWS**
+ **Associate or Disassociate**
+ **Assign**
For more information about what each button does, refer to [Upgrade features](api-upgrade-features.md), earlier in this guide.
1. Choose **Save**.
# Refresh the Solution Offerings tab
The following steps explain how to refresh the data on the **Solution Offerings** tab.
1. Sign in to your Salesforce organization as a system administrator.
1. Navigate to the **Solution Offerings** tab.
1. Select **Refresh Solutions**.
# Configuring the connector for a CRM with Amazon S3 integration
**Important**
Starting in 2024, AWS Partner Central made this integration type unavailable to new users.
**Note**
The topics in this section assume you've completed the prerequisites for an AWS Partner Central integration, an AWS Marketplace integration, or both. For more information, refer to [Integration prerequisites](crm-integration-setting-up.md) and [Getting started](crm-integration-getting-started.md) earlier in this guide.
The deprecated CRM with Amazon S3 integration uses an Amazon S3 bucket to transfer leads and opportunities . We recommend using the Partner Central API integration as shown in the previous section to create and manage opportunities. However, you can use this configuration if you want to use the connector to manage leads in Salesforce.
**Topics**
+ [Entering connection authentication details](#apn-s3-authentication-details)
+ [Entering system configuration settings](#apn-s3-config-settings)
+ [Testing the connection](#apn-s3-testing)
+ [Sending and receiving opportunities and leads](#sending-receiving-opportunities-leads)
+ [Production checklist](ace-production-checklist.md)
+ [Upgrading AWS Partner CRM connector to the new data model](connector-upgrade-plan.md)
+ [Sandbox testing with the custom ACE opportunity and ACE lead objects](custom-ace-opportunity.md)
+ [Linking AWS Marketplace private offers to ACE opportunities](#linking-private-offers-to-ace)
## Entering connection authentication details
Partners start the integration process by entering the details needed to connect to their Amazon S3 endpoint. Follow each set of steps in the order listed, and complete each set before proceeding to the next one.
The following tasks are performed from the **AWS guided setup** tab. For information about using the tab, refer to [Using guided setup](use-guided-setup.md) earlier in this guide.
**To enter the authentication details**
1. In Salesforce, open the **AWS guided setup** tab. For information about opening that tab, refer to [Using guided setup](use-guided-setup.md) earlier in this guide.
1. Expand **Step 1: AWS connection authentication details** and choose **Start.**
1. On the **Named credentials** page, choose **New earlier**.
1. In the **New named credential** form, enter the values from the following table.
| **Field** | **Value** |
| --- | --- |
| Label | APN API Connection |
| URL | [https://s3.us-west-2.amazonaws.com](https://s3.us-west-2.amazonaws.com) |
| Identity type | Named Principal |
| Authentication protocol | AWS signature version 4 |
| AWS access key ID | Cloud-Ops provides the ID during the prerequisite steps |
| AWS secret access key | Cloud-Ops provides the access key during the prerequisite steps |
| AWS Region | us-west-2 |
| AWS service | s3 |
| Generate authorization header | checked |
| Allow merge fields in HTTP header | unchecked |
| Allow merge fields in HTTP body | unchecked |
1. Choose **Save**.
1. Return to the **AWSGuided setup** page. In the **Authentication details** section, choose **Review** and confirm the credentials.
1. Keep the **AWSGuided setup** page open and go to the next steps.
## Entering system configuration settings
The following steps explain how to enter the correct system configuration settings for the integration.
1. Expand **Step 2: System configuration settings** and choose **Start.**
1. Locate the **AWS Partner CRM Connector Settings**, and choose **Manage**.
1. Choose **New**, and then enter the required values from the following table.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/partner-central/latest/crm/s3-config.html)
1. Choose **Save**.
1. Return to the **AWSGuided setup** page. In the **Authentication details** section, choose **Review** and confirm the credentials.
## Testing the connection
Before testing the connection, make sure you complete the steps in the previous sections.
**To test the connection**
1. Expand **Step 3: Test configuration for APN API**.
1. Choose **Test**.
If the connection succeeds, you receive a confirmation message.
## Sending and receiving opportunities and leads
You send and receive opportunities and leads by synchronizing them with Partner Central. To synchronize an opportunity or lead, you must set the **Sync with Partner Central** field to **True**. Additional key fields for integration include the **Last APN Sync Date** and the **Eligible to Sync with APN** fields.
These fields are included for standard opportunities and leads. However, you must create and map them for any custom source objects.
+ **Sync with Partner Central** – Included in the app for standard opportunities and leads. If a AWS Partner chooses to map to custom objects, a custom boolean field must be created and mapped in the opportunity and lead mappings, respectively.
+ **Last Sync Date with APN** – Indicates the last time the record was successfully sent to or received from APN. This field is autoset when the record is successfully sent to APN or an update is received from APN.
+ **Eligible to Sync with APN** – A formula field that determines if the record is targeted to be sent to APN in the next scheduled job. Calculated based on whether the record was modified since the last time the outbound schedule ran, and it was updated by a user other than the designated integration user for the AWS Partner's organization.
# Production checklist
Follow these steps to complete the production installation of your AWS Partner CRM connector.
1. Confirm that you completed the [onboarding process](https://docs.aws.amazon.com/partner-central/latest/crm/crm-integration-getting-started.html) for the CRM integration. In [stage 6](https://docs.aws.amazon.com/partner-central/latest/crm/stage-6-production-approval.html) of this process, you set up your production environment and perform data migration so you can manage opportunities and leads through the integration.
1. Install and configure the CRM connector. For more information, refer to [Installing the connector](install-connector.md).
1. Map opportunities and lead objects by choosing one of the following mapping options. For reference, see this list of [required fields](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/opportunity-samples/Opportunity-Fields.csv) on GitHub.
+ Use the AWS ACE opportunity custom object provided with AWS Partner CRM connector to log opportunities and share them with AWS. Using this option, you can automatically map AWS fields to Salesforce fields.
+ Use the standard Salesforce object and map the required AWS fields.
+ Use an ACE custom opportunity object. You first create a workflow to populate an intermediate table of ACE opportunity objects and then map the Salesforce fields to AWS.
1. For additional details and guidance about mapping options, refer to [Mapping ACE objects](crm-connector-mapping.md).
1. (Optional) Set up inbound and outbound synchronization schedules between the AWS Partner Network and Salesforce. For details, refer to [Creating synchronization schedules](crm-connector-scheduling.md).
1. To validate a partner-originated opportunity in production, raise a [support case](https://docs.aws.amazon.com/partner-central/latest/crm/crm-integration-faq.html#troubleshooting) with Partner Central Operations (PCO) in your Partner Central account. In this process, you create a dummy opportunity, sync it with AWS, and ask the AWS support agent to confirm that AWS received the opportunity. At the end of testing, ask your AWS support agent to reject the opportunity request so you can delete it from your side.
1. (Optional) Perform data backfill. This process ensures that both AWS Originated and Partner Originated opportunity referrals can be identified during future updates. For more information, refer to [Stage 6: Production approval](https://docs.aws.amazon.com/partner-central/latest/crm/stage-6-production-approval.html) in the CRM onboarding process.
1. Activate the production integration to allow the exchange of files through the Amazon S3 bucket. For details, refer to [Stage 7: Launch](https://docs.aws.amazon.com/partner-central/latest/crm/stage-7-launch.html).
# Upgrading AWS Partner CRM connector to the new data model
**Important**
Test and approve the new data model upgrade in your sandbox Salesforce organization before upgrading your production environment. For the new data model and changes between the old and new models, refer to the following [aws-samples/partner-crm-integration-samples](https://github.com/aws-samples/partner-crm-integration-samples/tree/main/opportunity-samples) on GitHub:
**Opportunity-FieldsAndStandardValues-DiffWithPrevVersion-V14.3.xlsx**
**Opportunity-Fields.xlsx**
**Opportunity\$1-\$1StandardValues.xlsx**
## Prerequisites
+ Use field definitions for new data model guidelines of the ACE CRM integration, and migrate any required open opportunities and leads to the new data model.
+ Add or remove columns in your custom or standard objects (objects used in mapping).
+ Ensure that you're using version 2.0 or later of the AWS Partner CRM connector.
**To upgrade to the new data model**
1. Sign in to your Salesforce organization as a system administrator.
1. Deactivate any active schedules.
1. Choose **Setup**, **Custom Settings**, **AWS Partner CRM connector Settings**, and then update the version to **2.0** or later.
**Note**
Starting with version 2.0, the **Version** field is mandatory. This field specifies the payload version that partners use to interact with the CRM Integration. When partners move to version 2.0, they must fully adopt its specifications. Reverting to previous versions isn't permitted.
1. Choose the **ACE Mapping** tab.
1. Create, review, and update all required field mappings and details. For sandbox testing, use the custom ACE opportunity and ACE lead object to test the new data model features. For more information, refer to [Sandbox testing with the custom ACE opportunity and ACE lead objects](custom-ace-opportunity.md).
1. Activate schedules for opportunities and leads.
1. Review the ACE sync logs for synchronization errors and make any corrections.
1. Review the synced opportunities and leads to ensure that the data transformation is accurate. Alternatively, review the opportunities and leads in ACE to ensure that the new data model changes are captured accurately.
1. Follow your product deployment process to migrate the changes to your production Salesforce environment.
**Note**
If you need help, refer to [Getting help](getting-help.md).
# Sandbox testing with the custom ACE opportunity and ACE lead objects
**Note**
If you are an existing CRM connector user, refer to [Upgrading AWS Partner CRM connector to the new data model](connector-upgrade-plan.md).
1. Sign in to your Salesforce organization as a system administrator.
1. Choose **Setup**, **Custom settings**, **AWS Partner CRM connector settings**, and update version to **2**.
1. Choose the **ACE Mapping** tab.
1. For **Opportunity**, map it to the **ACE opportunity** custom object.
1. Choose **Auto Map ACE object**.
**Note**
If you want to upgrade to the new version of the CRM connector that want to use the custom ACE opportunity and ACE lead objects from the connector for sandbox testing, we recommend manually deleting any available records from the `Field Mappings` and `Field Mapping Details` objects from the database before using the Auto Map ACE object feature. You only need to do this once.
1. Review field mappings and field mapping values for picklist and multipicklist.
1. Activate schedules for opportunities and leads.
1. Review the ACE Sync Logs for synchronization errors and make any required corrections.
1. Review the synced opportunities and leads to ensure the data transformation is accurate. Alternatively, review the opportunities and leads in ACE to ensure that the new data model changes have been accurately captured.
## Viewing sync log detail records for ACE opportunities
You can view sync log details for AWS-delivered ACE opportunities on the **Related** tab on the ACE opportunity record.
**Note**
These steps only apply to AWS-delivered ACE opportunity objects. If you map to standard or custom objects in your Salesforce organization, you can view sync log details on the **ACE Sync Log** tab.
1. Sign in to your Salesforce organization.
1. In the **App Launcher**, choose **AWS Partner CRM connector**.
1. Choose the **ACE Opportunities** tab.
1. Choose an ACE opportunity record.
1. Choose the **Related** tab to view details including **Sync Log Name**, **Status**, **Error Message**, and **Created Date**.
## Linking AWS Marketplace private offers to ACE opportunities
You can link private offers directly from the AWS delivered ACE opportunity record page.
1. Sign in to your Salesforce organiziation.
1. In the **App Launcher**, choose **AWS Partner CRM connector**.
1. Choose the **ACE Opportunities** tab.
1. Choose an ACE opportunity record.
1. Choose **Link Private Offer**.
1. In **Offer ID Look Up**, choose the private offer.
1. Choose **Save**.
# Integration resources
AWS provides the following resources to help you create a custom integration.
**Topics**
+ [Field definitions](#custom-field-definitions)
+ [Standard values](#standard-values)
+ [Sample inbound files](#sample-inbound-files)
+ [Sample outbound files](#sample-outbound-files)
+ [Sample processed results](#sample-processed-results)
+ [Sample test cases](#sample-test-cases)
+ [Sample code snippets](#sample-code-snippets)
## Field definitions
The links in the following sections list all the fields, explaining their data types, usage, and any constraints or formatting rules that apply. They serve as a reference to ensure that when partners and AWS exchange data, it’s correctly formatted and understood.
The following links take you to GitHub.
+ [Opportunity](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/opportunity-samples/Opportunity-Fields.csv)
+ [Lead](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/lead-samples/Leads-Fields.csv)
## Standard values
These lists outline the standard values and enumerations for various fields. They help to maintain consistency in the data exchanged, and ensure that both parties have a common understanding of the values used.
The following links take you to GitHub.
+ [Opportunity](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/opportunity-samples/Opportunity_-_StandardValues.csv)
+ [Lead](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/lead-samples/Lead_-_StandardValues.csv)
## Sample inbound files
The following sample files show the structure of the JSON payload for a file sent from a partner to AWS.
The following links take you to GitHub.
+ [Opportunity](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/opportunity-samples/Opportunity-Create-Inbound-Sample.json)
+ [Lead](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/lead-samples/Lead-Update-Inbound-Sample.json)
## Sample outbound files
The following sample files show the structure of the JSON payload for a file sent from AWS to a partner.
The following links take you to GitHub.
+ [Opportunity](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/opportunity-samples/Opportunity-Outbound-Sample.json)
+ [Lead](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/lead-samples/Lead-Outbound-Sample.json)
## Sample processed results
The following files show a typical result after AWS processes a payload sent by a partner.
The following links take you to GitHub.
+ [Opportunity](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/opportunity-samples/Opportunity-Results-Success-Sample.json)
+ [Lead](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/lead-samples/Lead-Results-Success-Sample.json)
## Sample test cases
The following links take you to GitHub.
+ [Opportunity](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/opportunity-samples/Opportunity%20-%20Testing%20Scenarios.xlsx)
+ [Lead](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/lead-samples/Lead%20-%20Testing%20Scenarios.xlsx)
## Sample code snippets
The following links take you to GitHub.
+ [ace\$1read\$1s3.py](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/ace_read_s3.py)
+ [Apex\$1Sample\$1REST\$1API\$1Code.cls](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/Apex_Sample_REST_API_Code.cls)
+ [S3\$1Authentication.cls](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/S3_Authentication.cls)
+ [Sample\$1AceOutboundBatch.cls](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/Sample_AceOutboundBatch.cls)
+ [SFDC apex s3 sample.txt](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/SFDC_apex_s3_sample.txt)
+ [Apex\$1get\$1files\$1from\$1s3\$1ace\$1partner\$1test.cls](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/Apex_get_files_from_s3_ace_partner_test.cls)
+ [s3\$1ace\$1partner\$1test.cls](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/s3_ace_partner_test.cls)
# Lead sharing
## How AWS shares leads
1. **Incremental exports**: Amazon Web Services (AWS) exports new leads (and updates) referred by AWS, on an hourly basis.
1. **File creation**: AWS generates lead files adhering to a specific format. For detailed file specifications, refer to [Field definitions](resources.md#custom-field-definitions).
1. **File upload**: The lead files are uploaded to the `lead-outbound` folder.
## Consuming leads from AWS
To effectively consume leads from AWS, build custom integration with the following functionalities.
1. **File retrieval**:
+ Regularly scan the `lead-outbound` folder using a scheduled job at an interval you choose.
+ Retrieve the lead files for processing.
1. **Data transformation and mapping**:
+ After you read the content of each file, transform and map the data to the lead records in your customer relationship management (CRM) system.
+ For guidance on field mapping, refer to [Field mapping](custom-field-mapping.md).
1. **Lead identification**:
+ Uniquely identify each lead using either `partnerCrmLeadId` or `apnCrmUniqueIdentifier`.
+ If `partnerCrmLeadId` is blank and `apnCrmUniqueIdentifier` is present, the lead is a new referral from AWS Partner Network (APN) Customer Engagement (ACE).
+ If both identifiers are present, the record is treated as an update from ACE.
1. **Lead ingestion**:
+ Ingest new leads or update existing leads in the CRM system.
1. **File management**:
+ After you successfully process each lead and the complete file data, delete the files from the outbound folder.
+ Each file is automatically archived in the `lead-outbound-archive` folder.
**Integration and code reference**:
+ For reading files uploaded to the Amazon Simple Storage Service (Amazon S3) bucket, you can use AWS Lambda or read directly from your CRM system.
+ Use the sample codes below for Lambda and Salesforce REST API to validate and update CRM records.
+ **Lambda for validating files**: [ace\$1read\$1s3.py](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/ace_read_s3.py).
+ **Salesforce REST API**: [Apex\$1Sample\$1REST\$1API\$1Code.cls](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/Apex_Sample_REST_API_Code.cls).
+ If you use a CRM system other than Salesforce, you must provide code specific to your system to update your data.
## Sharing updates on leads with AWS
1. **Identify leads**: Locate the leads with updates to be shared with AWS.
1. **Data transformation**: Convert the data into the AWS format, as outlined in [Field definitions](resources.md#custom-field-definitions).
1. **File creation**:
+ Generate lead files in JSON format.
+ Append a timestamp to each file, ensuring all file names are unique and follow the format: `{name}_MMDDYYYY24HHMMSS.json`.
1. **Authenticate and upload**:
+ Authenticate to the ACE Amazon S3 bucket.
+ Upload the file to the `lead-inbound` folder. All files shared with AWS are automatically archived in the `lead-inbound-archive` folder.
+ When you upload files to S3, ensure you provide full access to the bucket owner.
```
aws s3 cp example.jpg s3://awsexamplebucket --acl bucket-owner-full-control
```
See a sample result of running this command in ["Results Sample file.json"](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/lead-samples/Lead-Results-Success-Sample.json).
1. **File processing**:
+ Upon receipt, AWS automatically processes the files.
+ The results of the processing is uploaded to the `lead-inbound-processed-results` folder in the Amazon S3 bucket. This includes the status of successes and errors, as well as any error messages for each lead.
+ These processed results are also archived in the `lead-inbound-processed-results-archive` folder.
+ For more information, refer to the [Technical FAQ—leads and opportunities](technical-faq-leads-and-opps.md).
1. **Response handling**:
+ You must develop logic to consume these responses, review erroneous records, correct any errors, and resend the data to ACE.
+ You can find sample errors in the FAQ and Troubleshooting sections.
+ To upload a file to Amazon S3 from CRM:
+ Reference the version of the AWS signature.
+ Use an HTTPS request to upload the file.
+ For reference, use the following files to upload a file to the Amazon S3 bucket:
+ **For authenticating an S3 bucket**: [S3\$1Authentication.cls](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/S3_Authentication.cls)
+ **For uploading files to an S3 bucket**: [Sample\$1AceOutboundBatch.cls](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/Sample_AceOutboundBatch.cls)
+ **NOTE:** Files must not exceed 1 MB in size, and duplicate files won’t be processed.
# Opportunity sharing
## How AWS shares opportunities
1. **Incremental exports**: Amazon Web Services (AWS) exports new opportunities (and updates) referred by AWS, on an hourly basis.
1. **File creation**: AWS generates opportunity files that adhere to a specific format. For detailed file specifications, refer to [Opportunity field definitions](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/opportunity-samples/Opportunity-Fields.csv).
1. **File upload**: Opportunity files are uploaded to the `opportunity-outbound` folder.
## Consuming opportunities from AWS
To effectively consume opportunities from AWS, you need to build custom integration with these functionalities.
1. **File retrieval**:
+ Use a scheduled job to regularly scan the `opportunity-outbound` folder, at an interval you choose.
+ Retrieve the opportunity files for processing.
1. **Data transformation and mapping**:
+ After you read the content of each file, transform and map the data to the opportunity records in your customer relationship management (CRM) system.
+ For guidance on field mapping, refer to [Field mapping](custom-field-mapping.md).
1. **Opportunity identification**:
+ Uniquely identify each opportunity using either `partnerCrmOpportunityId` or `apnCrmUniqueIdentifier`.
+ If `partnerCrmOpportunityId` is blank and `apnCrmUniqueIdentifier` is present, the opportunity is a new referral from AWS Partner Network (APN) Customer Engagement (ACE).
+ If both identifiers are present, the record is treated as an update from ACE.
1. **Opportunity ingestion**: Ingest new opportunities or update existing opportunities in the CRM system.
1. **File management**:
+ After you successfully process each opportunity and the complete file data, delete the files from the outbound folder.
+ Each file is automatically archived in the `opportunity-outbound-archive` folder.
**Integration and code reference**:
+ For reading files uploaded to the Amazon Simple Storage Service (Amazon S3) bucket, you can use AWS Lambda or read directly from your CRM system.
+ Use the sample codes below for Lambda and Salesforce REST API to validate and update CRM records.
+ **Lambda for validating files**: [ace\$1read\$1s3.py](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/ace_read_s3.py).
+ **Salesforce REST API**: [Apex\$1Sample\$1REST\$1API\$1Code.cls](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/Apex_Sample_REST_API_Code.cls).
+ If you use a CRM system other than Salesforce, you must provide code specific to your system to update your data.
## Sharing updates to opportunities with AWS
1. **Identify opportunities**: Locate the opportunities with updates to be shared with AWS.
1. **Data transformation**: Convert the data into the AWS format, as outlined in [Field definitions](resources.md#custom-field-definitions).
1. **File creation**:
+ Generate opportunity files in JSON format.
+ Append a timestamp to each file, ensuring all file names are unique and follow the format: `{name}_MMDDYYYY24HHMMSS.json`.
1. **Authenticate and upload**:
+ Authenticate to the ACE Amazon S3 bucket.
+ Upload the file to the `opportunity-inbound` folder. All files shared with AWS are automatically archived in the `opportunity-inbound-archive` folder.
+ When you upload files to S3, ensure you provide full access to the bucket owner:
```
aws s3 cp example.jpg s3://awsexamplebucket --acl bucket-owner-full-control
```
See a sample result of running this command in [Opportunity Results Success Sample.json](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/opportunity-samples/Opportunity-Results-Success-Sample.json).
1. **File processing**:
+ Upon receipt, AWS automatically processes the files.
+ The results of the processing is uploaded to the `lead-inbound-processed-results` folder in the Amazon S3 bucket. This includes the status of successes and errors, as well as any error messages for each opportunity.
+ These processed results are also archived in the `opportunity-inbound-processed-results-archive` folder.
+ For more information, refer to the [Technical FAQ—leads and opportunities](technical-faq-leads-and-opps.md).
1. **Response handling**:
+ You must develop logic to consume these responses, review erroneous records, correct any errors, and resend the data to ACE.
+ You can find sample errors in the FAQ and Troubleshooting sections.
+ To upload a file to Amazon S3 from CRM:
+ Reference the version of the AWS signature.
+ Use an HTTPS request to upload the file.
+ For reference, use the following files to upload a file to the Amazon S3 bucket:
+ **For authenticating an S3 bucket**: [S3\$1Authentication.cls](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/S3_Authentication.cls)
+ **For uploading files to an S3 bucket**: [Sample\$1AceOutboundBatch.cls](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/Sample_AceOutboundBatch.cls)
+ **NOTE:** Files must not exceed 1 MB in size, and duplicate files won’t be processed.
# Field mapping
Field mapping is an essential step in the integration process where partners align their customer relationship management (CRM) system’s fields with those defined by Amazon Web Services (AWS). This ensures that both parties accurately exchange and understand data. Below are guidelines to assist in this process.
## Mandatory field mapping
+ Map each mandatory field to its corresponding field in your CRM system. It’s essential for successful data exchange when you ensure all required fields are mapped. For more information, refer to [Field definitions](resources.md#custom-field-definitions)
+ [Opportunity](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/opportunity-samples/Opportunity-Fields.csv)
+ [Lead](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/lead-samples/Leads-Fields.csv)
## Handling optional fields
+ Understand the role of optional fields in the integration process. Decide if you want to map these fields based on your business requirements, and be aware of any possible implications from leaving them unmapped.
## Value mapping
+ Align each field value in your CRM with the required AWS Partner Network (APN) Customer Engagement (ACE) list value, as specified in [Field definitions](resources.md#custom-field-definitions). This is important to maintain data consistency and integrity.
## Data type and format validation
+ Verify that the data types and formats of the fields in your CRM system align with those specified in the AWS *Field definitions*. It’s essential to maintain consistency in data types and formats to prevent data corruption and ensure seamless integration.
## Field length and limitations
+ Notice field length restrictions and other limitations. Ensure that the data from your CRM system fits into the corresponding fields in AWS without being truncated or causing errors.
## Data type and format validation
+ Verify that the field data types and formats in your CRM system align with those specified in [Field definitions](resources.md#custom-field-definitions). It’s crucial to prevent data corruption and ensure seamless integration with consistency in data types and formats.
## Periodic review and update
+ Regularly review and update your field mappings to accommodate changes in your CRM system or AWS requirements. This proactive approach ensures ongoing data exchange accuracy and efficiency.
## Field mapping documentation
+ Maintain comprehensive field mapping documentation. This practice aids in troubleshooting, future updates, and ensuring clarity in how data is transferred between systems.
## Testing and validation
+ Conduct thorough field mappings testing to validate that data is being transferred and transformed accurately. Address any discrepancies or issues immediately to ensure data integrity.
## Handling unwanted overwrites
+ To prevent AWS data from overwriting specific CRM fields, consider the following:
+ Creating a custom CRM field for the data you want to protect.
+ Having this custom field reviewed by a sales representative.
+ Once the custom field is approved, adding it to the opportunity record and pipeline.
+ This is particularly important for fields like `MRR` or `Stage`, especially if they signify that a product has launched.
## Managing downstream dependencies
+ If there are downstream dependencies in your system that rely on data exchange, consider the following:
+ Creating new fields in your CRM to accommodate the AWS data.
+ Realigning your business processes as necessary to ensure seamless integration and data flow.
# Creating synchronization schedules
**Note**
The topics in this section assume you've completed the prerequisites for an AWS Partner Central integration, an AWS Marketplace integration, or both. For more information, refer to [Integration prerequisites](crm-integration-setting-up.md) and [Getting started](crm-integration-getting-started.md) earlier in this guide.
You can create inbound and outbound synchronization schedules between Salesforce and AWS Partner Central. The steps in the following sections explain how.
**Topics**
+ [Prerequisites](#scheduling-prerequisites)
+ [Creating a schedule](#creating-a-schedule)
+ [Deactivating a scheduled job](#deactivating-a-scheduled-job)
+ [Viewing all schedules](#viewing-all-schedules)
## Prerequisites
Ensure that you complete the following before creating a synchronization schedule:
+ [Map](crm-connector-mapping.md) all required fields on at least one object, opportunity, or lead.
+ Create a [system integration user](#system-integration-user) in Salesforce.
### Creating a system integration user
Before you can create a synchronization schedule, you must use Salesforce to create a system integration user with APN integration permissions. To create synchronization schedules, you must sign in to Salesforce as the system integration user. Creating a schedule without APN integration user permissions can break the APN integration.
**To create a system integration user**
1. Sign in to your Salesforce organization as a system administrator.
1. Create a user in your Salesforce organization. Assign a profile to the user with access to the required objects in your Salesforce organization. For more information, refer to [Add a single user](https://help.salesforce.com/s/articleView?id=sf.adding_new_users.htm).
1. Assign the user the **APN Integration User** permissions set. For more information, refer to [Assign permission set to users](https://help.salesforce.com/s/articleView?id=sf.assign_permission_set_to_user.htm).
## Creating a schedule
After completing the [prerequisites](#scheduling-prerequisites), you can create synchronization schedules between Salesforce and APN.
**To create a synchronization schedule with APN**
1. Sign in to Salesforce as a user with system integration user permissions.
1. On the **Schedules** tab, choose **New**.
1. Choose the objects to schedule. You can set up schedules for leads and opportunities, or for a single object.
1. Choose the schedule frequency, from a minimum of every five minutes to a maximum of once a day.
1. Choose **Schedule**.
**Note**
Only one schedule per object can be active at one time. Creating a new schedule for the same object deactivates the existing schedule.
To disable the inbound integration when creating a schedule, choose **Disable Inbound Integration, Schedule**.
Creating a schedule without APN integration user permissions can break the APN integration.
## Deactivating a scheduled job
1. On the **Scheduling** page, choose **Deactivate All Jobs** to turn off any active schedules.
1. Proceed through the confirmation screen to deactivate the synchronization schedule.
## Viewing all schedules
From the **Schedules** tab, use the list view filters to toggle between **Active**, **Inactive**, and **All synchronization** schedules.
# Best practices
Use these best practices to optimize your custom integration development and maintenance.
## General best practices
1. Map all *mandatory* fields because they are the required fields in the AWS Partner Network (APN) Customer Engagement (ACE) submission form.
1. Connect with your current ACE Pipeline Manager user to understand what the process looks like. Capture any unique processes/field uses, so you can build it into your experience.
1. Consider creating separate sales pipeline stages for Amazon Web Services (AWS)-reported sales stages (example: Stage, Target Close Date, Expected Monthly AWS revenue, Next Steps). If we have different stage definitions, we might override your sales stages. When you create separate sales stages, it allows you to manage your pipeline appropriately, but still have visibility into what AWS is projecting.
1. For partner referred opportunities, the ACE team must approve/reject them before we accept any updates.
1. For AWS referred opportunities, the partner must accept or reject the opportunities.
## Data exchange protocols
1. **Input conventions**: Separate multi-select picklist entries with semicolons and omit spaces.
1. **Attention to detail**: Field names and values are case-sensitive, so maintain accuracy.
1. **Deletion procedures**: Execute field removal by transmitting the value `null` for the chosen field.
1. **Synchronization**: The synchronization processes operate on an hourly basis, causing potential delays in data reflections. Updates to AWS can take up to one hour to reflect in the AWS customer relationship management (CRM). Avoid sending multiple documents per hour.
## Field-specific best practices
1. **Inbound modifications**: To protect the integrity of your data, disable modifications for fields such as `stage`, `closedDate`, and `closedLostReason`. To track AWS values without affecting your local Salesforce values, use these read-only fields: `awsStage`, `awsCloseDate`, and `awsClosedLostReason`.
1. **Customer mapping and validation**: Ensure customer website accuracy because it’s pivotal for AWS CRM mapping. Pair it with the customer name for superior CRM account mapping.
1. **Project description clarity**: Furnish a clear description detailing customer challenges and solution alignments. AWS uses this to validate the opportunity.
1. **Provisioning**: (Optional) When you provision end-customer contact specifics, it enables AWS to retrace leads and campaigns. This leads to enhanced funding verdicts.
## Additional best practices
1. Adhere to the latest payload field definition guidelines.
1. Maintain sandbox bucket naming consistency with the specified format.
1. Use the recommended naming pattern for the production bucket.
1. Prioritize sandbox environment testing before live deployment.
1. Maintain distinct identifiers for records between AWS and partner CRMs.
1. Post-processing, delete files in the outbound Amazon Simple Storage Service (Amazon S3) folder. Originals remain in the archives.
1. To prevent errors, set up field level validations at the source.
# Quotas
## Inbound file to Amazon Web Services (AWS)
| Operation | Limit |
| --- | --- |
| Maximum opportunities | 500 per file |
| Maximum file size | 1 MB |
| Frequency of synchronization | Near real-time |
| Maximum number of submitted files | 10,000 per 24-hour period |
## Outbound file to partner
| Operation | Limit |
| --- | --- |
| Maximum file size | 5 MB |
| Frequency of synchronization | Hourly |
# Version history
Current fields version: 14 (November 15, 2023)
The following table describes important changes to the custom integration fields for leads and opportunities after 2020. To be notified of future updates, subscribe to the RSS feed.
| Change | Version | Date |
| --- | --- | --- |
| Update Amazon S3 quotas | 14 | 1/17/2024 |
| **Changes to integration opportunity fields:** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/partner-central/latest/crm/version-history.html) | 14 | 11/15/2023 |
| **Changes to integration opportunity fields:** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/partner-central/latest/crm/version-history.html) | 13 | 03/29/2023 |
| **Changes to integration opportunity fields:** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/partner-central/latest/crm/version-history.html) **Changes to standard values on opportunity:** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/partner-central/latest/crm/version-history.html) | 12 | 09/01/2022 |
| **Changes to integration opportunity fields:** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/partner-central/latest/crm/version-history.html) **Changes to standard values on opportunity fields:** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/partner-central/latest/crm/version-history.html) | 11 | 03/21/2022 |
| **Changes to integration opportunity fields:** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/partner-central/latest/crm/version-history.html) **Changes to standard values on opportunity:** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/partner-central/latest/crm/version-history.html) | 10 | 01/26/2022 |
| **Changes to standard values on lead fields:** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/partner-central/latest/crm/version-history.html) **Changes to integration lead fields:** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/partner-central/latest/crm/version-history.html) **Changes to integration opportunity fields:** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/partner-central/latest/crm/version-history.html) | 9 | 9/16/2021 |
| Update Closed Lost reason codes | 8 | 6/24/2021 |
# FAQs
Use these common questions and answers to assist in the custom integration.
**Topics**
+ [General FAQ](general-faq.md)
+ [Technical FAQ—fields](technical-faq-fields.md)
+ [Technical FAQ—Amazon S3](technical-faq-s3.md)
+ [Technical FAQ—leads and opportunities](technical-faq-leads-and-opps.md)
+ [Technical FAQ—versioning and backward compatibility](technical-faq-versioning.md)
# General FAQ
## How does the integration work?
**Q: Can I access the Amazon Simple Storage Service (Amazon S3) bucket used for sending and receiving the files?**
Yes. Partners can programmatically access the Amazon S3 bucket using the secret/access key of the AWS Identity and Access Management (IAM) that has access to the bucket. Partners won’t have console access to the Amazon S3 buckets because these buckets are in Amazon Web Services (AWS)’s own account.
**Q: What skill set does the partner's developer need?**
The partner’s developer needs to be familiar with their customer relationship management (CRM) system and Amazon S3.
**Q: Do the sample code files include complete code or does the partner have to write the code?**
The partner needs to write the code based on the provided sample code files.
**Q: If the partner develops their solution in Python, Golang, or any other language, does AWS Partner Network (APN) Customer Engagement (ACE) provide any software development kit (SDK) in those languages for this integration?**
No.
**Q: What is the sync process from the Amazon S3 bucket to internal ACE?**
Every hour, a batch process runs to pick up the files and synchronize information. Any update the AWS sales team makes on the record can take up to one hour to be sent to the partner’s bucket. Partners may receive an email notification about updates immediately, but the updates from AWS may still be delayed by one hour.
**Q: What is the frequency of lead and opportunity file uploads by ACE?**
ACE sends the leads and opportunities data every one hour.
**Q: Is there a sandbox environment for ACE?**
Yes. We do have a sandbox environment for ACE, but we can’t provide access to partners due to security reasons. Raise a support case on Partner Central if you want to have new opportunities or leads pushed into your bucket.
**Q: How do we maintain identifiers across the partner’s CRM and APN?**
To provide more flexibility for our partners, we use two sets of identifiers in our system.
1. `apnCrmUniqueIdentifier`: AWS manages this identifier. It starts with `OXXXXXX` for opportunities and `LXXXXXX` for leads.
1. `PartnerCrmUniqueIdentifier`/`partnerCrmLeadId`: The partner manages this identifier on opportunities and leads, respectively, within their CRM. Partners should add this identifier while ingesting new opportunities to trace updates back to their CRM.
When an opportunity is sent without `apnCrmUniqueIdentifier` or `partnerCrmUniqueIdentifier`, AWS treats it as a new opportunity and assigns a new `apnCrmUniqueIdentifier` for the opportunity.
When an opportunity is sent with a `apnCrmUniqueIdentifier` or `partnerCrmUniqueIdentifier`, AWS treats it as an update action and updates the existing opportunity with the payload data.
**Q: How do I prevent duplicate records from getting created in both systems?**
From the partner CRM side, there must be a unique identifier for each record that’s sent to ACE, which is called `partnerCrmUniqueIdentifier`. Similarly, ACE also maintains a unique identifier for each record, which is called `apnCrmUniqueIdentifier`. When the data is sent, both ACE and the partner have to include these two fields, which helps to identify if the record is a new opportunity (if blank) or an existing opportunity (if populated).
# Technical FAQ—fields
**Q: Does the integration support CSV format?**
No. The integration accepts only JSON file formats.
**Q: When do the files have to be deleted from outbound folders?**
Delete the files only after you successfully process them.
**Q: If I accidentally delete the files from outbound folders, where can I find the original files?**
The files are available in the `opportunity-outbound-archive` and `lead-outbound-archive` folders.
**Q: What do I do for support during development?**
For assistance during development, reach out to AWS Partner Network (APN) support on Partner Central.
**Q: What is the difference between `opportunityOwnerName` and `opportunityOwnerEmail`?**
+ `opportunityOwnerName`: The opportunity owner’s name in the partner organization. This needs to be a Partner Central user.
+ `opportunityOwnerEmail`: The opportunity owner’s email in the partner organization. This needs to be a Partner Central user. If not provided, the opportunity is created with the Partner Central Alliance Lead as the owner.
**Q: What's the time zone for all the date fields (`targetCloseDate`, `lastModifiedDate`, `createdDate`, and `acceptBy`)?**
The time zone for the date fields is Greenwich Mean Time (GMT).
**Q: Are the inbound JSON files versioned?**
No. Amazon Web Services (AWS) doesn’t support versioning of the files. APN Customer Engagement (ACE) processes the file immediately after receiving and then deletes the file after successful processing. If we receive the same file name again, it’s rejected.
**Q: What fields in the Amazon Simple Storage Service (Amazon S3) JSON file indicate the creation and latest update date of a particular lead and opportunity?**
`createdDate` and `lastModifiedDate`.
**Q: How do you determine if an opportunity is new or existing?**
The field `PartnerCrmUniqueIdentifier` is a unique identifier on each opportunity that we require from the partner. This identifier must be defined in the source CRM of the partner's system. We use this to determine if an opportunity exists in AWS. If it exists, we update the opportunity with the shared information. If not, we create a new opportunity.
When we send data to the partner, we include both `PartnerCrmUniqueIdentifier` and `apnCrmUniqueIdentifier`. If the opportunity shared by AWS is being sent for the first time, you won’t see any value for `PartnerCrmUniqueIdentifier`. This helps you to treat the opportunity as new from ACE. Once you ingest it into your CRM, you send the updates back to us with both `PartnerCrmUniqueIdentifier` and `apnCrmUniqueIdentifier`.
**Q: Is it possible to have more than one outbound and result JSON file in Amazon S3?**
Yes. Sometimes we may generate more files in the outbound folder. Similarly, if you send files to the inbound folder, we process them and keep the results files in the result folder. You must tag or delete the result files after processing.
**Q: Does the outbound file contain more than one record?**
Yes. The outbound file can contain multiple records.
**Q: If 20 inbound opportunities are sent in a single input JSON file under the opportunities section, and one of the opportunities doesn’t comply with APN standard, what happens?**
If the format is incorrect, regardless of the case, the entire file is rejected. If the format is correct but only one opportunity can’t be processed on our end, the results file includes all 20 opportunities and their status, along with the error message for the failed opportunity.
**Q: What are the key attributes to validate if the JSON file was processed successfully?**
These are the key attributes to help you understand if the JSON file processed successfully.
```
{
"inboundApiResults": [
{
"warnings": null, // no warnings
"partnerCrmUniqueIdentifier": "XXXX", //uniqueId from Partner side
"isSuccess": true, // file successfully processed
"errors": null, //no errors reported
"apnCrmUniqueIdentifier": "OXXXX" //uniqueId from AWS side
}
]
}
```
**Q: What happens if I send an invalid JSON?**
You receive this error response: "`[{input JSON}]` is not of type `object`".
**Q: How many lead/opportunity records can be included in a single inbound JSON file?**
A maximum of 50 records can be in one file.
# Technical FAQ—Amazon S3
**Q: Where can I get the Amazon Simple Storage Service (Amazon S3) REST API documentation?**
For more information, refer to the [Amazon S3 REST API Introduction](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html).
**Q: How do I get the Amazon Web Services AWS Key Management Service (AWS KMS) key details to authenticate to access the Amazon S3 bucket?**
AWS Partner Network (APN) shares a policy that includes the key name.
**Q: How do I authenticate Amazon S3 from Salesforce.com (SFDC)?**
Use the sample code file [S3\$1Authentication.cls](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/S3_Authentication.cls) to authenticate the Amazon S3 from SFDC.
**Q: How do I upload the file from the AWS software development kit (SDK) to S3?**
Use the following AWS CLI command to upload the file to S3.
```
aws s3 cp example.json s3://awsexamplebucket/opportunity- inbound/filename.json --acl bucket-owner-full-control
```
The sample code file [Sample\$1AceOutboundBatch.cls](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/code-snippets/Sample_AceOutboundBatch.cls) contains code to upload the data file from SFDC.
**Q: Who owns the Amazon S3 bucket?**
AWS owns and manages the Amazon S3 bucket. You have programmatic access to your own Amazon S3 bucket with the AWS Identity and Access Management (IAM) user.
**Q: Are there separate folders or buckets for receiving and sending files?**
There is one bucket with different folders for receiving and sending the files. Refer to the user guide for further details on the folders.
**Q: Do I need to access the Amazon S3 bucket using AWS Lambda, or can I access it directly using the customer relationship management (CRM) system?**
You can access it both ways.
**Q: Is the Amazon S3 bucket secured or encrypted?**
Yes. We enable the default encryption mechanism that Amazon S3 offers.
**Q: Is it possible to enable Amazon Simple Notification Service (Amazon SNS) listening to the Amazon S3 bucket, so I can only act on the event, instead of polling periodically?**
No. Currently, APN Customer Engagement (ACE) doesn’t support this feature.
**Q: What folders do I have access to and what is the purpose of each folder?**
You can find the list of Amazon S3 folders in [Integration prerequisites](crm-integration-setting-up.md).
# Technical FAQ—leads and opportunities
## Send and receive leads and opportunities
**Q: Is there a file naming convention?**
Each file name needs to be unique. We recommend the file name `PartnerProvided FileName+{timestamp}.json`.
**Q: What's the structure of the results?**
Sample files for the results (success and error) can be downloaded from the following locations:
+ [Lead Results Success Sample.json](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/lead-samples/Lead-Results-Success-Sample.json)
+ [Opportunity Results Success Sample.json](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/opportunity-samples/Opportunity-Results-Success-Sample.json)
+ [Lead Results With Errors Sample.json](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/lead-samples/Lead-Results_With-Errors-Sample.json)
+ [Opportunity Results With Errors Sample.json](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/opportunity-samples/Opportunity-Results_With-Errors-Sample.json)
**Q: What's the naming convention of the results?**
`PartnerProvidedFileName_result.json`
**Q: What if I submit a second JSON file with the same name?**
We won’t process the file, and the file is moved to the archive folder.
**Q: What is the inbound file size limit?**
The inbound file size limit is 1MB.
**Q: Is there a maximum number of opportunities and leads that can be batched into one JSON file?**
Given the 1MB limit, we recommend you have one opportunity or lead per file.
**Q: I’m getting an access denied error message, so I’m not able to upload the files. What should I do?**
Partners receive an *Access denied* message for two reasons.
1. You uploaded the file into the `outbound` folder instead of the `inbound` folder. Upload the file into the `inbound` folder.
1. You need to provide a access control list (ACL). Use the following Amazon Web Services (AWS) CLI command for uploading the data file:
```
aws s3 cp example.json s3://awsexamplebucket --acl bucket-owner-full-control
```
**Q: What happens if files with extensions such as `.pdf`, `.docx`, or anything other than `.json` are uploaded?**
We reject the files and generate a `*.error.json` file with the reason details.
**Q: What do I do after I receive a data issue error message in production?**
1. If the data needs to be corrected in the partner’s customer relationship management (CRM) system, after you correct the data, send the revised file to Amazon Simple Storage Service (Amazon S3).
1. If any clarifications are required for the data, reach out to your Partner Development Manager (PDM).
1. For any other technical support, raise an AWS Partner Network (APN) support case in the APN Portal.
**Q: Where can I find the results files and how long are they available?**
The results files are in the `lead-inbound-results` and `opportunity-inbound-results` folders. They're available until you delete them. You can delete the files after successful pull.
**Q: If I need to find a results file after I delete it, where can we find it?**
You can find the results files in the `lead-inbound-results-archive/YYYY/MM/DD` and `opportunity-inbound-results-archive/YYYY/MM/DD` folders.
**Q: If there is any failure in APN processing the file, how am I notified?**
APN has alarms that automatically create Sev2 tickets to track the processing errors. We review, resolve, and communicate these to partners.
**Q: What fields can be updated after the opportunity is launched?**
The following fields can be updated only by Independent Software Vendor (ISV) Accelerate Partners:
+ `isThisForMarketplace`
+ `isNetNewBusinessForCompany`
+ `deliveryModel`
+ `awsFieldEngagement`
+ `additionalComments`
**Q: I received a *Record not editable* error. What does it mean?**
When a you send a new partner referred opportunity, it goes through the validation process and the APN Customer Engagement (ACE) team must approve or reject it. While the opportunity is in review and has not yet been validated, you can’t update the record, and you receive this error.
**Q: What happens if there is no activity on the my side (example: I'm not processing the file or not sending any inbound opportunity)?**
If you don't send any information or aren't processing the files we provide, we currently don’t have a mechanism in place to alert you. We encourage you to monitor your system to ensure the information is flowing to APN.
**Q: How soon are the JSON results available in the results folder following the submission of a new/updated inbound opportunity/lead?**
The processing is almost real time. You should receive the files in less than five minutes.
**Q: If I send an inbound opportunity CRM that doesn’t comply with the format/length restriction of the APN standard, how does the system handle it? Does it generate the error report?**
If the file isn't in the field definition format, the result file from APN calls out the file.
**Q: I don’t have an AWS account ID at the time of launching. What do I do?**
Per the ACE process, `Launched` means workload completed and billing started. This requires an AWS account ID. For more information, refer to the [ACE Program FAQs](https://partnercentral.awspartner.com/partnercentral2/s/resources?Id=0690h000003xjjXAAQ).
**Q: Following User Acceptance Testing (UAT), how should the historical data be handled during the move to production?**
By default, when any updates happen in ACE, we send those opportunities to the Amazon S3 bucket. For historical data that you don’t want to process, you need to provide the `partnerCrmUniqueIdentifier` with dummy values such as `X0001, X0002….X000N` in the extract for what you don’t want to process in your system. You need to write code to recognize these identifiers and process them accordingly. The rest of the opportunities provide the correct `partnerCrmUniqueIdentifier` value. This ensures that you have full control on what to process and what not to process in your system.
**Q: Does the outbound file contain more than one record?**
Yes. The outbound file can contain more than one record.
**Q: Why does the data send *Accept to view* for some fields?**
For an AWS referred opportunity or lead, all PII fields are masked with the label *Accept to view* until the opportunity or lead is accepted by you. Once accepted, you receive all data fields in the next sync cycle.
**Q: What do I do when a new AWS referred opportunity or lead is synced for the first time?**
When a new opportunity or lead is synced for the first time, you need to accept or reject it to get additional data (example: customer contacts).
## Creating and updating opportunities/leads
**Q: How do I ingest new *Partner Referred (Originated)* opportunities into ACE through the integration?**
To create new opportunities in ACE through the integration, you need to ingest the required opportunity information in the defined JSON format into the `opportunity-inbound` folder. AWS processes this information, creates a new opportunity in ACE, and shares results of a successful/failed create operation in the `opportunity-inbound-processed-results` folder.
**Q: How does the integration differentiate between new opportunity submissions and updates?**
The field `PartnerCrmUniqueIdentifier` on each opportunity is a required unique identifier required. This identifier must be defined in the your system source CRM. AWS uses this to determine if an opportunity already exists in ACE. If it's available in ACE, we use the information shared to update the opportunity, but if it's not available in ACE, we use the information shared to create a new opportunity.
**Q: If I’ve already implemented the update functionality through the integration, what do I need to do to use the integration to submit (create) new opportunities?**
You need to make the following changes to the existing integration:
1. Start ingesting new opportunities for creation in the `opportunity-inbound` folder. Provide updates in the same folder.
1. Ensure that the mandatory fields required to create are available in the Opportunity JSON shared.
1. Verify each new opportunity has a unique `PartnerCrmUniqueIdentifier` that doesn’t exist in ACE/Partner Central. An important go-live best practice is to map and update the existing data in ACE to each `PartnerCrmUniqueIdentifier` in your CRM so we don’t create duplicates when we receive updates. For assistance, contact ACE.
**Q: As part of the go-live process, how do I update existing opportunities in ACE with my `PartnerCrmUniqueIdentifier`?**
The ACE team supplies you with a list of all open opportunities to aid in preparation for the production launch. You must map these existing opportunities in ACE to their respective `PartnerCrmUniqueIdentifier`, and return the updated file to ACE for integration into AWS’s CRM.
If you choose to sync only a subset of the opportunities AWS provides, you must develop logic to bypass AWS updates for any opportunities you don’t want to process. This approach should also be applied to future opportunities, post-onboarding. You must supply the associated `partnerCrmUniqueIdentifier` for opportunities that need alignment across both CRMs. Additionally, you should indicate which opportunities you won’t be updating (example: Marking closed-lost or closed-won opportunities) to exclude them from updates. It’s important that all open/active opportunities that AWS shares, and you accept, are assigned a `partnerCrmUniqueIdentifier`.
**Q: Can I update only specific fields in the opportunity or lead?**
Yes. You can provide only the fields that require updates, along with the necessary identifiers.
**Q: Is it possible to change the *ApnCrmUniqueIdentifier***?
No. This identifier remains constant for AWS and uniquely identifies each opportunity.
**Q: What if I provide an incorrect *partnerCrmUniqueIdentifier***?
If you provide an incorrect identifier, a new opportunity is created. Ensure accuracy to avoid data duplication.
**Q: Can I update opportunities that AWS submitted?**
Yes. You can update opportunities AWS submitted using the correct `partnerCrmUniqueIdentifier`.
**Q: How soon can I expect results for submitted opportunities?**
The processing is almost real time, and results are usually available within a few minutes in the `opportunity-inbound-processed-results` folder.
**Q: What should I do if there are processing errors for opportunities submitted?**
Review error details in the results files, address issues, and seek further assistance from the ACE support team.
**Q: Can I delete an opportunity through the integration?**
No. Direct deletion is not supported. You can update an opportunity to reflect a *Closed* status.
**Q: What does the *Record not editable* error mean?**
This error occurs if you try to update an opportunity in ACE review. These opportunities can’t be edited until validated.
**Q: What if don't send updates or new opportunities?**
No new data is received and processed if you don't send updates or new opportunities through the integration.
**Q: How long are the results files available?**
Results files are available for a reasonable duration. You should retrieve and manage them promptly.
# Technical FAQ—versioning and backward compatibility
**Q: What is a payload in Amazon Web Services (AWS) data exchange?**
A payload is a structured piece of data formatted in JSON, sent either inbound to AWS or outbound from AWS. Each key in this JSON structure is referred to as a *field*, and each field has an associated *value.*
**Q: How is the payload version determined?**
Payload version is specified within the `version` field of the payload itself. Payloads adhering to field definition v13 are considered Payload Version 1.0, while those following the format defined in field definition v14 or higher are referred to as Payload Version 2.0.
**Q: What does backward compatibility mean in this context, and how is it handled?**
Backward compatibility ensures that existing opportunities don’t fail when new and mandatory fields are introduced in newer payload versions. AWS maintains this by auto-assigning default values to fields required in the new version. You might notice values in the AWS Partner Network (APN) Customer Engagement (ACE) UI that you did not explicitly provide through the Customer Relationship Management (CRM) Integration. Details and conditions for each field are explained in the field description or additional details about the field.
**Q: Is backward compatibility a permanent feature?**
No. Backward compatibility is time-bound, designed to provide flexibility for you to plan and implement upcoming changes. It stops working beyond a specified cut-off date, which will be announced later in the year as part of a wider launch.
**Q: What happens when I start sending payloads with version 2.0?**
Once you send a payload with version 2.0, the system assumes that all necessary changes have been implemented, and validations for the new payload version apply to all subsequent changes. It’s essential that you don't implement features partially between version 1.0 and version 2.0 payloads.
**Q: Can I revert back to payload version 1.0 after updating to version 2.0?**
No. Transitioning to payload version 2.0 is a one-way process. Once you update to version 2.0, you can't revert back to version 1.0 of the payload.