openapi: 3.0.0
info:
  title: PeopleSync
  version: 1.0.0
  description: >
    **PeopleSync** synchronises the people of a project from a CSV file. It
    compares the file with

    what is already recorded, works out the difference, and applies only the
    changes needed: missing

    people are created, existing ones updated, and their offices and job
    assignments aligned to the

    file.


    The synchronisation runs as an asynchronous **Task**, because a file can
    hold thousands of rows.

    Starting a sync returns a task reference: poll the Task API to follow its
    progress and read the

    outcome.


    Use this API to:

    - Upload a CSV file and start a synchronisation for a project

    - Check the status and the result of a synchronisation you started
tags:
  - name: PeopleSync
servers:
  - url: http://service.4hse.com/
security:
  - Oauth2: []
  - AccessToken: []
paths:
  /people-sync/create:
    post:
      summary: create
      operationId: createPeopleSync
      tags:
        - PeopleSync
      description: >
        Create a new people sync task by uploading a CSV file and specifying the
        project and sync options.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - project_id
              properties:
                file:
                  type: string
                  format: binary
                  description: CSV file that contains data to synchronize.
                project_id:
                  type: string
                  description: The project identifier of people to synchronize.
                  example: b190e786-8b47-4575-9947-3b1f782e6356
                pk:
                  type: string
                  description: The name of the primary key field. It is used to uniquely identify
                    a person.
                  default: code
                  example: tax_code
                emulation:
                  type: boolean
                  description: If true, the request is executed in emulation mode (no changes are
                    made, but the changes and errors are reported).
                  default: 0
                  example: 1
                max_changes:
                  type: integer
                  description: Maximum number of changes allowed in the task. If exceeded, the
                    task is aborted.
                  default: 100
                  example: 150
                sync_type:
                  type: array
                  items:
                    type: string
                    enum:
                      - people
                      - offices
                      - jobs
                  description: Defines which datasets will be synchronized. "people" syncs a
                    single person, "offices" syncs person-office associations,
                    "jobs" syncs person-job associations. "offices" requires
                    "people", "jobs" requires "offices".
                  default:
                    - people
                  example:
                    - people
                    - offices
                    - jobs
      responses:
        "201":
          description: Task was created and put in queue
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id:
                    type: string
                    description: The created task ID. Use it to retrieve the current task status via
                      the /view endpoint.
                    example: task-1234
              example:
                task_id: task-1234
        "400":
          description: Bad request. Required parameter missing or invalid value.
        "403":
          description: Not allowed to synchronize data on the specified project due to
            permissions.
        "413":
          description: CSV file is too large.
        "500":
          description: Unknown internal server error.
  /people-sync/view/{id}:
    get:
      summary: view
      operationId: viewPeopleSync
      tags:
        - PeopleSync
      description: |
        Retrieve the status and result of a people sync task by its unique ID.
      parameters:
        - name: id
          in: path
          description: The task identifier
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The requested task data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
              example:
                task_id: task-1234
                user_id: admin@myproject.com
                status: DONE
                response:
                  result:
                    PS2:
                      - id: PS2
                        action: activate
                        periods:
                          - end_date: 2021-07-01 00:00:00
                            start_date: 2020-07-01 00:00:00
                          - end_date: ""
                            start_date: 2023-06-08 00:00:00
                    PS3:
                      - id: PS3
                        action: add
                    PS4:
                      - id: PS4
                        action: deactivate
                        periods:
                          - end_date: 2023-06-08 00:00:00
                            start_date: 2020-07-01 00:00:00
                    PS5:
                      - id: PS5
                        action: update
                        changes:
                          street: New street address
                          locality: New locality
                    PS6:
                      - id: OF2
                        action: add
                      - id: OF1
                        action: deactivate
                        periods:
                          - end_date: 2023-06-14 00:00:00
                            start_date: 1970-01-01 00:00:00
                      - id: OF2-JOB1
                        action: add
                  errors:
                    - line: 9
                      message: Invalid office code OF1234
                      info: ...
                  changes:
                    add: 2
                    update: 3
                    activate: 5
                    deactivate: 4
                    total: 14
                created_at: 2023-06-30 10:40:00
                updated_at: 2023-06-30 10:40:00
        "403":
          description: Not allowed to fetch task data due to permissions.
components:
  schemas:
    Task:
      type: object
      properties:
        task_id:
          type: string
          description: task identifier
          example: task-1234
        user_id:
          type: string
          description: identifier of the user who created the task
          example: admin@myproject.com
        status:
          type: string
          description: the current task status
          enum:
            - TODO
            - PENDING
            - PROCESSING
            - DONE
            - FAILED
        response:
          type: object
          properties:
            result:
              type: object
              example:
                PS2:
                  - id: PS2
                    action: activate
                    periods:
                      - end_date: 2021-07-01 00:00:00
                        start_date: 2020-07-01 00:00:0
                      - end_date: ""
                        start_date: 2023-06-08 00:00:00
                PS3:
                  - id: PS3
                    action: add
                PS4:
                  - id: PS4
                    action: deactivate
                    periods:
                      - end_date: 2023-06-08 00:00:00
                        start_date: 2020-07-01 00:00:00
                PS5:
                  - id: PS5
                    action: update
                    changes:
                      street: New street address
                      locality: New locality
                PS6:
                  - id: OF2
                    action: add
                  - id: OF1
                    action: deactivate
                    periods:
                      - end_date: 2023-06-14 00:00:00
                        start_date: 1970-01-01 00:00:00
                  - id: OF2-JOB1
                    action: add
            errors:
              type: array
              description: It lists eventually task execution errors
              items:
                type: object
                properties:
                  line:
                    type: integer
                    description: CSV file line that cointains the error
                    example: 9
                  message:
                    type: string
                    description: The error esplication
                    example: Invalid office code OF1234
                  info:
                    type: string
                    description: Error additional informations
                    example: ...
            changes:
              type: object
              description: It presents a summary of the applied changes after the task
                execution.
              properties:
                add:
                  type: integer
                  description: the total number of add operations
                  example: 2
                update:
                  type: integer
                  description: the total number of update operations
                  example: 3
                activate:
                  type: integer
                  description: the total number of activate operations
                  example: 5
                deactivate:
                  type: integer
                  description: the total number of deactivate operations
                  example: 4
                total:
                  type: integer
                  description: the total number of operations executed
                  example: 14
        created_at:
          type: string
          description: date time when task was created
          example: 2023-06-30 10:40:00
        updated_at:
          type: string
          description: date time when task was updated last
          example: 2023-06-30 10:40:00
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token
          scopes: {}
        refreshToken:
          tokenUrl: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token
          scopes: {}
    AccessToken:
      type: apiKey
      in: query
      name: access-token
