# 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.