openapi: 3.0.3
info:
  title: cx-announcement-service
  version: '1.0'
  description: Details a group of APIs that act upon Announcements.
  contact:
    name: CS+ Team
servers:
  - url: http://localhost:8080
    description: ''
tags:
  - name: announcement-display-controller
  - name: announcement-crud-controller
  - name: announcement-history-controller
paths:
  /{salesOrg}/announcements:
    parameters:
      - $ref: '#/components/parameters/salesOrg'
    get:
      summary: Get all announcements
      tags:
        - announcement-crud-controller
      operationId: get-announcements
      description: |-
        Retrieve all announcements in this collection.
        Possible error outcomes:
        * ANN-001
      responses:
        '200':
          $ref: '#/components/responses/AnnouncementPage'
        '400':
          $ref: '#/components/responses/400'
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/size'
        - $ref: '#/components/parameters/acceptLanguage'
        - $ref: '#/components/parameters/refreshPriorities'
        - $ref: '#/components/parameters/isOnTrade'
        - $ref: '#/components/parameters/scope'
    post:
      summary: Add a new announcement
      operationId: create-announcement
      responses:
        '200':
          $ref: '#/components/responses/Announcement'
        '400':
          $ref: '#/components/responses/400'
      description: |-
        Add a new announcement to this collection of announcements.
        Possible error outcomes:
        * ANN-001
        * ANN-002
        * ANN-006
        * ANN-007
        * ANN-008
      tags:
        - announcement-crud-controller
      requestBody:
        $ref: '#/components/requestBodies/CreateAnnouncement'
  /{salesOrg}/announcements/{announcementId}:
    get:
      summary: Get announcement by ID
      operationId: get-announcement-by-ID
      description: |-
        Use this endpoint to retrieve an announcement by ID.
        Possible error outcomes:
        * ANN-001
        * ANN-003
      tags:
        - announcement-crud-controller
      responses:
        '200':
          $ref: '#/components/responses/Announcement'
        '400':
          $ref: '#/components/responses/400'
      parameters:
        - $ref: '#/components/parameters/acceptLanguage'
    put:
      summary: Update announcement
      operationId: update-announcement
      description: |-
        Use this endpoint to update an announcement.
        Update an announcement to change its details or to dismiss it.
        Possible error outcomes:
        * ANN-001
        * ANN-002
        * ANN-003
        * ANN-004
        * ANN-005
        * ANN-006
        * ANN-007
        * ANN-008
        * ANN-009
      tags:
        - announcement-crud-controller
      requestBody:
        $ref: '#/components/requestBodies/UpdateAnnouncement'
      responses:
        '200':
          $ref: '#/components/responses/Announcement'
        '400':
          $ref: '#/components/responses/400'
    parameters:
      - $ref: '#/components/parameters/salesOrg'
      - $ref: '#/components/parameters/announcementId'
    delete:
      summary: Delete Announcement
      operationId: delete-announcement
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/400'
      description: |-
        Deletes an announcement by ID.
        Possible error outcomes:
        * ANN-001
      tags:
        - announcement-crud-controller
  /{salesOrg}/display:
    parameters:
      - $ref: '#/components/parameters/salesOrg'
    post:
      summary: Get targeted Announcements
      operationId: display-to
      responses:
        '200':
          $ref: '#/components/responses/AnnouncementPage'
        '400':
          $ref: '#/components/responses/400'
      parameters:
        - $ref: '#/components/parameters/size'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/acceptLanguage'
        - $ref: '#/components/parameters/isOnTrade'
        - $ref: '#/components/parameters/scope'
      description: |-
        The endpoint to retrieve announcements to display.
        Given a target (target group, outlet, user) return all valid, enabled and not dismissed announcements in a paginated manner.
        Possible error outcomes:
        * ANN-001
        * ANN-002
      tags:
        - announcement-display-controller
      requestBody:
        $ref: '#/components/requestBodies/DisplayTo'
  /{salesOrg}/announcements/{announcementId}/history:
    parameters:
      - $ref: '#/components/parameters/salesOrg'
      - $ref: '#/components/parameters/announcementId'
    get:
      summary: Get history log
      responses:
        '200':
          $ref: '#/components/responses/HistoryPage'
        '400':
          $ref: '#/components/responses/400'
      operationId: get-history-log
      description: |-
        Retrieve the history log for an announcement.
        Possible error outcomes:
        * ANN-001
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/size'
        - $ref: '#/components/parameters/event'
        - $ref: '#/components/parameters/author'
      tags:
        - announcement-history-controller
components:
  requestBodies:
    CreateAnnouncement:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateAnnouncement-v1'
      description: Body used to create a new announcement.
    UpdateAnnouncement:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateAnnouncement-v1'
      description: Body used to update an announcement.
    DisplayTo:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DisplayTo-v1'
      description: Body specifying the targeted to display announcements to.
  responses:
    '400':
      description: |-
        Bad request error

         - ANN-001 - SalesOrg is not available
         - ANN-002 - Mandatory fields is not on the request body
         - ANN-003 - Announcement is not found
         - ANN-004 - Cannot dismiss announcement that is not DISMISSIBLE
         - ANN-005 - Fields cannot be edited after creation
         - ANN-006 - ValidFrom must be before ValidTo
         - ANN-007 - ValidTo must be a date in the future
         - ANN-008 - When provided, message must contain 1 object
         - ANN-009 - Must specify at least one target for dismissal
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WithErrorCode-v1'
          examples:
            ANN-001 - SalesOrg Not Found:
              value:
                title: Bad Request
                status: 400
                detail: 'SalesOrg: ''0000'' not found'
                errorCode: ANN-001
            ANN-002 - Required parameters missing:
              value:
                title: Bad Request
                status: 400
                detail: Required parameters missing
                errorCode: ANN-002
                errorMetadata:
                  fields:
                    - param1
                    - param2
            ANN-003 - Announcement not found:
              value:
                title: Bad Request
                status: 400
                detail: 'Announcement: ''id'' not found'
                errorCode: ANN-003
            ANN-004 - Cannot dismiss announcement that is not DISMISSIBLE:
              value:
                title: Bad Request
                status: 400
                detail: Cannot dismiss announcement that is not DISMISSIBLE
                errorCode: ANN-001
            ANN-005 - Fields cannot be edited after creation:
              value:
                title: Bad Request
                status: 400
                detail: Fields cannot be edited after creation
                errorCode: ANN-005
                errorMetadata:
                  fields:
                    - param1
                    - param2
            ANN-006 - ValidFrom must be before ValidTo:
              value:
                title: Bad Request
                status: 400
                detail: ValidFrom must be before ValidTo
                errorCode: ANN-006
            ANN-007 - ValidTo must be a date in the future:
              value:
                title: Bad Request
                status: 400
                detail: ValidTo must be a date in the future
                errorCode: ANN-007
            ANN-008 - When provided, message must contain 1 object:
              value:
                title: Bad Request
                status: 400
                detail: When provided, message must contain 1 object
                errorCode: ANN-008
            ANN-009 - Must specify at least one target for dismissal:
              value:
                title: Bad Request
                status: 400
                detail: Must specify at least one target for dismissal
                errorCode: ANN-009
    Announcement:
      description: An announcement response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Announcement-v1'
    AnnouncementPage:
      description: Example paginated announcements response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AnnouncementPage-v1'
    HistoryPage:
      description: Paginated history log response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HistoryPage-v1'
  parameters:
    salesOrg:
      name: salesOrg
      in: path
      required: true
      schema:
        type: string
        minLength: 4
        maxLength: 4
      description: The sales organization
    announcementId:
      name: announcementId
      in: path
      required: true
      schema:
        type: string
      description: The ID of the announcement
    size:
      name: size
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        default: 10
      description: The size of each page
    page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
      description: The page we want to fetch
    acceptLanguage:
      name: Accept-Language
      in: header
      schema:
        type: string
        pattern: '[a-z]{2}-[A-Z]{2}'
        example: en-GB
      description: When present filter in only given language
    refreshPriorities:
      name: refreshPriorities
      in: query
      required: false
      schema:
        type: boolean
        default: false
      description: If true, outdated announcements with priority will be updated to not have priority. And then all announcement with priorities will be reordered.
    author:
      name: author
      in: query
      required: false
      schema:
        type: string
      description: The author of the change to the announcement.
    event:
      name: event
      in: query
      required: false
      schema:
        type: string
      description: The event done on an announcement (update, creation, deletion)
    isOnTrade:
      name: isOnTrade
      required: false
      in: query
      schema:
        type: boolean
      description: If target is On-trade or Off-trade
    scope:
      name: scope
      in: query
      required: false
      schema:
        type: string
        example: CADI
      description: The announcement scope
  schemas:
    WithErrorCode-v1:
      title: Errors With Error Code
      type: object
      properties:
        title:
          type: string
          description: A short summary of the problem type. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
          example: Bad Request
        status:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          minimum: 100
          example: 400
        detail:
          type: string
          description: A human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
          example: 'Customer: ''620069'' not found'
        errorCode:
          type: string
          description: The error code of this problem
          example: CSP-001
        errorMessage:
          type: string
          description: Brief message about the error. It is usually key message beside errorCode for client to identify the problem.
        errorMetadata:
          type: object
          description: Specific metadata for the error code
      required:
        - title
        - status
        - detail
        - errorCode
    Page-v1:
      title: page-v1
      type: object
      properties:
        page:
          type: integer
          description: the current page
        totalPages:
          type: integer
          description: the total number of pages
        totalElements:
          type: integer
          description: the total number of elements
        numberOfElements:
          type: integer
          description: number of elements in this page
        size:
          type: integer
          description: the size of each page
      description: 'Pagination metadata for page method '
    CreateAnnouncement-v1:
      title: CreateAnnouncement
      type: object
      description: Used to create a new announcement.
      properties:
        author:
          type: string
          description: the eid of the user that create the announcement
        dismissible:
          type: string
          description: |-
            Scope of dismissibility of the announcement.
            Possible values:
            * DISMISSIBLE
            * NOT_DISMISSIBLE
            * SESSION
          example: DISMISSIBLE
        scope:
          type: object
          description: The scope of this announcement.
          required:
            - application
          properties:
            application:
              type: string
              description: |-
                The application scope of this announcement.
                Possible values:
                * CSPLUS
                * CADI
              example: CSPLUS
        details:
          type: object
          description: The details of the announcement.
          required:
            - message
            - severity
            - priority
          properties:
            message:
              type: array
              uniqueItems: true
              minItems: 1
              description: Represents the message details of the announcement in different languages.
              items:
                type: object
                properties:
                  title:
                    type: string
                    description: The title of the announcement.
                  body:
                    type: string
                    description: The body of the announcement.
                  locale:
                    type: string
                    description: The language of the announcement.
                    pattern: '[a-z]{2}-[A-Z]{2}'
                    example: en-GB
                    minLength: 5
                    maxLength: 5
                required:
                  - title
                  - body
                  - locale
            severity:
              type: string
              description: |-
                Enum with severity levels.
                Possible values:
                * CRITICAL
                * WARN
                * INFO
              example: CRITICAL
            priority:
              type: integer
              description: Priority levels.
              format: int32
              minimum: 1
        target:
          type: object
          description: The target of the announcement.
          properties:
            outlets:
              type: array
              description: Outlets target of this announcement.
              items:
                type: string
            targetGroups:
              type: array
              description: Target Groups target of this announcement.
              items:
                type: string
            userIds:
              type: array
              description: Target User ids of this announcement.
              items:
                type: string
        validity:
          type: object
          description: The validity of this announcement.
          required:
            - from
            - to
          properties:
            from:
              type: string
              format: date-time
              description: Announcement valid from this date-time.
            to:
              type: string
              format: date-time
              description: Announcement valid to this date-time.
        enabled:
          type: boolean
          default: false
          description: Whether the announcement is enabled or not.
        state:
          type: string
          description: |-
            The state of the document. Possible Values:
            * DRAFT
            * COMPLETE
          example: DRAFT
        properties:
          type: array
          description: flex properties
          items:
            type: object
            properties:
              key:
                type: string
                description: Flexfield key
              value:
                type: string
                description: Flexfield value
        isOnTrade:
          type: boolean
          description: If the target market is OnTrade or OffTrade
      required:
        - dismissible
        - scope
        - details
        - validity
        - enabled
        - state
    DisplayTo-v1:
      title: displayTo-v1
      type: object
      description: Input to retrieve announcements for a given target.
      properties:
        target:
          type: object
          properties:
            outlets:
              type: array
              description: The outlets to display to.
              items:
                type: string
            targetGroups:
              type: array
              description: The target groups to display to.
              items:
                type: string
            userIds:
              type: array
              description: The Users ids to display to.
              items:
                type: string
    UpdateAnnouncement-v1:
      title: UpdateAnnouncement
      type: object
      description: |-
        Used to update an existing announcement.
        An update might be changes to the details or the dismissal of the announcement.
      properties:
        author:
          type: string
          description: the eid of the user that update the announcement
        dismissible:
          type: string
          description: |-
            Scope of dismissibility of the announcement.
            Possible values:
            * DISMISSIBLE
            * NOT_DISMISSIBLE
            * SESSION
          example: DISMISSIBLE
        details:
          type: object
          description: The details of the announcement.
          properties:
            message:
              type: array
              uniqueItems: true
              minItems: 1
              description: Represents the message details of the announcement in different languages.
              items:
                type: object
                properties:
                  title:
                    type: string
                    description: The title of the announcement.
                  body:
                    type: string
                    description: The body of the announcement.
                  locale:
                    type: string
                    description: The language of the announcement.
                    pattern: '[a-z]{2}-[A-Z]{2}'
                    minLength: 5
                    maxLength: 5
                    example: en-GB
            severity:
              type: string
              description: |-
                Enum with severity levels.
                Possible values:
                * CRITICAL
                * WARN
                * INFO
              example: CRITICAL
            priority:
              type: integer
              description: Priority levels.
              format: int32
              minimum: 1
        target:
          type: object
          description: The target of the announcement.
          properties:
            outlets:
              type: array
              description: Outlets target of this announcement.
              items:
                type: string
            targetGroups:
              type: array
              description: Target Groups target of this announcement.
              items:
                type: string
            userIds:
              type: array
              description: Target User ids of this announcement.
              items:
                type: string
        validity:
          type: object
          description: The validity of this announcement.
          properties:
            from:
              type: string
              format: date-time
              description: Announcement valid from this date-time.
            to:
              type: string
              format: date-time
              description: Announcement valid to this date-time.
        dismissal:
          type: object
          properties:
            outlets:
              type: array
              description: The outlets dismissing this announcement.
              items:
                type: string
            targetGroups:
              type: array
              description: Target Groups dismissing this announcement.
              items:
                type: string
            userIds:
              type: array
              description: User ids that can dismiss this announcement.
              items:
                type: string
        enabled:
          type: boolean
          description: Whether the announcement is enabled or not.
        state:
          type: string
          description: |-
            The state of the document. Possible Values:
            * DRAFT
            * COMPLETE
          example: DRAFT
        properties:
          type: array
          description: flex properties
          items:
            type: object
            properties:
              key:
                type: string
                description: Flexfield key
              value:
                type: string
                description: Flexfield value
    Announcement-v1:
      title: Announcement
      type: object
      description: The fully detailed announcement.
      properties:
        eid:
          type: string
          description: the eid of the announcement
        salesOrg:
          type: string
          minLength: 4
          maxLength: 4
          description: the sales org
        dismissible:
          type: string
          description: |-
            Scope of dismissibility of the announcement.
            Possible values:
            * DISMISSIBLE
            * NOT_DISMISSIBLE
            * SESSION
        scope:
          type: object
          description: The scope of this announcement.
          properties:
            application:
              type: string
              description: |-
                The application scope of this announcement.
                Possible values:
                * CSPLUS
                * CADI
        details:
          type: object
          description: The details of the announcement.
          properties:
            message:
              type: array
              uniqueItems: true
              minItems: 1
              description: Represents the message details of the announcement in different languages.
              items:
                type: object
                properties:
                  title:
                    type: string
                    description: The title of the announcement.
                  body:
                    type: string
                    description: The body of the announcement.
                  locale:
                    type: string
                    example: en-GB
                    description: The language of the announcement.
                    pattern: '[a-z]{2}-[A-Z]{2}'
                    minLength: 5
                    maxLength: 5
            severity:
              type: string
              description: |-
                Enum with severity levels.
                Possible values:
                * CRITICAL
                * WARN
                * INFO
            priority:
              type: integer
              description: Priority levels.
              format: int32
        validity:
          type: object
          description: The validity of this announcement.
          properties:
            from:
              type: string
              format: date-time
              description: Announcement valid from this date-time.
            to:
              type: string
              format: date-time
              description: Announcement valid to this date-time.
        target:
          type: object
          description: The target of the announcement.
          properties:
            outlets:
              type: array
              description: Outlets target of this announcement.
              items:
                type: string
            targetGroups:
              type: array
              description: Target Groups target of this announcement.
              items:
                type: string
            userIds:
              type: array
              description: Target user ids of this announcement.
              items:
                type: string
        status:
          type: object
          description: The status of the announcement, whether it is active, inactive or to whom it has been dismissed.
          properties:
            enabled:
              type: boolean
              description: Whether the announcement is enabled or not.
            dismissal:
              type: object
              description: The dismissal object - used to dismiss an announcement for someone.
              properties:
                outlets:
                  type: array
                  description: By whom was the announcement dismissed
                  items:
                    type: string
                targetGroups:
                  type: array
                  description: By whom was the announcement dismissed
                  items:
                    type: string
                userIds:
                  type: array
                  description: By whom was the announcement dismissed
                  items:
                    type: string
            state:
              type: string
              description: |-
                The state of the document. Possible Values:
                * DRAFT
                * COMPLETE
              example: DRAFT
        properties:
          type: array
          description: flex properties
          items:
            type: object
            properties:
              key:
                type: string
                description: Flexfield key
              value:
                type: string
                description: Flexfield value
        createdAt:
          type: string
          format: date-time
          description: the date-time of the creation
        modifiedAt:
          type: string
          format: date-time
          description: the last date-time of the modification
        author:
          type: string
          description: the eid of the user that create the announcement
        modifiedBy:
          type: string
          description: the eid of the last user that update the announcement
        isOnTrade:
          type: boolean
          description: If the target market is OnTrade or OffTrade
    AnnouncementPage-v1:
      title: announcementPage-v1
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/Announcement-v1'
        pagination:
          $ref: '#/components/schemas/Page-v1'
    History-v1:
      title: History
      type: object
      description: The details of an history log.
      properties:
        salesOrg:
          type: string
          minLength: 4
          maxLength: 4
          description: the sales org
        announcementId:
          type: string
          description: the eid of the announcement
        eventTimestamp:
          type: string
          format: date-time
          description: the date-time of the modification
        event:
          type: string
          description: |-
            Type of the modification.
            Possible values:
            * CREATE
            * UPDATE
            * DISMISSAL
        author:
          type: string
          description: the eid of the user that create/update the announcement
    HistoryPage-v1:
      title: historyPage-v1
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/History-v1'
        pagination:
          $ref: '#/components/schemas/Page-v1'
