CDS Import Declarations Frontend
This application provides a GOV.UK frontend for the Customs Declarations API that enables users to submit an import declaration online. The project is currently in the early stages of development.
Technical Notes
Dependencies
In order to deliver required functionality, this frontend interacts with a number of other HMRC microservices. These are:
- Declaration submission:
- Customs Declarations - required to process an import declaration submission
- Customs Notifications Gateway - a transitive dependency from Customs Declarations
- API Subscription Fields - a transitive dependency from Customs Declarations which is used by them to verify access permissions for this application to their API
- Authentication:
- Auth - to provide sign in support via Government Gateway
- Auth Login API - transitive dependency required as a backend for the above
- Company Auth Frontend - provides the Government Gateway sign in frontend
- SSO - provides "single-sign-on" support
- User Details - enables the retrieval of user details
- User Interface:
- Assets Frontend - implementation provider of GOV.UK styles, widgets, and design patterns
- Audit:
- Datastream - sink endpoint for audit logs and messages
- Testing and running in development:
- Auth Login Stub - to simulate Government Gateway login
- Customs API Hods Stubs - a transitive dependency which is used by Customs Declarations when running locally to authenticate API requests
If you are using HMRC's service manager, then you can start all of the above dependencies using a pre-configured profile:
sm --start CDS_IMPORTS_ALL -f
will start the latest snapshot version of the CDS Import Declarations Frontend and all dependent services, including those required for testing or running in developmentsm --start CDS_IMPORTS_DEPS -f
will start all the dependent services; i.e. excluding this frontend itselfsm --start GG_AUTH_SERVICES -f
will start only the dependencies required to satisfy authentication, which is often sufficient for the purposes of ongoing development work
When running locally for the purposes of development, you will additionally need to ensure that you have created an API subscription which grants permission for this application to access the Customs Declarations API. To achieve this, execute the following CURL command:
curl -v -X PUT "http://localhost:9650/field/application/customs-declare-imports-frontend/context/customs%2Fdeclarations/version/2.0" -H "Cache-Control: no-cache" -H "Content-Type: application/json" -d '{ "fields" : { "callback-url" : "http://localhost:6789/customs-declare-imports", "token" : "abc59609za2q" } }'
Feature Switching
In order to facilitate continuous integration, A/B testing, and live support, the CDS Import Declarations Frontend supports feature toggles. In the provided implementation, "features" have one of three potential states:
enabled
- the feature is "on".disabled
- the feature is "off".suspended
- the feature is "currently unavailable" (should only be used on a temporary basis for the purposes of live support).
Features can be "switched" on a per-endpoint basis using the switch action.
Via this mechanism, enabled
actions will return as expected, those that are disabled
will return a 404 Not Found
status, and
those that are suspended
will return 503 Service Unavailable
.
Features can also be "switched" on a more granular basis using conditional checks in code that utilise the feature status check support provided in AppConfig.
In order to determine the status of any given feature, the following locations are checked, in order:
- System properties
- The packaged application configuration (i.e.
application.conf
) - The
defaultFeatureStatus
(which is set to bedisabled
by default)
Out-of-the-box, all features should be configured to have the default status. They should only be enabled on a per-environment basis using the mechanisms that are provided to achieve this.
The system or configuration property names for features follow a convention in the form microservice.services.customs-declare-imports-frontend.features.{featureName}
When running outside of production or live-like environments, the application provides an endpoint which can be used to
update a feature status. Use curl -X GET http://$CDS_IMPORTS_HOST/customs-declare-imports/test-only/feature/{featureName}/{status}
.
For example, to update the default feature status to enabled
, you could do curl -X GET http://$CDS_IMPORTS_HOST/customs-declare-imports/test-only/feature/default/enabled
.
Alternatively, you could pass the same system property when starting the application; e.g. sbt "run -Dmicroservice.services.customs-declare-imports-frontend.features.default=enabled"
###TestEndpoints
in order to enable the test endpoint we need to specify that we use a different router when starting play.
sbt run -Dapplication.router=testOnlyDoNotUseInAppConf.Routes
License
This code is open source software licensed under the Apache 2.0 License