Merge branch 'master' into 1913-update-jobs-v3-tests

Author: despadam

Development/v4.x/Migration.md

@@ -1,4 +1,10 @@
-## Migrating from the old SciCat Backend
+# Migrating from the old SciCat Backend
+
+SciCat v4.x is a major rewrite from [v3.x](https://github.com/SciCatProject/backend-v3). The backend has been rewritten in typescript. It uses NestJS rather than Loopback 3 for the API, and includes a large number of new features. Version 3 is now considered deprecated and will receive only maintenance updates.
+
+This document is intended to help users of backend-v3 migrate to v4. It also describes major breaking changes between the two versions that will need to be updated in scicat clients or scripts.
+
+## Database changes
 
 Where the [current SciCat Backend](https://github.com/SciCatProject/backend) accepts id fields in the database named `pid`, `doi`, or similar, this implementation requires there to be an id field of the form `_id` on every document. It is therefore necessary to run a database migration script towards MongoDB instance from a place where you have access to it and can install `migrate-mongo` package.
 
@@ -16,20 +22,39 @@ if `migrate-mongo` is installed globally at the location where you want to run i
 ./node_modules/migrate-mongo/bin/migrate-mongo.js up
 ```
 
+## API changes
+
+### Base URL
+
+The scicat API was previously served at `/api/v3`. Many of the endpoints are backwards
+compatible and are still served at the same address. However, several schemas have added
+non-backwards-compabible features (eg. `Datasets`, `Attachements`, and `Jobs`). For
+these it is recommended to access the new `/api/v4` endpoints. Old `/api/v3` endpoints
+are still available for backwards compatibility, but will be removed in a future
+version.
+
+<!-- TODO: provide more details about the updated DTOs -->
+
+### Authorization
+
+Version 3 endpoints were authenticated by including an `access_token` query parameter in
+the URL. Following best practices, this has been changed to use the HTTP `Authorization:
+Bearer` header to pass the access token. All scicat clients must be updated for this
+change, even those using the otherwise backwards-compatible `/api/v3` endpoints.
+
 ## Migration documentation and NestJs resources
 Following are the post that I found useful working on the migration:
 - Schema and DTOs: https://betterprogramming.pub/how-to-use-data-transfer-objects-dto-for-validation-in-nest-js-7ff95309f650
 - Validation:
   - [Official documentation](https://docs.nestjs.com/techniques/validation)
   - [Custom validation with datasbase in NestJs](https://dev.to/avantar/custom-validation-with-database-in-nestjs-gao)
-  - [Validating nested objects with class-validator in NestJs](https://dev.to/avantar/validating-nested-objects-with-class-validator-in-nestjs-1gn8) 
+  - [Validating nested objects with class-validator in NestJs](https://dev.to/avantar/validating-nested-objects-with-class-validator-in-nestjs-1gn8)
   - [Validating numeric query parameters in NestJS](https://dev.to/avantar/validating-numeric-query-parameters-in-nestjs-gk9)
   - [Injecting request object to a custom validation class in NestJS](https://dev.to/avantar/injecting-request-object-to-a-custom-validation-class-in-nestjs-5dal)
 - Swagger and OpenAPI:
   - https://docs.nestjs.com/openapi/introduction
   - https://docs.nestjs.com/openapi/types-and-parameters
   - https://docs.nestjs.com/openapi/decorators
-
 ---
 
 For the full documentation please go to the [SciCat home page](https://scicatproject.github.io/) and follow the [documentation link](https://scicatproject.github.io/documentation)

Development/v4.x/backend/configuration.md

@@ -87,13 +87,26 @@ _src/config/configuration.ts_
   _example_: "group1,group2,group3,..."
 
 - DELETE\_JOB\_GROUPS:
-  list of non admin groups that are allowed to delete jobs for groups
-  they do not belong to. If set to "#all", all users can delete a job belonging to
-  any group.
+  groups that are allowed to delete jobs. If set to "#all", all users can delete a job
+  belonging to any group.
   _default_: ""
   _format_: comma separated list of strings. Leading and trailing spaces are trimmed
   _example_: "group1,group2,group3,..."
 
+- CREATE\_JOB\_PRIVILEGED\_GROUPS:
+  Comma separated list of groups with permission to create any job.
+  For more details check: [Jobs Authorization](authorization/authorization_jobs.md)
+  _default_: ""
+  _format_: comma separated list of strings. Leading and trailing spaces are trimmed
+  _example_: "archivemanager,jobmanager"
+
+- UPDATE\_JOB\_PRIVILEGED\_GROUPS:
+  Comma separated list of groups with permission to update any job.
+  For more details check: [Jobs Authorization](authorization/authorization_jobs.md)
+  _default_: ""
+  _format_: comma separated list of strings. Leading and trailing spaces are trimmed
+  _example_: "archivemanager,jobmanager"
+
 - ACCESS\_GROUPS\_STATIC\_VALUES:
   List of groups assigned by default to all users. Used in the vanilla implementation
   for easy configuration. If you do not want or need to assign any default group, it
@@ -477,3 +490,13 @@ _src/config/configuration.ts_
   If omitted, the jobs subsystem is inactive.
   _default_: "jobConfig.yaml", optional.
   _format_: string
+
+- JOB\_DEFAULT\_STATUS\_CODE:
+  Default statusCode for new jobs
+  _default_: "jobSubmitted", optional.
+  _format_: string
+
+- JOB\_DEFAULT\_STATUS\_MESSAGE
+  Default statusMessage for new jobs
+  _default_: "Job submitted.", optional.
+  _format_: string