Update to version v1.0.0

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,42 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior.
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Please complete the following information about the solution:**
+- [ ] Version: [e.g. v1.0.0]
+
+To get the version of the solution, you can look at the description of the created CloudFormation stack. For example, "_(SO0126) - Cognito User Profiles Export Reference Architecture. Version **v1.0.0**_". If the description does not contain the version information, you can look at the mappings section of the template:
+
+```yaml
+Mappings:
+  SourceCode:
+    General:
+      S3Bucket: "solutions"
+      KeyPrefix: "cognito-user-profiles-export-reference-architecture/v1.0.0"
+```
+
+- [ ] Region: [e.g. us-east-1]
+- [ ] Was the solution modified from the version published on this repository?
+- [ ] If the answer to the previous question was yes, are the changes available on GitHub?
+- [ ] Have you checked your [service quotas](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html) for the sevices this solution uses?
+- [ ] Were there any errors in the CloudWatch Logs?
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem (please **DO NOT include sensitive information**).
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea for this solution
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the feature you'd like**
+A clear and concise description of what you want to happen.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,5 @@
+*Issue #, if available:*
+
+*Description of changes:*
+
+By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2020-08-31
+### Added
+- Launch Cognito User Profiles Export Reference Architecture

CODE_OF_CONDUCT.md

@@ -1,4 +1,4 @@
 ## Code of Conduct
-This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
-For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
+This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). 
+For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact 
 [email protected] with any additional questions or comments.

CONTRIBUTING.md

@@ -11,7 +11,7 @@ information to effectively respond to your bug report or contribution.
 
 We welcome you to use the GitHub issue tracker to report bugs or suggest features.
 
-When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already
+When filing an issue, please check [existing open](https://github.com/awslabs/cognito-user-profiles-export-reference-architecture/issues), or [recently closed](https://github.com/awslabs/cognito-user-profiles-export-reference-architecture/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aclosed%20), issues to make sure somebody else hasn't already
 reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
 
 * A reproducible test case or series of steps
@@ -41,7 +41,7 @@ GitHub provides additional document on [forking a repository](https://help.githu
 
 
 ## Finding contributions to work on
-Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
+Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels ((enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any ['help wanted'](https://github.com/awslabs/cognito-user-profiles-export-reference-architecture/labels/help%20wanted) issues is a great place to start.
 
 
 ## Code of Conduct
@@ -56,6 +56,6 @@ If you discover a potential security issue in this project we ask that you notif
 
 ## Licensing
 
-See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
+See the [LICENSE](https://github.com/awslabs/cognito-user-profiles-export-reference-architecture/blob/master/LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
 
 We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes.

LICENSE → LICENSE.txt

@@ -172,4 +172,4 @@
       of any other Contributor, and only if You agree to indemnify,
       defend, and hold each Contributor harmless for any liability
       incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
+      of your accepting any such warranty or additional liability.

NOTICE.txt

@@ -0,0 +1,19 @@
+Cognito User Profiles Export Reference Architecture
+Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+Licensed under the Apache License Version 2.0 (the "License"). You may not use this file except
+in compliance with the License. A copy of the License is located at http://www.apache.org/licenses/
+or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+**********************
+THIRD PARTY COMPONENTS
+**********************
+This software includes third party software subject to the following copyrights:
+
+aws-sdk under the Apache License Version 2.0
+axios under the Massachusetts Institute of Technology (MIT) license
+axios-mock-adapter under the Massachusetts Institute of Technology (MIT) license
+jest under the Massachusetts Institute of Technology (MIT) license
+moment under the Massachusetts Institute of Technology (MIT) license
+uuid under the Massachusetts Institute of Technology (MIT) license

README.md

@@ -1,13 +1,114 @@
-## My Project
+# Cognito User Profiles Export Reference Architecture
+This solution uses an [AWS Step Functions](https://aws.amazon.com/step-functions/) workflow (`ExportWorkflow`) to periodically export user profiles, groups, and group membership details from your user pool to an [Amazon DynamoDB global table](https://aws.amazon.com/dynamodb/global-tables/) with automatic, asynchronous replication to a backup Region for added resiliency. This solution is designed to provide a framework for exporting user profile and group information from your user pool, allowing you to focus on extending the solution’s functionality rather than managing the underlying infrastructure operation. 
 
-TODO: Fill this README out!
+This solution’s `ImportWorkflow` Step Functions workflow can be used to populate a new, empty user pool with data from the global table, allowing you to easily recover user profiles, groups, and group memberships. The `ImportWorkflow` Step Functions workflow can be run in either the primary or backup Region.
 
-Be sure to:
+> **_NOTE:_**  Some data loss will result when running the `ImportWorkflow` Step Functions workflow because this solution runs periodically. For example, if you schedule exports daily, you will lose up to a day’s worth of user pool updates depending on when the `ImportWorkflow` Step Functions workflow was run.
 
-* Change the title in this README
-* Edit your repository description on GitHub
+For more information and a detailed deployment guide visit the [solution home page](https://aws.amazon.com/solutions/implementations/cognito-user-profiles-export-reference-architecture/).
 
-## License
+## On This Page
+- [Architecture Overview](#architecture-overview)
+- [Getting Started](#getting-started)
+- [File Structure](#file-structure)
+- [License](#license)
+
+## Architecture Overview
+
+![Architecture](architecture-diagram.png)
+
+## Getting Started
+### 1. Prerequsites
+The following procedures assumes that all of the OS-level configuration has been completed. They are:
+- [AWS Command Line Interface](https://aws.amazon.com/cli/)
+- Node.js 12.x
+
+The Cognito User Profiles Export Reference Architecture is developed with Node.js for the microservices that run in AWS Lambda. The latest version has been tested with Node.js 12.x.
+
+### 2. Clone the Cognito User Profiles Export Reference Architecture repository
+Clone the ```cognito-user-profiles-export-reference-architecture``` GitHub repositroy, then make the desired code changes.
+
+```bash
+git clone https://github.com/awslabs/cognito-user-profiles-export-reference-architecture.git
+```
+
+### 3. Run unit tests
+* Next, run unit tests to make sure added customization passes the tests.
+```bash
+cd ./deployment
+chmod +x ./run-unit-tests.sh
+./run-unit-tests.sh
+```
 
-This project is licensed under the Apache-2.0 License.
+### 4. Declare environment variables
+```bash
+export REGION=aws-region-code # the AWS region to launch the solution (e.g. us-east-1)
+export DIST_OUTPUT_BUCKET=my-bucket-name # bucket where customized code will reside
+export SOLUTION_NAME=my-solution-name
+export VERSION=my-version # version number for the customized code
+```
+
+### 5. Create an Amazon S3 bucket
+The AWS CloudFormation template is configured to pull the AWS Lambda deployment packages from Amazon S3 bucket in the region the template is being launched in. Create a bucket in the desitred region name appended to the name of the bucket. _Note:_ you must have the AWS Command Line Interface installed.
+```bash
+aws s3 mb s3://$DIST_OUTPUT_BUCKET-$REGION --region $REGION
+```
+
+### 6. Build the Cognito User Profiles Export Reference Architecture for deployment
+```bash
+chmod +x ./build-s3-dist.sh
+./build-s3-dist.sh $DIST_OUTPUT_BUCKET $SOLUTION_NAME $VERSION
+```
+
+### 7. Upload deployment assets to your Amazon S3 bucket
+* Deploy the distributable to an Amazon S3 bucket in your account. _Note:_ you must have the AWS Command Line Interface installed.
+```bash
+aws s3 cp ./regional-s3-assets/ s3://$DIST_OUTPUT_BUCKET-$REGION/$SOLUTION_NAME/$VERSION/ --recursive --acl bucket-owner-full-control
+```
+
+### 8. Launch the Cognito User Profiles Export Reference Architecture
+- Get the link of cognito-user-profiles-export-reference-architecture.template uploaded to your Amazon S3 bucket.
+- Deploy the Cognito User Profiles Export Reference Architecture to your account by launching a new AWS CloudFormation stack using the S3 link of cognito-user-profiles-export-reference-architecture.template.
+
+## File Structure
+```
+|- deployment/
+  |- cognito-user-profiles-export-reference-architecture.yaml   [ solution CloudFormation deployment template ]
+  |- stack-set-template.yaml                                    [ CloudFormation template for the StackSet that is deployed in each region ]
+  |- build-s3-dist.sh                                           [ shell script for packaging distribution assets ]
+  |- run-unit-tests.sh                                          [ shell script for executing unit tests ]
+|- source/
+  |- custom-resources/
+    |- check-stackset-status.js                                 [ Checks the status of the solution's StackSets and when ready, responds to CloudFormation ]
+    |- global-table-checker.js                                  [ Checks the status of the Backup Table replica and when active, response to CloudFormation ]
+    |- global-table-creator.js                                  [ Adds a replica to the Backup Table in the Secondary Region ]
+    |- solution-constants.js                                    [ Generates values to be used within the solution ]
+    |- stack-checker.js                                         [ Custom Resource that checks to see if the current stack update is supported ]
+    |- stackset-constants.js                                    [ Retrieves solutions constants from SSM parameter store so they can be used within the StackSet instance ]
+    |- stackset-manager.js                                      [ Manages the solution's StackSet during solution create/update/deletes ]
+  |- utils/
+    |- custom-resource-helper-functions.js                      [ Exports common functions that can be used within custom resource lambda functions ]
+    |- helper-functions.js                                      [ Exports utility functions to be used throughout the solution ]
+    |- metrics.js                                               [ Client for sending anonymous operational metrics ]
+  |- workflow-common/
+    |- check-state-machine-executions.js                        [ Checks whether a state machine has multiple executions running ]
+    |- check-workflow-queues.js                                 [ Checks whether the SQS queues used by the workflow are empty prior to proceeding ]
+    |- message-broker.js                                        [ Publishes info and error messages to the solution's SNS topic and if enabled, sends anonymous operational metrics ]
+  |- workflow-export/
+    |- backup-table-cleanup.js                                  [ Cleans up the Backup Table by identifying items that were not updated during the most recent export and removing them ]
+    |- check-user-pool-config.js                                [ Checks the configuration of the primary user pool to ensure it is supported by the solution ]
+    |- export-group.js                                          [ Exports the supplied group name to the backup table ]
+    |- export-users.js                                          [ Exports user profiles to the backup table ]
+    |- export-users-in-group.js                                 [ Exports group memberships to the backup table ]
+    |- list-groups.js                                           [ Lists group in a user pool and returns group details so they can be processed by the Export Workflow ]
+  |- workflow-import/
+    |- check-new-user-pool.js                                   [ Checks the new user pool to ensure it has no users or groups ]
+    |- import-users.js                                          [ Imports users into the new user pool ]
+    |- scan-table.js                                            [ Scans the backup table and queues items for the Import Workflow ]
+    |- update-new-users.js                                      [ Updates users that have been imported to the new user pool ]
+```
+
+## License
+Cognito User Profiles Export Reference Architecture is distributed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).
 
+See [LICENSE](./LICENSE.txt) and [NOTICE](./NOTICE.txt) for more information.

deployment/build-s3-dist.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+#
+# This assumes all of the OS-level configuration has been completed and git repo has already been cloned
+#
+# This script should be run from the repo's deployment directory
+# cd deployment
+# ./build-s3-dist.sh source-bucket-base-name solution-name version-code
+#
+# Paramenters:
+#  - source-bucket-base-name: Name for the S3 bucket location where the template will source the Lambda
+#    code from. The template will append '-[region_name]' to this bucket name.
+#    For example: ./build-s3-dist.sh solutions v1.0.0
+#    The template will then expect the source code to be located in the solutions-[region_name] bucket
+#
+#  - solution-name: name of the solution for consistency
+#
+#  - version-code: version of the package
+
+# Check to see if input has been provided:
+if [ -z "$1" ] || [ -z "$2" ] || [ -z "$3" ]; then
+    echo "Please provide the base source bucket name, trademark approved solution name and version where the lambda code will eventually reside."
+    echo "For example: ./build-s3-dist.sh solutions trademarked-solution-name v1.0.0"
+    exit 1
+fi
+
+# Get reference for all important folders
+template_dir="$PWD"
+template_dist_dir="$template_dir/global-s3-assets"
+build_dist_dir="$template_dir/regional-s3-assets"
+source_dir="$template_dir/../source"
+
+echo "------------------------------------------------------------------------------"
+echo "[Init] Clean old dist, node_modules and bower_components folders"
+echo "------------------------------------------------------------------------------"
+echo "rm -rf $template_dist_dir"
+rm -rf $template_dist_dir
+echo "mkdir -p $template_dist_dir"
+mkdir -p $template_dist_dir
+echo "rm -rf $build_dist_dir"
+rm -rf $build_dist_dir
+echo "mkdir -p $build_dist_dir"
+mkdir -p $build_dist_dir
+
+echo "------------------------------------------------------------------------------"
+echo "[Packing] Templates"
+echo "------------------------------------------------------------------------------"
+SUB_BUCKET_NAME="s/BUCKET_NAME_PLACEHOLDER/$1/g"
+SUB_SOLUTION_NAME="s/SOLUTION_NAME_PLACEHOLDER/$2/g"
+SUB_VERSION="s/VERSION_PLACEHOLDER/$3/g"
+
+for FULLNAME in ./*.yaml
+do
+  TEMPLATE=`basename $FULLNAME .yaml`
+  echo "Template: $TEMPLATE"
+  sed -e $SUB_BUCKET_NAME -e $SUB_SOLUTION_NAME -e $SUB_VERSION $template_dir/$TEMPLATE.yaml > $template_dist_dir/$TEMPLATE.template
+  cp $template_dist_dir/$TEMPLATE.template $build_dist_dir/
+done
+
+echo "------------------------------------------------------------------------------"
+echo "[Building] Utils"
+echo "------------------------------------------------------------------------------"
+cd $source_dir/utils
+npm run clean
+npm ci --production
+
+declare -a lambda_packages=(
+  "custom-resources"
+  "workflow-common"
+  "workflow-export"
+  "workflow-import"
+)
+
+for lambda_package in "${lambda_packages[@]}"
+do
+  echo "------------------------------------------------------------------------------"
+  echo "[Building] Lambda package: $lambda_package"
+  echo "------------------------------------------------------------------------------"
+  cd $source_dir/$lambda_package
+  npm run package
+
+  # Check the result of the build and exit if a failure is identified
+  if [ $? -eq 0 ]
+  then
+    echo "[Building] Package for $lambda_package built successfully"
+  else
+    echo "------------------------------------------------------------------------------"
+    echo "[ERROR] Package build FAILED for $lambda_package"
+    echo "------------------------------------------------------------------------------"
+    exit 1
+  fi
+  cp ./dist/package.zip $build_dist_dir/$lambda_package.zip
+done