Portal App Tile Configurations

Access-Boston Config

Repo: https://github.com/CityOfBoston/access-boston-config

Overview

The access-boston-config repository manages changes to the "front end" of the Access Boston website without requiring developer intervention. This includes updates to application icons, names, links, and assigned security groups. The repository handles configuration for three environments: Development (dev), Testing (test), and Production (prod).

Changes are made by editing configuration files for each environment separately. It is encouraged to make these changes Monday-Friday, 9 a.m.-5 p.m., if possible, to ensure that if something goes run that there are available staff to help resolve. The following are step-by-step instructions on how to make these edits:

Configuration Process

1. Request Details

   Ensure that the following details are provided in the DIG Access Boston portal request ticket:

   • Name of app: The name of the application to link to the Access Boston portal.

   • Security group: The security group(s) that should have access to view the application link. If left blank or set to 'birthright', the link will be visible to all users.

   • URL: The external link URL to redirect to upon clicking. Ensure the URL is complete and valid. Specify if it should open in a new tab.

   • Icon: The name of the icon and the SVG graphic file. Attach the graphic to the ticket.

   • Deadline: A specified window for deployment within working hours, typically within 12 to 24 hours from today.

2. Edit Configuration

   From the repository landing page, edit the config file for the environment (dev/test/prod) you want to change, by going from the 'src' and the 'config' folder; the click on the folder for the environment you want to edit.

   

   • Dev

   • Test

   • Prod

   Click on the 'apps.yaml' file, from the details view click the 'Edit this File' icon.

   Adding new links require 3 of the following fields:

   • title

   • url

   • *icon

   • *groups

     

   *Icon is require for links in the 'Apps' section, at the top of the file.

   *Groups is a list of groups of people with access that application. The formatting should follow this style:

   Edit the apps.yaml file in the selected directory:

   • Locate the categories field.

   • Find the item with the title Applications.

   • Under apps, navigate to the end of the list and add a new entry in the following format:

     Copy

     - title: [Name of app]
       url: [URL]
       target: _blank (Include only if the link should open in a new tab)
       icon: https://assets.boston.gov/icons/accessboston/[Icon_Name].svg
       groups: (Include only if specific security groups are assigned)
         - [Security Group 1]
         - [Security Group 2]

1. Update Patterns Library in AWS

Next, we need to log into the AWS console to update the patterns library repository with the icon. If the ticket did not request an icon change (adding a new tile or replacing an icon), you still need to verify the SVG icon is available at:

https://assets.boston.gov/icons/accessboston/[Icon_Name].svg.

It is strongly recommended to complete this step before pushing any changes.

The patterns library is a hosted publicly available style library for development on Boston.gov and related digital applications.

Log into the AWS Console. Contact the administrator if there are access issues.

Upload the SVG icon to the S3 bucket:

Amazon > S3 > Buckets > patterns.boston.gov > assets/ > icons/ > accessboston/

• Click Upload.

• Upload the file with the correct filename.

• Under Server-side encryption, select specify an encryption key

• No extra settings need to be selected. Click Upload to confirm changes.

1. Commit Changes

When you're done making changes, click on the 'Commit Changes' button on the top right corner. This will open a pop-up modal; provide a name and description for the changes made.

In pop-up modal select the "Create a new Branch for this commit" radio button

When you're done, hit the "Commit Changes" button

Give the new branch for your work a name. Follow these naming conventions:

deploy_<environment>/<ticket-id>

Hit the "Propose Changes" button; this will take you to another screen where you will see a preview of the "Pull Request" that will be created.

Hit the "Create Pull Request" button. This will create the PR and you will be take to its page.

On the PR page tag a reviewer to approve your changes. After you'll be able to "Merge" your changes. After merging a github action for (Force) Push Changes to deploy-branches. This will update the corresponding [deploy-dev|test|prod] branch to match the master branch.

Go to the Deploy AB Configs to Amazon S3 Github Actions, click on the Run workflow to select what branch to run this action on. Make sure you're not selecting any other actions as it will fail the process.

Select the branch your previous commit targeted and click Run workflow

Wait for the workflow to run, it will show a green circular check mark if the it passed, and a red circular x if it failed

1. Verify the workflow changes in AWS

The above automated process should update the apps.yaml file in the AWS console in the respective environment with the latest changes.

Log into the AWS Console. Contact the administrator if there are access issues.

Verify that the CI/CD process updated the file in:

Amazon S3 > Buckets > cob-digital-apps-staging-config > access-boston/ > [Environment]/ > apps.yaml

1. Redeploy the Access Boston Portal with New Changes

With all changes in place, we must redeploy the container in which the Access Boston Portal application is running and servicing. To do this:

Log into the AWS Console. Contact the administrator if there are access issues.

Go to Elastic Container Services >Apps Staging Services > access-boston-[Environment]

Click Update Service to trigger a re-deployment with the new configurations

Select Force new deployment and proceed to click Update

You will be returned to the service details page. Click Tasks to monitor the container deployment process. Make sure that the process terminates without errors.

You've now completed the configurations process. Make sure to close the ticket, notify all parties and update its status.