Customize Deployment

A Qrvey instance uses five CloudFormation templates to create pipelines: Widgets, DataRouter, Worker, Microservices, and Admin. Each template has input parameters that configure the instance. To update an instance, change these parameters to update all related resources. Most changes require external setup, like email verification or CNAME record updates, followed by parameter updates in Qrvey. This document explains how to update a single pipeline's parameters and provides steps for specific changes.

Update a Single Pipeline

These steps will show you how to update the parameters for a single pipeline. In this example, we’ll be updating the QrveyCodePipeline but the same steps can be replicated for any of the other pipelines.

Step 1: Identify CloudFormation Stack

1. Log into your AWS Account and select the region where your Qrvey instance is located.
2. Navigate to the CloudFormation console.
3. Identify the cloudFormation stack for the Pipeline you want to update. You can search for “CodePipeline” and you should see the 5 stacks as shown in this screenshot.

Step 2: Update CloudFormation Template Parameters

1. From the CloudFormation screen, pick the CloudFormation stack matching the pipeline you want to update and click on the Update button.
2. On the Prerequisites screen, pick “Use Current Template”. Click Next.

3. On the parameters screen, find the option you would like to change and enter in the new value. Leave the rest of the parameters as they are. You can find the specific parameter for your use-case in later sections of this document. In this example we are updating the “From” email address by changing the parameter called “VerifiedEmail” (highlighted with yellow). Click Next after changing the value.

4. Click on Next on the Configure Stack options screen.
5. On the next screen (Review), review the changes you have made, select the Capabilities checkbox (if shown) and click on Update Stack to apply the changes.
6. At this point, the CloudFormation stack will move to “UPDATE_IN_PROGRESS” state.
7. Wait for the CloudFormation stack to finish updating. Once it’s done the status would change to “UPDATE_COMPLETE”.

Step 3: Trigger CodePipeline to Deploy Changes

1. Once the CloudFormation stack has finished with the update, navigate to the AWS CodePipeline console.
2. Identify the matching pipeline for the CloudFormation stack you updated in the last step. For the “QrveyCodePipeline” stack, the pipeline will be called “Qrvey_xxxxx_Worker”.
3. Select the Pipeline and click on the Release Change button.

4. This will change the Pipeline status to “In Progress” and once the Pipeline is done the status will change to “Succeeded”.

At this point, the changes are deployed and you can start using the Platform.

Change “From” Email Address

Qrvey platform uses AWS SES to send out all emails. These emails come from Automation or Page flows and also transactional emails like the “forgot password” feature.

To change the email address that is used under the “From” section you’ll need to add and verify the email address in AWS SES and then update the Qrvey deployment to use it. Here are the steps:

1. Log into your AWS Account and navigate to the AWS SES console.
2. Under the “Email Addresses” section click on Verify a New email address. Type in the new email address and click Verify. This will send an email to the specified address from AWS.
3. Open your email client and click on the verification link under that email
4. Go back to AWS SES to confirm that the “Verification status” for that email address has changed to “Verified”.
5. Update the following CloudFormation Stacks and CodePipelines by following the steps mentioned here.
   • a. Qrvey Worker
     • CloudFormation Stack: xxxxxQrveyCodePipeline. Parameters:
       • 1. VerifiedEmail - Enter the new email address
     • CodePipeline: Qrvey_xxxxx_Worker
   • b. Microservices
     • CloudFormation Stack: xxxxxMicroservicesCodePipeline. Parameters:
       • 1. VerifiedEmail - Enter the new email address
     • CodePipeline: Qrvey_xxxxx_Microservices
6. Once all Pipelines have finished updating you will start receiving emails using the specified “From” email address.

Change Composer URL

You can change the Composer URL to match your own domain. You would need access to DNS settings for that domain (Route 53 or similar) to be able to create a new CNAME record and SSL Certificate.

Step 1: Create New Public Certificate

1. Identify two URLs associated with your Qrvey instance:
   • The Composer URL — (e.g., https://qrveysample.yourdomain.com)
   • The API Domain URL — (e.g., https://api-qrveysample.yourdomain.com)
2. Log into your AWS account and navigate to the AWS Certificate Manager console.
3. Create a new certificate matching the URL/domain you would like to use. You can create a specific certificate for the exact URL or a wildcard (*.yourdomain.com). You can also import or use an existing certificate if you already have one. Here’s the AWS documentation on creating certificates. We recommend using DNS validation.
4. Once the certificate is verified (status changes to “Issued”), copy the ARN to be used in later steps.

Note: If your Qrvey Installation is in a region other than us-east-1 then you will need to repeat steps 2-4 for us-east-1.

Note: Starting on version 8.4 the Widget URL is the same as the Composer URL.

Step 2: Update MainTemplate

1. Navigate to AWS Cloudformation console.
2. Find the stack called Qrvey-----MainTemplate.
3. Navigate into Update > Use Existing Template > Update and replace parameters that use the old URLs (composer or API) to use the new ones:
   • WidgetsBucketPath
   • WidgetsBucketlauncherPath
   • sslCertificateNameDesired
4. Apply the changes and wait for the update to finish.

Step 3: Update CloudFormation Stacks

Update the following CloudFormation Stacks and CodePipelines by following the steps from Update a Single Pipeline. Update any parameters with the old URL to the new URLs.

1. Data Router
   • CloudFormation Stack: xxxxxDataRouterCodePipeline.
     • Parameters:
       • APIDomainURL - Set it to the API URL.
       • QrveyURL - Set it to the Composer URL.
       • certificateARN - SSL Certificate ARN from the local region.
2. Widgets
   • CloudFormation Stack: xxxxxWidgetsCodePipeline.
     • Parameters:
       • APIDomainURL - Set it to the API URL.
       • ARNSSLCertificate - Set it to the SSL Certificate ARN from the us-east-1 (N.Virginia) region.
       • ComposerUrl - Set it to the Composer URL.
       • CustomDNS - Set it to the Composer URL.
3. Qrvey Worker
   • CloudFormation Stack: xxxxxQrveyCodePipeline.
     • Parameters:
       • sslCertificateNameDesired - Set it to the Composer URL.
       • APIDomainURL - Set it to the API URL.
4. Microservices
   • CloudFormation Stack: xxxxxMicroserviceCodePipeline.
     • Parameters:
       • APIDomainSSLCertARN - Set it to the SSL Certificate in the local region that matches the API URL.
       • APIDomainURL - Set it to the API URL.
       • AdminAppDomainURL - Replace the part with the Composer URL and leave the rest as is.
       • AdminServerURL - Replace the part with the Composer URL and leave the rest as is.
       • CertificateARN - SSL Certificate ARN from the local region.
       • QrveyURL - Set it to the Composer URL.
       • WidgetsBucketPath - Set it to the Composer URL.
       • WidgetsBucketlauncherPath - Replace the part with the Composer URL and leave the rest as is.
       • sslCertificateNameDesired - Set it to the Composer URL.
5. Admin Center
   • CloudFormation Stack: xxxxxAdminAppCodePipeline.
     • Parameters:
       • APIDomainURL - Set it to the API URL.
       • AdminAppDomainURL - Replace the part with the Composer URL and leave the rest as is.
       • AdmindrURL - Replace the part with the Composer URL and leave the rest as is.
       • certificateARN - SSL Certificate ARN from the local region.
       • widgetBucketURL - Set it to the Composer URL.

Step 4: Trigger CodePipelines

Run the Qrvey CodePipelines to apply template changes by following the steps from Trigger CodePipelines to deploy changes.

• Qrvey_xxxxx_DataRouter
• Qrvey_xxxxx_Widgets
• Qrvey_xxxxx_Worker
• Qrvey_xxxxx_Microservice
• Qrvey_xxxxx_Admin

Step 5: Add New CNAME Values to DNS.

Find values for the CNAME records of the new domain and add them to your DNS.

1. Navigate to AWS CloudFormation console.
2. Find the stack called Qrvey-----WidgetsCodePipeline and select Outputs Tab.
3. Copy the value of the CloudfrontDomainName. Example: https://xxxxxxxxxxx.cloudfront.net.
   This will be the value for the Composer URL CNAME record.
4. Navigate to AWS API Gateway console and click on “Custom domain names”.
5. Select the domain matching your new API Domain URL, for example: api-qrveysample.yourdomain.com.
6. Copy the value of the API Gateway domain name, for example: x-xxxxxxx.execute-api.us-east-1.amazonaws.com.
   This will be the value for the API Domain URL CNAME record.
7. Login or navigate to your DNS provider (Route 53 or similar) and add or update the CNAME records for Composer URL and API URL with the values from the last steps, for example:
   • Composer URL:
     • CNAME record: qrveysample.yourdomain.com
     • CNAME value: https://xxxxxxxxxxx.cloudfront.net
   • API URL:
     • CNAME record: api-qrveysample.yourdomain.com
     • CNAME value: x-xxxxxxx.execute-api.us-east-1.amazonaws.com

Step 6: Update Bucket Path

Update Bucket Path values with new URLs.

1. Navigate to AWS CloudFormation console.
2. Find updated in previous steps xxxxxMicroserviceCodePipeline stack.
3. Copy the values of WidgetsBucketPath and WidgetsBucketlauncherPath.
4. Navigate to AWS Systems Manager console.
5. Click on Parameter Store.
6. Find /qrvey/xxxxxx/WidgetsBucketPath.
7. Update the value with the new value from the xxxxxMicroserviceCodePipeline stack. Example: https://qrveysample.yourdomain.com
8. Find: /qrvey/xxxxxx/WidgetsBucketlauncherPath.
9. Update the value with the new value from the xxxxxMicroserviceCodePipeline stack. Example: https://qrveysample.yourdomain.com/widgets-launcher/app.js

Step 7: Run the Lambda Function

1. Navigate to AWS Lambda console.
2. Find the function called -----_CreateEnvFile_LambdaFunction and click the function name to open the details.
3. Select the Test tab:
   • Enter any string in Event name.
   • Add this JSON to the body: { "RequestType": "UpdateEnvFile" }
   • Click Test.
4. Select the Test tab:
   • Enter any string in Event name.
   • Add this JSON to the body: { "RequestType": "UpdateVariables" }
5. Click Test.
   • Wait for the functions to finish and then you can start using the new URL.

Step 8: Start Using New URL

Once all the pipelines have finished successfully, you can launch Composer using the new URL.