swagger: '2.0'
info:
  title: Job Manager API
  version: '3.1'
  x-released: 'no'
  x-visibility: external
  description: >-
    Offers execution mechanisms for running models stored in Model Management module. A schedule is created based on a model identifier and a cron expression so the model will run one or multiple times. 
      Each time  a model runs a new job is generated.
      When the schedule is created it will start according to the cron expression. If a user wants to stop the executions it can update the status of the schedule and the executions will stop. Also the user has the possibility to update again the status and trigger again the schedule. 
      If a user does not want to run a model multiple times or based on a schedule expression it can start immediately a new job.  
schemes:
  - https
basePath: /api/jobmanager-1000001700/v3
securityDefinitions:
  jobmanager:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'
    scopes:
      prl.jm.e: allows starting and stopping execution of job executions; includes writes for retrieving results or defining new execution schedules.
      prl.jm.h: query history of job executions      
paths:
  /jobs:
    get:
      tags:
        - Jobs
      summary: >-
        Retrieves all the jobs executions 
      description: >-
        Retrieves all the job executions within a tenant, sorted by creationDate 
        descendant order, up to 10.000 items, paged, maximum 100 items per 
        request if no paging parameters are specified. The service purges 
        all jobs older than 90 days that have one of the final statuses
        (e.g. STOPPED, FAILED, SUCCEEDED).
      security:
        - jobmanager:
            - prl.jm.e
            - prl.jm.h
      operationId: getExecutionsForAModel
      consumes: 
        - application/json
        - multipart/form-data
      produces:
        - application/json
      parameters:
        - in: query
          name: pageNumber
          type: integer
          format: int32
          minimum: 0
          maximum: 10000
          required: false
          description: Specifies the requested page index
        - in: query
          name: pageSize
          type: integer
          format: int32
          minimum: 0
          maximum: 500
          required: false
          description: Specifies the number of elements in a page
        - in: query
          name: filter
          type: string
          required: false
          description: >-
            Complex and flexible filter that can filter by modelId, message, status and creationDate. <br />
            All the top fields used in the filter are ANDed, but the searched
            values can use AND and OR operands, including comparison operators
            where the values allow.
            All fields are optional.<br />
            The expected format follows:<br />
            ?filter={
              "message": {
                "contains": "Error"
              },
              "status": {
                "or": {
                  {"eq" : "STOPPED"},
                  {"eq" : "FAILED"}
                }
              },
              "creationDate": {
                {"after": "2018-06-23T20:09:00"}
              }
            }
      responses:
        '200':
          description: |
            The list with all the job executions within a tenant is retrieved . The list is empty if the model does not have job executions
          schema:
            $ref: '#/definitions/JobList'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          description: |
            Exception while getting the list of job executions
          schema:
            $ref: '#/definitions/Errors'
    post:
      tags:
        - Jobs
      summary: >-
       Creates a new job execution
      description: >-
        Creates a new job execution based on the model identifier. This endpoint offers the possibility of running a model or an algorithms just one time without the need of providing a schedule string
        The inputFolderId and outputFolderId are identifiers of data sources provided by Data Exchange module.
      security:
        - jobmanager:
            - prl.jm.e
      operationId: createSingeExecution
      consumes: 
        - application/json
        - multipart/form-data
      produces:
        - application/json
      parameters:
        - in: body
          name: parameters
          required: false 
          schema:
            $ref: '#/definitions/JobParameters'
      responses:
        '202':
          description: |
            The job was updated successfully and the response represents the job details 
          schema:
            $ref: '#/definitions/Job'
        '400':
          description: |
            Wrong input parameter
              - model does not exists
              - input or output folders are not created
              - configuration does not exist
              - maximumExecutionTimeInSeconds must be a positive number and must not exceed 30 days
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          description: |
            Exception while creating job execution
          schema:
            $ref: '#/definitions/Errors'
  /jobs/{id}:
    get:
      tags:
        - Jobs
      summary: Retrieves the details regarding a job execution
      description: Retrieves the details regarding a job execution
      security:
        - jobmanager:
            - prl.jm.e
      operationId: getExecutionDetails
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: the job execution id for which a user wants to retrieve the details
          required: true
          type: string
      responses:
        '200':
          description: |
            Returns the details of the execution
          schema:
            $ref: '#/definitions/Job'
        '404':
          description: |
            The job resource cannot be found
          schema:
            $ref: '#/definitions/Errors'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          description: |
            Exception while getting the details of an execution
          schema:
            $ref: '#/definitions/Errors'
  /jobs/{id}/stop:
    post:
      tags:
        - Jobs
      summary: Stops a job execution
      description: |
        Stops a job execution. The call sets the job's status to STOPPING,
        while letting the service to internally handle the additional 
        steps required to get the job into a STOPPED status.
        Caller is responsible for polling the status until the job has reached 
        a final state. In the event that the stop action fails for various 
        reasons, the job execution can end up with a FAILED status.
        Existing results that were resulted from execution will be kept and 
        provided to Data Exchange following the parameters used to start the 
        job execution. If no output parameters were defined, any definitive 
        (or partial) results will be lost and cleaned up during the stopping process.
      security:
        - jobmanager:
            - prl.jm.e
      operationId: stopExecution
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: the identifier of the job to be stopped
          required: true
          type: string
      responses:
        '202':
          description: |
            The job status will be updated to STOPPING and the response 
            simply returns the job's details
          schema:
            $ref: '#/definitions/Job'
        '400':
          description: |
            The job is in an incompatible state to perform a stop request
          schema:
            $ref: '#/responses/400-wrong-param'
        '404':
          description: |
            The job resource cannot be found
          schema:
            $ref: '#/definitions/Errors'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          description: |
            Exception during updating the status of an execution
          schema:
            $ref: '#/definitions/Errors'
  /schedules:
    get:
      tags:
        - Schedules
      summary: Retrieves a list with all schedules stored within the same tenant
      description: Retrieves a list with all schedules stored within the same tenant
      security:
        - jobmanager:
            - prl.jm.e
      operationId: getAllSchedules
      produces:
        - application/json
      parameters:
        - in: query
          name: pageNumber
          type: integer
          required: false
          description: Specifies the requested page index
        - in: query
          name: pageSize
          type: integer
          required: false
          description: Specifies the number of elements in a page
        - in: query
          name: filter
          type: string
          required: false
          description: >-
            Complex and flexible filter that can filter by creationDate, name, 
            status, modelId and scheduleString. <br />
            All the top fields used in the filter are ANDed, but the searched 
            values can use AND and OR operands, including comparison operators
            where the values allow.
            All fields are optional.<br />
            The expected filter format is:<br />
            ?filter={
              "status": {
                "eq": "RUNNING"
              },
              "message": {
                "eq": "Insufficient disk space"
              },
              "creationDate": {
                "gt": "2018-06-23T20:09:00"
              },
              "name": {
                "eq": "Every 2 Months"
              }
            }
      responses:
        '200':
          description: |
            Returns a list with schedules 
          schema:
            $ref: '#/definitions/ScheduleList'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          description: |
            Exception during retrieving the list of schedules
          schema:
            $ref: '#/definitions/Errors'
    post:
      tags:
        - Schedules
      summary: >-
        Schedules a job for execution specified by its model id and a cron string
      description: >-
        Schedules a job for execution specified by its model id and a schedule string. The model ID is retrieved from Model Management module after uploading a model. 
        The schedule string follows the cron format. Example 0 15 10 * * ? - will trigger the model at 10:15 am every day 
      security:
        - jobmanager:
            - prl.jm.e
      operationId: scheduleAModel
      consumes: 
        - application/json
        - multipart/form-data
      produces:
        - application/json
      parameters:
        - in: body
          name: parameters
          required: false 
          schema:
            $ref: '#/definitions/ScheduleParameters'
      responses:
        '200':
          description: |
            If the schedule was created and registered successfully for execution the details of the schedule are sent back
          schema:
            $ref: '#/definitions/ScheduleDetails'
        '400':
            $ref: '#/responses/400-wrong-param'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          description: |
            Exception during scheduling a model for execution.
          schema:
            $ref: '#/definitions/Errors'
  /schedules/{id}:
    get:
      tags:
        - Schedules
      summary: Retrieves information about a schedule
      description: Retrieves information about a schedule
      security:
        - jobmanager:
            - prl.jm.e
      operationId: getScheduler
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: the identifier of the schedule
          required: true
          type: string
      responses:
        '200':
          description: |
            Returns a list with schedules 
          schema:
            $ref: '#/definitions/ScheduleDetails'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          description: |
            Exception during retrieving the list of schedules
          schema:
            $ref: '#/definitions/Errors'
        '404':
          description: |
            The schedule resource cannot be found
          schema:
            $ref: '#/definitions/Errors'
    delete:
      tags:
        - Schedules
      summary: Removes a schedule
      description: This endpoint offers the possibility of removing a schedule from the storage
      security:
        - jobmanager:
            - prl.jm.e
      operationId: removeScheduler
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: the identifier of the schedule to be removed
          required: true
          type: string
      responses:
        '204':
          description: |
            Resource deleted successfully 
        '400':
          description: |
            Wrong input parameter 
            - The schedule cannot be deleted since it has executions in progress
          schema:
            $ref: '#/definitions/Errors'
        '404':
          description: |
            The schedule resource cannot be found
          schema:
            $ref: '#/definitions/Errors'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          description: |
            Exception while updating the status of the schedule to started
          schema:
            $ref: '#/definitions/Errors'
  /schedules/{id}/start:
     post:
      tags:
        - Schedules
      summary: Updates the status of the schedule to started
      description: Updates the status of the schedule to started. If a schedule has been stopped it can be started again using this endpoint. If a schedule is running, based on the schedule string it creates jobs
      security:
        - jobmanager:
            - prl.jm.e
      operationId: startScheduler
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: The identifier of the schedule which will be updated
          required: true
          type: string
      responses:
        '201':
          description: |
            The execution of the schedule according to the cron expression is started
          schema:
            $ref: '#/definitions/ScheduleDetails'
        '404':
          description: |
            The schedule resource cannot be found
          schema:
            $ref: '#/definitions/Errors'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          description: |
            Exception while updating the status of the schedule to started
          schema:
            $ref: '#/definitions/Errors'
  /schedules/{id}/stop:
     post:
      tags:
        - Schedules
      summary: Updates the status of the schedule to stopped
      description: Updates the status of the schedule to stopped. If a user wants to stop a schedule this endpoint offers the possibility to update the status of the schedule to stop. When a scheduler is stopped it cannot create new jobs executions
      security:
        - jobmanager:
            - prl.jm.e
      operationId: stopScheduler
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: The identifier of the schedule which will be updated
          required: true
          type: string
      responses:
        '202':
          description: |
            The schedule clock is stopped and will not trigger any executions
          schema:
            $ref: '#/definitions/ScheduleDetails'
        '404':
          description: |
            The schedule resource cannot be found
          schema:
            $ref: '#/definitions/Errors'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          description: |
            Exception while updating the status of the schedule to started
          schema:
            $ref: '#/definitions/Errors'
responses:
  403-unauth:
    description: Forbidden - The user does not have permission to execute this operation
    schema:
      $ref: '#/definitions/Errors'
  200-schedules:
    description: OK
    schema:
      $ref: '#/definitions/ScheduleList'
  200-jobexecutions:
    description: OK
    schema:
      $ref: '#/definitions/JobList'
  400-wrong-param:
    description: Wrong input parameter 
    
      - The model does not exists in Model Management
      
      - The cron expression is not valid
      
      - maxExecutionTime is negative
      
      - the action requested is not matching existing staet
    schema:
      $ref: '#/definitions/Errors'            
definitions:
  ScheduleList:
    type: object
    properties:
      schedules:
        type: array
        items:
          $ref: '#/definitions/ScheduleDetails'
      page:
        $ref: '#/definitions/Page' 
  ScheduleDetails:
    type: object
    properties:
      id:
        type: string
        format: uuid
        example: c603fb82-8417-11e8-adc0-fa7ae01bbebc
      name:
        type: string
        example: everyDay
      modelId:
        type: string
        format: uuid
        example: 951b3240-7857-11e8-adc0-fa7ae01bbebc
      scheduleString:
        type: string
        example: 0 15 10 * * ?
      creationDate:
        type: string
        format: date-time
        example: '2017-10-01T12:00:00.001Z'
      createdBy:
        type: string
        example: analytics
      status:
        description: schedule status
        type: string
        enum:
          - RUNNING
          - STOPPED
  JobList:
    type: object
    properties:
      jobs:
        type: array
        items:
          $ref: '#/definitions/Job'
      page:
        $ref: '#/definitions/Page' 
  Job:
    type: object
    properties:
      id:
        type: string
        format: uuid
        example: ah5b3240-7857-11e8-oki5-fa7ae01oopw
      modelId:
        type: string
        format: uuid
        description: ID of the model which is to be executed by the jobs
        example: 951b3240-7857-11e8-adc0-fa7ae01bbebc
      environmentId:
        type: string
        format: uuid
        description: ID of the environment in which the model is to be executed
        example: fh534d4-6f0e-11e8-adc0-fa7ae01bbebc
      message:
        type: string
        format: byte
        example: Job failed due to lack of input data
      status:
        type: string
        enum:
          - SUBMITTED
          - STARTING
          - RUNNING
          - SUCCEEDED
          - STOPPING
          - STOPPED
          - FAILED
      creationDate:
        type: string
        format: date-time
        example: '2017-10-01T12:00:00.001Z'
      createdBy:
        type: string
        description: Tenant who executed the job
        example: jobmgr
      inputFolderId:
        type: string 
        format: uuid
        description: The input folder with the input data required by the model 
        example: 17f9d94e-8417-11e8-adc0-fa7ae01bbebc
      outputFolderId:
        type: string
        format: uuid
        description: The output folder were the the results can be found after running the model
        example: 0cf21f02-8417-11e8-adc0-fa7ae01bbebc   
  VndError:
    type: object
    properties:
      code:
        type: string
        example: mdsp.core.jobmanager.error
        readOnly: true
      message:
        type: string
        example: Error message
        readOnly: true
      logref:
        type: string
        example: c06534d4-6f0e-11e8-adc0-fa7ae01bbebc
        readOnly: true
  Errors:
    type: object
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/VndError'
  JobParameters:
    type: object
    properties:
      modelId:
        type: string
        format: uuid
        description: ID of the model which is to be executed by the jobs
        example: 951b3240-7857-11e8-adc0-fa7ae01bbebc
      configurationId:
        type: string
        format: uuid
        description: >-
          ID of the configuration used to start the environment in which the model is to be executed
        example: hy1b3240-4163-11e8-adc0-fa7ae01bbubh
      inputFolderId:
        type: string 
        format: uuid
        description: The input folder with the input data required by the model 
        example: 17f9d94e-8417-11e8-adc0-fa7ae01bbebc
      outputFolderId:
        type: string
        format: uuid
        description: The output folder were the the results can be found after running the model
        example: 0cf21f02-8417-11e8-adc0-fa7ae01bbebc
      maximumExecutionTimeInSeconds:
        type: string
        format: int64
        description: Maximum execution time in seconds
        example: 60
  ScheduleParameters:
    type: object
    properties:
      modelId:
        type: string
        format: uuid
        description: ID of the model which is to be executed by the jobs
        example: 951b3240-7857-11e8-adc0-fa7ae01bbebc
      configurationId:
        type: string
        format: uuid
        description: ID of the configuration in which the model is to be executed
        example: hy1b3240-4163-11e8-adc0-fa7ae01bbubh
      scheduleString:
        type: string
        description: The cron expression which is used to trigger the (periodical) execution of the model
        example: 0 15 10 * * ?
      maximumExecutionTime:
        type: integer
        format: int64
        default: 7200
        minimum: 1
        description: Parameter which specifies how many times a job will run (in case the CRON job is a recurrent one)
      inputFolderId:
        type: string 
        format: uuid
        description: The input folder with the input data required by the model
        example: 17f9d94e-8417-11e8-adc0-fa7ae01bbebc
      outputFolderId:
        type: string
        format: uuid
        description: The output folder were the the results can be found after running the model     
        example: 0cf21f02-8417-11e8-adc0-fa7ae01bbebc
  Page:
    type: object
    properties:
      number:
        type: integer
        description: Number of current page.
      size:
        type: integer
        description: Size of the page
      totalPages:
        type: integer
        description: Number of the total pages
      totalElements:
        type: integer 