Skip to content

service-onboarding.md

Latest commit

 

History

History
85 lines (51 loc) · 4.76 KB

service-onboarding.md

File metadata and controls

85 lines (51 loc) · 4.76 KB

Onboard a new service

Onboarding a new service to the Document Evidence Service requires:

  1. Setting up the service specific configuration by creating a new sheet in this document
  2. Authentication, which will depend on your use case, see section below.

⚙️ Configuration

There are a couple of configurations that need to take place:

Service Areas

Add their team configuration to document-evidence-store-frontend/teams.json. Ensure to add:

  • a machine readable ID (this should contain no spaces, and only contain lowercase letters, numbers and hyphens)
  • a human readable group name
  • Google Group that matches configuration in auth-groups.json
  • Other fields which the service provided in the onboarding sheet, such as reasons and landingMessage

Document Types

Add any document types that the service deals with to EvidenceApi/DocumentTypes.json and EvidenceApi/StaffSelectedDocumentTypes.json. Ensure to add:

  • the team ID that was created in teams.json
  • a human readable title
  • a description (this will be shown to the resident, so please ensure it describes what they need to provide and any important details)
  • whether the document type is enabled=true or enabled=false. The purpose of this flag is to give service areas the option to remove any document types they no longer need, but preserve the document type of legacy documents, so the frontend doesn't crash (because it'll try and look for something that no longer exists). Any new document types would be by default enabled=true. If a service area no longer needs a specific document, you can change this to enabled=false.

The easiest way to do this is to use Github to edit the file directly and open a Pull Request for a developer to review. If this is your first time doing that, there is a handy guide here. Alternatively, you can ask a developer to help you with this instead.

🔐 Authentication

This depends on the team use case:

  • Officers create and manage evidence requests through the DES frontend
    • Follow the Document Evidence Service Frontend section
  • Programmatically perform some actions with officers managing evidence requests through the DES frontend
    • Follow both sections
  • Programmatic access only
    • Follow the APIs section

Document Evidence Service Frontend

To ensure officers of your service can be authenticated properly with the DES frontend, add their Google Groups to document-evidence-store-frontend/auth-groups.json.

  • Groups are configured for each environment - development, staging, and production - which allows us to be specific about which group is able to access instances of the service
  • Make sure you're OK with everyone who is in the Google Groups getting access to the service (i.e. only add Google Groups which contain the people you want to give access).

The JSON file is designed to be easy to amend by anyone—all it needs is the Google Group and a human readable name for the service.

⚠️ Do not delete a Google Group — this could break records that exist in the database for that service. If you need to, speak to a developer to update the database records first.

APIs

SwaggerHub

HTTP Headers

At the time of writing 2 headers are required for interacting with evidence-api endpoints. These are detailed in the SwaggerHub Docs and we also wanted to describe them here.

Authorization

The client needs to provide an Authorization bearer token. We use the HackIT Lambda authorizer which means tokens are required for each HTTP method and path.

To give an example - if a client is wanting to invoke the following endpoints:

  • POST /api/v1/evidence_requests/{evidenceRequestId}/document_submissions
  • GET /api/v1/evidence_requests/{id}

The service area will need to contact someone from the HackIT team to have these tokens generated for them. A token per path and per environment is needed. Other information that needs to be provided is the AWS account and the service name.

  • POST evidence_requests
  • GET evidence_requests
UserEmail

This field is for audit purposes and should be the name of the service accessing the endpoint.

Help!

If you're stuck then please reach out on our Slack channel #document-management-support