Update Marketplace SaaS Setup Instructions

[gbroques]

I'm on step 2 under Marketplace Saas Setup Instructions in the README titled "Create a SaaS Product in AWS Marketplace".

I'm concerned because this section says "NOTE: These instructions are now out of date!"

I received an email about integrating my SaaS Subscription listing with the AWS Marketplace API.

There are three integration tasks to complete:

1. Customer registration – When a customer subscribes to your service from AWS Marketplace, they will be redirected via an HTTP POST to your registration page. In the POST request will be a form field named x-amzn-marketplace-token. This token can be redeemed via an AWS API call to ResolveCustomer to determine the customer ID of the subscriber and the product code of the service they subscribed too. You should save this alongside any registration information as you will need it when reporting metering usage.
2. Report usage information – Each hour, you need to report usage information for each customer. You do this via an API call to BatchMeterUsage, sending up to 25 metering records at a time. You would send 1 record per customer per dimension. Each call would include the Customer ID, Dimension Name, Usage Quantity and UTC timestamp.
3. Handle Subscription events – When a customer subscribes or unsubscribes from your service, messages are sent to an SNS topic created by AWS for your service. It’s a good practice to subscribe an SQS queue to the topic, then read the messages from the queue. This way you won’t lose messages if your service is unavailable. The most important event to handle is the unsubscribe-pending. If you receive this for a customer, you will have 1 hour to report any final usage. After an hour you will receive an unsubscribe-success message, at which time no more metering records can be sent for that customer.

How do I complete each of these integration tasks using the AWS API Gateway Developer Portal framework?

Do steps 3 - 6 under Marketplace SaaS Setup Instructions in the README complete these integration tasks?

3. Update your Usage Plan with the AWS Marketplace Product Code via API Gateway "UpdateUsagePlan" API: "aws apigateway update-usage-plan --usage-plan-id [USAGE_PLAN_ID] --patch-operations '[{ "path" : "/productCode", "value" : "[MARKETPLACE_PRODUCT_CODE]", "op" : "replace" }]'"

4. Update marketplaceSubscriptionTopic in package.json with the AWS Marketplace Product Code

5. Update CloudFormation stack via 'npm run update-stack'

6. Subscribe your listener function to your subscription topic via 'npm run subscribe-listener

Help and guidance on how to integrate my Developer Portal and product listing with AWS Marketplace would be greatly appreciated!

[gbroques]

Looks like step 4 under Marketplace SaaS Setup Instructions became out-of-date in commit 406f84d.

You now don't have to update "marketplaceSubscriptionTopic" in package.json.

Looks like the following code in the static-asset-uploader lambda automatically pulls the AWS Marketplace Product Code as some MarketplaceSuffix property on the Lambda event object?

let suffix = event.ResourceProperties.MarketplaceSuffix
if(suffix !== 'DevPortalMarketplaceSubscriptionTopic') {
    configObject.marketplaceSubscriptionTopic = `arn:aws:sns:us-east-1:287250355862:aws-mp-subscription-notification-${suffix}`
}

---

EDIT: Upon further digging, it appears you're now supposed to pass it as a parameter override to the cloud formation template using the sam deploy command like such:

sam deploy \
    --template-file ./cloudformation/packaged.yaml \
    --stack-name "dev-portal" \
    --s3-bucket dev-portal-bucket \
    --capabilities CAPABILITY_NAMED_IAM \
    --parameter-overrides 
        MarketplaceSubscriptionTopicProductCode="YourMarketplaceProductCode"

[gbroques]

I found the no longer existing npm run subscribe-listener command that's referenced in step 6 that was added to package.json in commit f20871390e.

 "subscribe-listener": "aws sns subscribe --topic-arn $npm_package_config_marketplaceSubscriptionTopic --protocol lambda --notification-endpoint arn:aws:lambda:$npm_package_config_primaryAwsRegion:$npm_package_config_accountId:function:$npm_package_config_listenerLambdaFunctionName --region us-east-1",

It's unclear whether or not this, or a similar command still needs to be ran to complete integration with the AWS Marketplace.

[gbroques]

The alleged npm run update-stack mentioned in step 5 never seemed to exist in the first place as that README instruction was added in commit f20871390e, but the update-stack command wasn't added to the scripts in package.json in the same commit.

Would running a sam package and sam deploy command be equivalent to "updating the stack"?

[gbroques]

I performed step 3 by using the AWS Console GUI:

1. Navigate to API Gateway
2. Navigate to Usage Plans in the left-hand sidebar
3. Click the usage plan you registered in step 2 when you created your Product Listing
4. Click the Marketplace tab
5. Paste your Product Code in the Product Code text box and click the Save button.
   • You should've received your Product Code in an email when you registered your product listing in step 2 of Marketplace SaaS Setup Instructions.

[okigan]

+1 please update / streamline aws market place integration docs