...

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

...

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

   Code Block
   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.

How to utilize Feature Flags

Toggling the feature

1. Sign into the AWS Management Console, and go to AWS AppConfig

2. Access the AppConfig Application that corresponds to your application name

3. Click the FreeForm configuration profile under Configuration Profiles and Feature Flags

4. Click Create

5. Edit the JSON configuration as wanted (e.g. true → false)Create hosted configuration version

6. Select the newly created configuration version under the Version dropdown menu if not already set

7. Click on Start Deployment

8. Double check that the hosted configuration version matches the newly created version and select AllAtOnce under deployment strategy

9. Click on Start Deployment

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

Applying Feature Flag in SWC

...

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.

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

Applying Feature Flag in

...

synapse-react-client

SRC utilizes react-query library and Applications using synapse-react-client will fetch the configuration from the SWC servlet to retrieve feature flags from AWS AppConfig. 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 followedfollows:

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

   Code Block
   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.

   Code Block
   useGetFeatureFlag(FeatureFlagEnum.DESCRIPTION_FIELD)

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)

...