Merge pull request eclipse-tractusx#561 from catenax-ng/feature/TRI-1…

…664-new-batch-api-endpoint

feat(impl):[TRI-1664] new batch api endpoints impl

CHANGELOG.md

@@ -5,6 +5,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- Introduced new API endpoint to register ESS Jobs in Batch - POST {{IRS_HOST}}/irs/ess/orders
+
+### Changed
+- Deprecated query parameter 'jobStates' was removed from GET {{IRS_HOST}}/irs/jobs endpoint
 
 ## [3.5.3] - 2023-10-09
 ### Fixed

docs/src/api/irs-api.yaml

@@ -156,6 +156,61 @@ paths:
       summary: Accepts notifications sent via EDC.
       tags:
         - Environmental- and Social Standards
+  /irs/ess/orders:
+    post:
+      description: "Registers an order for an ESS investigation with an array of 
+      {globalAssetIds}. Each globalAssetId will be processed in an separate job, grouped in batches."
+      operationId: registerESSInvestigationOrder
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RegisterBpnInvestigationBatchOrder'
+        required: true
+      responses:
+        "201":
+          content:
+            application/json:
+              examples:
+                complete:
+                  $ref: '#/components/examples/job-handle'
+              schema:
+                $ref: '#/components/schemas/BatchOrderCreated'
+          description: Returns orderId of registered Batch order.
+        "400":
+          content:
+            application/json:
+              examples:
+                error:
+                  $ref: '#/components/examples/error-response-400'
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+          description: Batch Order registration failed.
+        "401":
+          content:
+            application/json:
+              examples:
+                error:
+                  $ref: '#/components/examples/error-response-401'
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+          description: No valid authentication credentials.
+        "403":
+          content:
+            application/json:
+              examples:
+                error:
+                  $ref: '#/components/examples/error-response-403'
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+          description: Authorization refused by server.
+      security:
+        - oAuth2:
+            - profile email
+      summary: "Registers an order for an ESS investigation with an array of {globalAssetIds}. 
+      Each globalAssetId will be processed in an separate job, grouped in batches."
+      tags:
+        - Environmental- and Social Standards
   /irs/jobs:
     get:
       description: Returns paginated jobs with state and execution times.
@@ -759,7 +814,7 @@ paths:
       responses:
         "200":
           content:
-            'application/json':
+            application/json:
               schema:
                 type: array
                 items:
@@ -1155,8 +1210,8 @@ components:
               - language: en
                 text: The shell for a vehicle
             globalAssetId: urn:uuid:a45a2246-f6e1-42da-b47d-5c3b58ed62e9
-            idShort: future concept x
             id: 882fc530-b69b-4707-95f6-5dbc5e9baaa8
+            idShort: future concept x
             specificAssetIds:
               - name: engineserialid
                 value: "12309481209312"
@@ -1186,13 +1241,13 @@ components:
                       href: https://catena-x.net/vehicle/partdetails/
                       endpointProtocol: HTTPS
                       endpointProtocolVersion: ["1.0"]
-                idShort: vehicle part details
                 id: dae4d249-6d66-4818-b576-bf52f3b9ae90
+                idShort: vehicle part details
                 semanticId:
-                  type: ModelReference
                   keys:
                     - type: Submodel
                       value: urn:bamm:com.catenax.vehicle:0.1.1#PartDetails
+                  type: ModelReference
         submodels:
           - aspectType: urn:bamm:io.catenax.single_level_bom_as_built:1.0.0
             identification: urn:uuid:fc784d2a-5506-4e61-8e34-21600f8cdeff
@@ -1335,8 +1390,8 @@ components:
               - language: en
                 text: The shell for a vehicle
             globalAssetId: urn:uuid:a45a2246-f6e1-42da-b47d-5c3b58ed62e9
-            idShort: future concept x
             id: 882fc530-b69b-4707-95f6-5dbc5e9baaa8
+            idShort: future concept x
             specificAssetIds:
               - name: engineserialid
                 value: "12309481209312"
@@ -1350,8 +1405,8 @@ components:
                       href: https://catena-x.net/vehicle/basedetails/
                       endpointProtocol: HTTPS
                       endpointProtocolVersion: ["1.0"]
-                idShort: vehicle base details
                 id: 4a738a24-b7d8-4989-9cd6-387772f40565
+                idShort: vehicle base details
                 semanticId:
                   type: ModelReference
                   keys:
@@ -1366,8 +1421,8 @@ components:
                       href: https://catena-x.net/vehicle/partdetails/
                       endpointProtocol: HTTPS
                       endpointProtocolVersion: ["1.0"]
-                idShort: vehicle part details
                 id: dae4d249-6d66-4818-b576-bf52f3b9ae90
+                idShort: vehicle part details
                 semanticId:
                   type: ModelReference
                   keys:
@@ -1468,10 +1523,10 @@ components:
           type: string
           description: Id of global asset.
           example: urn:uuid:6c311d29-5753-46d4-b32c-19b918ea93b0
-        idShort:
-          type: string
         id:
           type: string
+        idShort:
+          type: string
         specificAssetIds:
           type: array
           items:
@@ -1507,8 +1562,8 @@ components:
           minimum: 0
     BatchOrderCreated:
       type: object
-      description: Id of the created Batch order.
       additionalProperties: false
+      description: Id of the created Batch order.
       properties:
         id:
           type: string
@@ -2258,6 +2313,69 @@ components:
           minimum: 60
       required:
         - keys
+    RegisterBpnInvestigationBatchOrder:
+      type: object
+      additionalProperties: false
+      description: Request body for registering a new Batch Order for ESS Investigation
+        Job.
+      properties:
+        batchSize:
+          type: integer
+          format: int32
+          default: 20
+          description: Size of the batch.
+          maximum: 100
+          minimum: 10
+        batchStrategy:
+          type: string
+          description: The strategy how the batch is processed internally in IRS.
+          enum:
+            - PRESERVE_BATCH_JOB_ORDER
+            - PRESERVE_JOB_ORDER
+            - PRESERVE_BATCH_ORDER
+        bomLifecycle:
+          type: string
+          description: The lifecycle context in which the child part was assembled
+            into the parent part.
+          enum:
+            - asBuilt
+            - asPlanned
+            - asSpecified
+        callbackUrl:
+          type: string
+          description: "Callback url to notify requestor when job processing is finished.\
+                \ There are four uri variable placeholders that can be used: orderId,\
+                \ batchId, orderState and batchState."
+          example: "https://hostname.com/callback?orderId={orderId}&batchId={batchId}&orderState={orderState}&batchState={batchState}"
+        incidentBPNSs:
+          type: array
+          items:
+            type: string
+            pattern: "(BPN)[LSA][\\w\\d]{10}[\\w\\d]{2}"
+          maxItems: 2147483647
+        jobTimeout:
+          type: integer
+          format: int32
+          default: 3600
+          description: Timeout in seconds for each job processing inside the complete
+            order.
+          maximum: 7200
+          minimum: 60
+        keys:
+          type: array
+          items:
+            $ref: '#/components/schemas/PartChainIdentificationKey'
+          maxItems: 2147483647
+        timeout:
+          type: integer
+          format: int32
+          default: 43200
+          description: Timeout in seconds for the complete batch order processing.
+          maximum: 86400
+          minimum: 60
+      required:
+        - incidentBPNSs
+        - keys
     RegisterBpnInvestigationJob:
       type: object
       additionalProperties: false

irs-api/src/main/java/org/eclipse/tractusx/irs/connector/batch/BatchOrder.java

@@ -44,65 +44,41 @@
 @Jacksonized
 public class BatchOrder {
 
-    /**
-     * Batch Order Id
-     */
     private UUID batchOrderId;
 
-    /**
-     * Processing State of Batch Order
-     */
     @Setter
     private ProcessingState batchOrderState;
 
-    /**
-     * Bom Lifecycle requested in order
-     */
     private BomLifecycle bomLifecycle;
 
-    /**
-     * List of Aspects requested in order
-     */
     private List<String> aspects;
 
-    /**
-     * Depth requested in order
-     */
     private Integer depth;
 
-    /**
-     * Direction requested in order
-     */
     private Direction direction;
 
-    /**
-     * Needs of collect aspects
-     */
     private Boolean collectAspects;
 
-    /**
-     * Flag to specify whether BPNs should be collected and resolved via the configured BPDM URL
-     */
     private Boolean lookupBPNs;
 
-    /**
-     * Timeout for Batch Order
-     */
     private Integer timeout;
 
-    /**
-     * Timeout for Job in Batch
-     */
     private Integer jobTimeout;
 
-    /**
-     * Callback Url to send results
-     */
     private String callbackUrl;
 
+    private String owner;
+
+    private List<String> incidentBPNSs;
+
+    private JobType jobType;
+
     /**
-     * Owner
+     * JobType to create batch
      */
-    private String owner;
+    public enum JobType {
+        REGULAR,
+        ESS
+    }
 
 }

irs-api/src/main/java/org/eclipse/tractusx/irs/connector/job/MultiTransferJob.java

@@ -106,6 +106,10 @@ public JobParameter getJobParameter() {
         return getJob().getParameter();
     }
 
+    public boolean jobIsCompleted() {
+        return this.getJob().getState().equals(JobState.COMPLETED);
+    }
+
     /**
      * Builder for {@link MultiTransferJob}.
      */

irs-api/src/main/java/org/eclipse/tractusx/irs/controllers/BatchController.java

@@ -47,6 +47,7 @@
 import org.eclipse.tractusx.irs.component.BatchOrderResponse;
 import org.eclipse.tractusx.irs.component.BatchResponse;
 import org.eclipse.tractusx.irs.component.RegisterBatchOrder;
+import org.eclipse.tractusx.irs.component.RegisterBpnInvestigationBatchOrder;
 import org.eclipse.tractusx.irs.dtos.ErrorResponse;
 import org.eclipse.tractusx.irs.common.auth.AuthorizationService;
 import org.eclipse.tractusx.irs.services.CreationBatchService;
@@ -121,6 +122,45 @@ public BatchOrderCreated registerBatchOrder(final @Valid @RequestBody RegisterBa
         return BatchOrderCreated.builder().id(batchOrderId).build();
     }
 
+    @Operation(operationId = "registerESSInvestigationOrder",
+               summary = "Registers an order for an ESS investigation with an array of {globalAssetIds}. Each globalAssetId will be processed in an separate job, grouped in batches.",
+               security = @SecurityRequirement(name = "oAuth2", scopes = "profile email"),
+               tags = { "Environmental- and Social Standards" },
+               description = "Registers an order for an ESS investigation with an array of {globalAssetIds}. Each globalAssetId will be processed in an separate job, grouped in batches.")
+    @ApiResponses(value = { @ApiResponse(responseCode = "201", description = "Returns orderId of registered Batch order.",
+                                         content = { @Content(mediaType = APPLICATION_JSON_VALUE,
+                                                              schema = @Schema(implementation = BatchOrderCreated.class),
+                                                              examples = { @ExampleObject(name = "complete",
+                                                                                          ref = "#/components/examples/job-handle")
+                                                              })
+                                         }),
+                            @ApiResponse(responseCode = "400", description = "Batch Order registration failed.",
+                                         content = { @Content(mediaType = APPLICATION_JSON_VALUE,
+                                                              schema = @Schema(implementation = ErrorResponse.class),
+                                                              examples = @ExampleObject(name = "error",
+                                                                                        ref = "#/components/examples/error-response-400"))
+                                         }),
+                            @ApiResponse(responseCode = "401", description = UNAUTHORIZED_DESC,
+                                         content = { @Content(mediaType = APPLICATION_JSON_VALUE,
+                                                              schema = @Schema(implementation = ErrorResponse.class),
+                                                              examples = @ExampleObject(name = "error",
+                                                                                        ref = "#/components/examples/error-response-401"))
+                                         }),
+                            @ApiResponse(responseCode = "403", description = FORBIDDEN_DESC,
+                                         content = { @Content(mediaType = APPLICATION_JSON_VALUE,
+                                                              schema = @Schema(implementation = ErrorResponse.class),
+                                                              examples = @ExampleObject(name = "error",
+                                                                                        ref = "#/components/examples/error-response-403"))
+                                         }),
+    })
+    @PostMapping("/ess/orders")
+    @ResponseStatus(HttpStatus.CREATED)
+    @PreAuthorize("@authorizationService.verifyBpn() && hasAnyAuthority('" + IrsRoles.ADMIN_IRS + "', '" + IrsRoles.VIEW_IRS + "')")
+    public BatchOrderCreated registerESSInvestigationOrder(final @Valid @RequestBody RegisterBpnInvestigationBatchOrder request) {
+        final UUID batchOrderId = creationBatchService.create(request);
+        return BatchOrderCreated.builder().id(batchOrderId).build();
+    }
+
     @Operation(description = "Get a batch order for a given orderId.",
                operationId = "getBatchOrder",
                summary = "Get a batch order for a given orderId.",

irs-api/src/main/java/org/eclipse/tractusx/irs/controllers/IrsController.java

@@ -275,10 +275,8 @@ public PageResult getJobsByState(
                explode = Explode.FALSE, array = @ArraySchema(schema = @Schema(implementation = JobState.class), maxItems = Integer.MAX_VALUE))
             @RequestParam(value = "states", required = false, defaultValue = "") final List<JobState> states,
             @Parameter(hidden = true)
-            @RequestParam(value = "jobStates", required = false, defaultValue = "") final List<JobState> jobStates,
-            @Parameter(hidden = true)
             @ParameterObject final Pageable pageable) {
-        return itemJobService.getJobsByState(states, jobStates, pageable);
+        return itemJobService.getJobsByState(states, pageable);
     }
 
     @Operation(operationId = "getAllAspectModels",