Common Service Get Token
To learn more about the Common Services available visit the Common Services Showcase page.
GETOK is a web-based tool for development teams to manage their application’s secure access to Common Services. Users can create and deploy Keycloak service clients instantly to gain access to common service APIs like email notifications, document management, or document generation.
Frontend
The frontend of the application is built on the Vue.js framework as a static UI layer. The web application calls to the GETOK API (see app) for authentication and application funtionality.
The frontend of the application allows users to fill in the appropriate info required to create a service client, and then test token aquisition. The backend API handles communication with the authorization systems to create the application configuration. The backend API also creates the password required for the service client and securely returns it to the UI (see Password Generation for these details).
Vue Archetecture
The frontend was built up from scratch using the official Vue CLI distribution. See the Vue CLI docs for more information.
Vuetify
The material design framework Vuetify is used for design and layout. All additional UI elements added should use Veutfify components and material design language. See the Vuetify docs for more information. We installed the Vuetify framework by running vue add Vuetify.
Vuex
The Vuex state management system is an integral part of the frontend application. It maintains a centralized store for all the components in the app. The location of the store in the project structure is ./src/store. See the Vuex docs for more information.
Our Vuex store leverages dynamic module registration in order to allow for certain modules to be loaded after store creation. This allows us to start the application sooner, and allows for better code separation in webpack bundling. At this time, the auth module must be loaded after the Keycloak plugin has fully loaded. Other modules may potentially follow this dynamic registration pattern if it makes sense.
Vue Router
Vue Router is used for Single Page App routing. See the Vue Router docs for more information. We are not using history mode in order to ensure network pathing remains consistent.
Other Dependencies
Other imported libraries used in the application include:
- axios for REST calls
- core-js standard JS library
- cryptico-js for password decryption
- nprogress AJAX progress bars
See ./package.json for more.
Environment Configuration
At the root of this frontend directory are environment files that create environment variables that are accessible to the app at build time.
For local development, create a .env.development.local file at this location (it will be ignored by Git) to provide local environment variables. This will be invoked when npm run serve is used.
See the Vue CLI docs on Modes and Environment variables for more information.
Unit Tests
Unit tests are written in Jest.
Vue Test Utils is included (scaffolded through Vue CLI) to facilitate unit test writing for the Vue components.
See Run your unit tests below for details on executing tests.
Writing Unit Tests
For most components, we will want to be shallow mounting them in order to avoid accidentally testing for behavior across different components. Components which contain children components should be stubbed out where possible.
As our codebase uses dynamic module registration, unit tests which need the store will need to one of the following:
- Instantiate a new vuex store with the appropriate values as part of the constructor
- Create an empty vuex store and then register a mocked vuex store module for the specific unit test environment
While both methods effectively achieve the same goal of setting the vuex store mock to be in the right state, we suggest using the second option as it can provide slightly more flexibility with unit testing.
Project scripts to run locally
All scripts are assuming terminal directory is ./frontend and npm is installed.
First execute npm install to set up dependencies
npm install
Note on backend setup
Without the backend app API running correctly, the front end will not do much on a local system. This is because it must acquire dynamic configuration settings from it beforehand. See backend instructions for details on running the api locally
If you are running the frontend in dev mode, it should not use the same port as the backend application. By default, the dev server will run on port 8081.
Compiles and hot-reloads for development
Vue CLI provides a hot-reloadable server. Run the command bellow to start it up and any changes to the frontend source will automatically reload.
npm run serve
Compiles and minifies for production
If you need to build the deliverables you can run the following. This is normally done by the build pipeline.
npm run build
Run your unit tests
npm run test
Lints and fixes files
To check linting, run
npm run lint
To autofix lint issues, run
npm run lint:fix
Lint configuration can be seen in ./.eslintrc.js