Updating an existing feature flag

To update a feature flag, (e.g. to release or rollback a feature), follow these steps. Note that this sequence is subject to change if AWS changes their UI.

1. Log in to the Synapse Prod AWS Console with the Developer Role

2. Navigate to the AWS AppConfig dashboard

3. Choose the application that maps to the release you wish to update. If updating production, staging should also be updated!

4. Create a new hosted configuration version and update the JSON document to toggle the desired flag(s).

5. Click “Start Deployment”, select the portal environment, desired strategy (e.g. AllAtOnce), and click “Start Deployment” to push out the feature flag.

6. Update the Synapse-Stack-Builder appconfig-config.json file to ensure future stacks have the updated default feature flag configuration.

The AppConfigServlet will serve the newly deployed configurations after the 5 minute cache expires

How to create Feature Flags

Feature flags are created and maintained through the Synapse-Stack-Builder repository. Assuming that there will be no cases in which a new feature flag will be created on a stack that has already been built, the steps to add a feature flag are as followed:

1. Navigate to appconfig-config.json inside the Synapse-Stack-Builder repo:

2. Inside the appConfigDescriptors JSON array, locate the object with the respective “appConfigName” (portal, repo, etc.) where a new feature flag will be added.

3. Edit the value of "appConfigDefaultConfiguration" with the additional feature flag configurations while maintaining the JSON string format.

4. Navigate to appconfig-data-test.json. (This file acts as a safeguard for when the stack builder generates unexpected AWS CloudFormation templates and for engineers to double check that the templates are generated as expected).

5. Edit the JSON file to reflect the AWS AppConfig CloudFormation template that should be generated while making sure that no JSON syntax errors exists

6. Run mvn test to verify that correct AppConfig templates are generated through the stack builder. (running mvn test DOES NOT guarantee that the AppConfig template is free of JSON syntax errors)
   The actual output generated from the stack builder could be seen in the logs or by debugging RepositoryTemplateBuilderImplTest with breakpoint at lines that creates a JSONObject like below

   JSONObject templateJson = new JSONObject(bodyJSONString);

7. An engineer should further verify that creating this new feature flag will not break the stack builder builds by running their own Jenkins build.

   1. Copy one of the existing builds by the name stackbuilder-dev... inside Jenkins

   2. Click Configure and replace “Repository URL” and “Default Value” for BRANCH String parameter with your respective GitHub Repository and the branch that includes the change

   3. Build the Jenkins build and validate that the build completes

8. If an engineer wants to delete a feature flag, follow the steps above with changes to step 3 as needed.

Applying Feature Flag in SWC

The feature flags are retrieved and memoized every five minutes through the AppConfigServlet in the server layer of SWC with the doGet() function surfaced to be used on the client side. Currently, the doGet() is called in Portal.java when the module is loaded. Then, it is stored in cookies.

The steps to apply feature flags inside SWC are as followed:

1. Inside FeatureFlagKey.java, add the enum value representing the Feature Flag.

2. If not done already, inject FeatureFlagConfig inside the class where the Feature Flag will be used.

3. Apply conditional statements referencing the enum value to use the feature flag.

   if (featureFlagConfig.isFeatureEnabled(FeatureFlagKey.PROVENANCE_V2_VISUALIZATION.getKey()){}

Applying Feature Flag in synapse-react-client

Applications using synapse-react-client will fetch the configuration from the SWC servlet. React components utilize react-query to retrieve and cache the configuration within the React application’s lifecycle.

The steps to apply feature flags inside SRC are as follows:

1. Inside FeatureFlags.ts under synapse-types, add an enum value representing the Feature Flag.

2. Build synapse-types using pnpm or command under package.json

3. Navigate to the file where the feature flag will be used and add imports

   import { useGetFeatureFlag } from '../../../../synapse-queries' import { FeatureFlagEnum } from '@sage-bionetworks/synapse-types'

4. Apply conditional statements referencing the enum value to use the feature flag.

5. Validation Process

   1. Add your stack to the list of Storybook stacks.

      1. In packages/synapse-react-client/src/utils/functions/getEndpoint.ts, add a stack to the STACK_MAP and use the endpoints for your dev stack (Reference the validation process for applying feature flag in SWC) or prod/staging/dev stack with the wanted configurations inside AWS AppConfig.

      2. Then in packages/synapse-react-client/.storybook/preview.tsx you can add it so you can pick that stack in Storybook (L94)

Related work and known challenges

The following tasks are left to be completed

• SWC-6716 - Getting issue details... STATUS

• SWC-6846 - Getting issue details... STATUS

• SWC-6847 - Getting issue details... STATUS

Validation Process for SWC

1. Build your SWC artifacts

   1. Copy one of the existing builds by the name swc-test-...-build inside Jenkins.

   2. Click configure and point the Jenkins build to your GitHub and branch

   3. Build with parameters.

   4. Once build succeeds, navigate to the console output and find the artifact id generated by locating an output statement portal-xxxx-xx-xx-... (ex: portal-2024-05-23-2be70b1ac6-20)

2. Build your own Dev Stack

   1. Copy one of the existing builds by the name build-dev-stack-... inside Jenkins.

   2. Click configure and point the PORTAL Artifacts to the artifact id generated in step a

   3. Build with parameters.

   4. Once build succeeds, navigate to ROUTE 53 on AWS Console and find the CNAME that points to your dev stack and validate that the feature flag is working as expected.