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.

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)

6. Create hosted configuration version

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

8. Click on Start Deployment

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

10. Click on Start Deployment

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

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 SRC

SRC utilizes react-query library and the SWC servlet to retrieve feature flags from AWS AppConfig.

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

1. Inside FeatureFlags.ts under synapse-types, add 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.

   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)

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.