openapi: 3.0.1
info:
  title: Batch Service
  description: The Batch Service Allows Bulk processing data.
  version: '2.0'
tags:
  - name: BatchService
security:
  - Authorization: []
paths:
  /batch/jobs:
    get:
      summary: |-
        Should return a paginated list of job objects (using the infinite scroll fashion).
        Supports sorting on the fields specified in the data model.
        Also supports doing a partial search on the job name field.
      operationId: BatchService_ListBatchJobs
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batchSearchBatchJobsResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googleRpcStatus'
      parameters:
        - name: tenantId
          description: 'Will use the tenantUtil to pull in from bearer token if not provided. Required: false'
          in: query
          required: false
          schema:
            type: string
        - name: sortField
          description: 'ENUM defined in proto CREATION_TIME/JOB_NAME/IMPORT_TYPE Required: true - Indexed/Sortable'
          in: query
          required: false
          schema:
            type: string
            enum:
              - CREATED_ON
              - IMPORT_TYPE
              - JOB_NAME
            default: CREATED_ON
        - name: sortType
          description: 'ENUM defined in proto none defaults to descending order NONE/ASC/DEC Required: true - Indexed/Sortable'
          in: query
          required: false
          schema:
            type: string
            enum:
              - NONE
              - ASC
              - DESC
            default: NONE
        - name: pageSize
          description: 'Page size of list items returned. Default: 10. Required: false'
          in: query
          required: false
          schema:
            type: integer
            format: int32
        - name: pageToken
          description: 'Auto generated page token to view results in order beyond page size. Required: false'
          in: query
          required: false
          schema:
            type: string
        - name: partialTextSearch
          description: 'Boolean value to search on jobName field by partial search. Required: false'
          in: query
          required: false
          schema:
            type: boolean
        - name: jobName
          description: 'Job Name field used only for partial search. Required: true (when partial search set to true)'
          in: query
          required: false
          schema:
            type: string
      tags:
        - BatchService
    post:
      summary: Creates and enqueues a batch job for asynchronous processing.
      description: |-
        The job creates new data records or updates existing ones based on the provided data. If a record
        with the same key/value pair already exists, the system will only update a specific subset of
        mutable fields unless 'replace_existing' is set to true.

        Supported upload formats for FSS uploads include CSV, XLS, and XLSX.

        For updates to existing Hierarchies, note that only the lowest tier is allowed to be removed.

        Permission Level: Read-Write
      operationId: BatchService_CreateBatchJob
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batchCreateJobsDataProto'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googleRpcStatus'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/batchCreateBatchJobRequest'
        required: true
      tags:
        - BatchService
  /batch/jobs/instance:
    post:
      summary: |-
        Create a batch job instance.
        This is for Schedule job failure. This will allow schedule service to save a batch job instance
        to track the failure.
      description: 'Permission Level: Read-Write'
      operationId: BatchService_SaveBatchJobInstance
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batchJobDetailsDataProto'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googleRpcStatus'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/batchJobDetailsDataProto'
        required: true
      tags:
        - BatchService
  /batch/jobs/{jobName}:
    get:
      summary: Get a batch job by its instance ID.
      description: 'Permission Level: Read'
      operationId: BatchService_GetBatchJob
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batchJobsDataProto'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googleRpcStatus'
      parameters:
        - name: jobName
          description: 'Job Name. Required: true'
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          description: 'Will use the tenantUtil to pull in from bearer token if not provided. Required: false'
          in: query
          required: false
          schema:
            type: string
      tags:
        - BatchService
    delete:
      summary: |-
        Deletes a specific job instance.
        When deleting a job instance we also should delete the associated file in the FSS.
      operationId: BatchService_DeleteBatchJob
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batchJobsDataProto'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googleRpcStatus'
      parameters:
        - name: jobName
          description: 'Job Name. Required: true'
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          description: 'Will use the tenantUtil to pull in from bearer token if not provided. Required: false'
          in: query
          required: false
          schema:
            type: string
      tags:
        - BatchService
  /batch/jobs/{jobName}/{instanceId}:
    get:
      summary: |-
        Returns a single job instance details object.
        Instance Id is the same as Batch Id when retrieving User batch details in the User Service.
        Support for retrieving other import types needs to be discussed with the POs.
        If a -1 is returned in the column_number for errors an internal error occurred with the spring-batch execution.
      operationId: BatchService_GetBatchJobInstance
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batchJobDetailsDataProto'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googleRpcStatus'
      parameters:
        - name: jobName
          description: 'Job Name. Required: true'
          in: path
          required: true
          schema:
            type: string
        - name: instanceId
          description: |-
            Specific job instance under a job name. Required: true
            Instance Id is the same as Batch Id when retrieving User batch details in the User Service.
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          description: 'Will use the tenantUtil to pull in from bearer token if not provided. Required: false'
          in: query
          required: false
          schema:
            type: string
      tags:
        - BatchService
    delete:
      summary: |-
        Deletes a specific job instance.
        When deleting a job instance we also should delete the associated file in the FSS
      operationId: BatchService_DeleteBatchJobInstance
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batchJobDetailsDataProto'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googleRpcStatus'
      parameters:
        - name: jobName
          description: 'Job Name. Required: true'
          in: path
          required: true
          schema:
            type: string
        - name: instanceId
          description: 'Specific job instance under a job name. Required: true'
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          description: 'Will use the tenantUtil to pull in from bearer token if not provided. Required: false'
          in: query
          required: false
          schema:
            type: string
      tags:
        - BatchService
    post:
      summary: |-
        Same functionality as Create Job but no body required,
        just uses the same file from the specific instance and all other details.
        Should be treated as a new instance with a new instanceId.
      operationId: BatchService_ReplayBatchJob
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batchJobsDataProto'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googleRpcStatus'
      parameters:
        - name: jobName
          description: 'Job Name. Required: true'
          in: path
          required: true
          schema:
            type: string
        - name: instanceId
          description: 'Specific job instance under a job name. Required: true'
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          description: 'Will use the tenantUtil to pull in from bearer token if not provided. Required: false'
          in: query
          required: false
          schema:
            type: string
      tags:
        - BatchService
servers:
  - url: https://prod-ui-zwseuprod01p.pp.zebra.com/api
    description: EU Server
  - url: https://prod-ui-zwsusprod01p.pp.zebra.com/api
    description: NA Server
components:
  schemas:
    batchCreateBatchJobRequest:
      type: object
      properties:
        tenantId:
          type: string
          title: 'Will use the tenantUtil to pull in from bearer token if not provided. Required: false'
        jobName:
          type: string
          title: 'Job Name. Required: true'
        importType:
          $ref: '#/components/schemas/commonsImportType'
        templateName:
          type: string
          title: Template Name pulled in from User Service. Required when uploading Users/
        ignoreHeader:
          type: boolean
          title: 'TODO: functionality in progress. Required = false'
        replaceExisting:
          type: boolean
          description: Boolean value to replace existing Users upon upload. Not supported for Permission Templates upload type Required = false.
        file:
          $ref: '#/components/schemas/commonsFile'
        signedUrl:
          type: string
          description: 'A signed URL for a GCS bucket. Required: false.'
        sftpDetails:
          $ref: '#/components/schemas/commonsSFTPDetails'
        fssId:
          type: string
          title: 'Unique identifier of file from FSS (File Store Service). Allowed file types: CSV,XLS, and XLSX. Required: false'
        gcsDetails:
          $ref: '#/components/schemas/commonsGcsDetails'
        emails:
          type: array
          items:
            type: string
          description: Email(s) to be sent upon Job completion/failure.
        deviation:
          type: integer
          format: int32
          title: 'The acceptable deviation percentage from 1-99 from previous file upload. Required:  false'
        dryRun:
          type: boolean
          title: 'TODO: functionality in progress. Required = False'
    batchCreateJobsDataProto:
      type: object
      properties:
        tenantId:
          type: string
        jobName:
          type: string
        importType:
          $ref: '#/components/schemas/commonsImportType'
        status:
          $ref: '#/components/schemas/servicesBatchStatus'
        message:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        fssId:
          type: string
        instanceId:
          type: string
        historicalJobs:
          type: array
          items:
            $ref: '#/components/schemas/batchHistoricalJobProto'
        creationTime:
          type: string
          format: date-time
        createdBy:
          type: string
        emails:
          type: array
          items:
            type: string
        deviation:
          type: integer
          format: int32
    batchErrorProto:
      type: object
      properties:
        columnNumber:
          type: string
        errorMessage:
          type: string
    batchHistoricalJobProto:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/servicesBatchStatus'
        message:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        fssId:
          type: string
        instanceId:
          type: string
    batchJobDetailsDataProto:
      type: object
      properties:
        tenantId:
          type: string
        instanceId:
          type: string
        jobName:
          type: string
        importType:
          $ref: '#/components/schemas/commonsImportType'
        status:
          $ref: '#/components/schemas/servicesBatchStatus'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/batchErrorProto'
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        fssId:
          type: string
        recordsProcessed:
          type: integer
          format: int32
        totalErrors:
          type: integer
          format: int32
        creationTime:
          type: string
          format: date-time
        createdBy:
          type: string
        created:
          type: integer
          format: int32
        updated:
          type: integer
          format: int32
        deleted:
          type: integer
          format: int32
    batchJobsDataProto:
      type: object
      properties:
        tenantId:
          type: string
        jobName:
          type: string
        importType:
          $ref: '#/components/schemas/commonsImportType'
        status:
          $ref: '#/components/schemas/servicesBatchStatus'
        message:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        fssId:
          type: string
        instanceId:
          type: string
        historicalJobs:
          type: array
          items:
            $ref: '#/components/schemas/batchHistoricalJobProto'
        creationTime:
          type: string
          format: date-time
        createdBy:
          type: string
        created:
          type: integer
          format: int32
        updated:
          type: integer
          format: int32
        deleted:
          type: integer
          format: int32
        emails:
          type: array
          items:
            type: string
    batchSearchBatchJobsResponse:
      type: object
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/batchJobsDataProto'
        nextPageToken:
          type: string
    batchSortJobsEnum:
      type: string
      enum:
        - CREATED_ON
        - IMPORT_TYPE
        - JOB_NAME
      default: CREATED_ON
    commonsFile:
      type: object
      properties:
        content:
          type: string
          format: byte
      description: This protobuf message represents any file through an array of bytes.
    commonsGcsDetails:
      type: object
      properties:
        projectId:
          type: string
        bucketName:
          type: string
        keyFile:
          type: string
        fileName:
          type: string
      description: GCS Details are used for granting access to a GCS bucket for us to read the file from.
    commonsImportType:
      type: string
      enum:
        - USERS
        - ROLES
        - WORKSPACES
        - SITES
        - DEPARTMENTS
        - HIERARCHIES
        - SITE_TEMPLATES
        - PERMISSION_TEMPLATES
        - GROUPS
        - LOCATIONS
      default: USERS
      description: |-
        The type of data being imported.

         - LOCATIONS: The import file is forwarded directly to the zac-server locations API
        Constraints:
          - template_name, deviation, and dry_run are all ignored.
          - zac-server performs an upsert always, any errors in the file will fail the entire file
    commonsSFTPDetails:
      type: object
      properties:
        host:
          type: string
          title: 'SFTP Server host, Required: true'
        port:
          type: integer
          format: int32
          title: 'SFTP Server port, Default: 22, Required: false'
        directory:
          type: string
          title: 'Directory in SFTP Server of the file to fetch, Required: true'
        fileName:
          type: string
          title: 'Name of the file including file extension, Required: true (Example - userdata.csv)'
        username:
          type: string
          title: 'Username for SFTP authentication, Required: true'
        password:
          type: string
          title: 'Password for SFTP authentication, Required: true'
        sshKey:
          type: string
      title: Remote SFTP Server details to fetch file from
    commonsSortType:
      type: string
      enum:
        - NONE
        - ASC
        - DESC
      default: NONE
    googleRpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
    protobufAny:
      type: object
      properties:
        '@type':
          type: string
      additionalProperties: {}
    servicesBatchStatus:
      type: string
      enum:
        - UNKNOWN_STATUS
        - PENDING
        - IN_PROGRESS
        - SUCCEEDED
        - SUCCEEDED_WITH_ERRORS
        - FAILED
      default: UNKNOWN_STATUS
  securitySchemes:
    Authorization:
      type: apiKey
      description: Bearer token
      name: Authorization
      in: header