openapi: 3.2.0
info:
  title: Blue Prism Calendars API
  description: An API to expose core functionality of the Blue Prism product.
  version: 7.5.1
security:
- Bearer:
  - bp-api
  - bpserver
- OAuth2:
  - bp-api
  - bpserver
tags:
- name: Calendars
paths:
  /api/v7/calendars:
    get:
      summary: Return a list of calendars
      description: '### Permissions required: `System - Calendar permission`'
      operationId: getCalendars
      tags:
      - Calendars
      parameters:
      - name: sortBy
        description: The field that results should be sorted by and the direction they should be sorted in.
        in: query
        schema:
          type: string
          enum:
          - IdAsc
          - IdDesc
          - NameAsc
          - NameDesc
          - RegionIdAsc
          - RegionIdDesc
      - name: id
        description: A filter to search for calendar id.
        in: query
        style: deepObject
        schema:
          $ref: '#/components/schemas/RangeOrEqualFilter'
        examples:
          equals:
            $ref: '#/components/examples/IntegerEqualsExample'
          range:
            $ref: '#/components/examples/IntegerRangeExample'
          less:
            $ref: '#/components/examples/IntegerLessThanExample'
      - name: name
        description: A filter to search for the name of the calendar.
        in: query
        style: deepObject
        schema:
          $ref: '#/components/schemas/BasicStringFilter'
        examples:
          equals:
            $ref: '#/components/examples/StringEqualsExample'
          startsWith:
            $ref: '#/components/examples/StringStartsWithExample'
          range:
            $ref: '#/components/examples/StringRangeExample'
          greater:
            $ref: '#/components/examples/StringGreaterThanExample'
      - name: region
        description: A filter to search for the region id.
        in: query
        style: deepObject
        schema:
          $ref: '#/components/schemas/RangeOrEqualFilter'
        examples:
          equals:
            $ref: '#/components/examples/IntegerEqualsExample'
          range:
            $ref: '#/components/examples/IntegerRangeExample'
          less:
            $ref: '#/components/examples/IntegerLessThanExample'
      - name: workingWeek
        in: query
        style: form
        explode: false
        description: The working week to search for.
        schema:
          type: array
          items:
            type: string
            enum:
            - Sunday
            - Monday
            - Tuesday
            - Wednesday
            - Thursday
            - Friday
            - Saturday
      responses:
        '200':
          description: A list calendars was successfully retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Calendar'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      summary: Creates a Calendar
      description: '> ### Permissions required: `System - Calendars`'
      tags:
      - Calendars
      requestBody:
        description: Details of the calendar to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCalendarModel'
      responses:
        '201':
          description: The calendar was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCalendarResponseModel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: postApiV7Calendars
      x-operation-id-source: derived
  /api/v7/calendars/{calendarId}:
    get:
      summary: Returns a calendar by Id
      description: '### Permissions required: `System - Calendar permission`'
      tags:
      - Calendars
      parameters:
      - name: calendarId
        in: path
        description: The ID of the calendar to get.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: A calendar was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calendar'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getApiV7CalendarsByCalendarId
      x-operation-id-source: derived
    delete:
      summary: Deletes a specified calendar
      description: '### Permissions required: `System - Calendar permission`'
      tags:
      - Calendars
      parameters:
      - name: calendarId
        in: path
        description: The ID of the calendar to delete.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '204':
          description: The calendar was successfully deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
      operationId: deleteApiV7CalendarsByCalendarId
      x-operation-id-source: derived
    patch:
      summary: Update a calendar by Id
      operationId: updateCalendar
      description: '> ### Permissions required: `System - Calendar permission`'
      tags:
      - Calendars
      parameters:
      - name: calendarId
        in: path
        required: true
        description: The ID of the Calendar to update.
        schema:
          type: integer
          format: int32
      requestBody:
        description: Details of the calendar to update.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchRequest'
            examples:
              add (to array):
                $ref: '#/components/examples/PatchAddToArrayExample'
              add (to object):
                $ref: '#/components/examples/PatchAddToObjectExample'
              copy:
                $ref: '#/components/examples/PatchCopyExample'
              move:
                $ref: '#/components/examples/PatchMoveExample'
              remove:
                $ref: '#/components/examples/PatchRemoveExample'
              replace:
                $ref: '#/components/examples/PatchReplaceExample'
      responses:
        '204':
          description: The calendar was successfully updated.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v7/calendars/{calendarId}/clones:
    post:
      summary: Clones a calendar by Id
      description: '### Permissions required: `System - Calendar permission`'
      tags:
      - Calendars
      parameters:
      - name: calendarId
        in: path
        description: The ID of the calendar to clone.
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        description: Details of the calendar to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloneCalendarModel'
      responses:
        '201':
          description: The calendar was successfully cloned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCalendarResponseModel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: postApiV7CalendarsByCalendarIdClones
      x-operation-id-source: derived
  /api/v7/calendars/{calendarId}/otherHolidays:
    get:
      summary: Returns calendar other holidays by calendar Id
      description: '### Permissions required: `System - Calendar permission`'
      tags:
      - Calendars
      parameters:
      - name: calendarId
        in: path
        description: The ID of the calendar used to get other holidays.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: The calendar other holidays were successfully retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              example:
              - '2021-01-04'
              - '2021-10-25'
              - '2022-03-05'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getApiV7CalendarsByCalendarIdOtherHolidays
      x-operation-id-source: derived
  /api/v7/calendars/{calendarId}/otherHolidays/batch:
    delete:
      summary: Deletes other holidays in calendar
      description: '### Permissions required: `System - Calendar permission`'
      tags:
      - Calendars
      parameters:
      - name: calendarId
        in: path
        description: The ID of the calendar used to remove other holidays.
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        description: The list of other holidays to delete.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OtherHolydaysModel'
      responses:
        '204':
          description: Other holidays were successfully deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: deleteApiV7CalendarsByCalendarIdOtherHolidaysBatch
      x-operation-id-source: derived
    post:
      summary: Creates other holidays in calendar
      description: '### Permissions required: `System - Calendar permission`'
      tags:
      - Calendars
      parameters:
      - name: calendarId
        in: path
        description: The ID of the calendar used to add other holidays.
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        description: The list of other holidays to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OtherHolydaysModel'
      responses:
        '204':
          description: Other holidays were successfully created.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: postApiV7CalendarsByCalendarIdOtherHolidaysBatch
      x-operation-id-source: derived
  /api/v7/calendars/{calendarId}/references:
    get:
      summary: Returns a list of process that reference a given calendar
      description: ''
      tags:
      - Calendars
      parameters:
      - name: calendarId
        in: path
        description: The ID of the calendar to find references for.
        required: true
        schema:
          type: integer
          format: int32
      - name: sortBy
        description: The field that results should be sorted by and the direction they should be sorted in.
        in: query
        schema:
          type: string
          enum:
          - NameAsc
          - NameDesc
          - DescriptionAsc
          - DescriptionDesc
          - ProcessTypeAsc
          - ProcessTypeDesc
      - name: itemsPerPage
        description: The maximum number of items to retrieve.
        in: query
        schema:
          type: integer
          minimum: 1
      - name: pagingToken
        description: The token to point to the last item previously returned.
        in: query
        schema:
          type: string
      - name: name
        description: A filter to search for the name of the reference.
        in: query
        style: deepObject
        schema:
          $ref: '#/components/schemas/BasicStringFilter'
        examples:
          equals:
            $ref: '#/components/examples/StringEqualsExample'
          startsWith:
            $ref: '#/components/examples/StringStartsWithExample'
          range:
            $ref: '#/components/examples/StringRangeExample'
          greater:
            $ref: '#/components/examples/StringGreaterThanExample'
      - name: description
        in: query
        style: deepObject
        description: A filter to search for the description of the reference.
        schema:
          $ref: '#/components/schemas/BasicStringFilter'
        examples:
          equals:
            $ref: '#/components/examples/StringEqualsExample'
          startsWith:
            $ref: '#/components/examples/StringStartsWithExample'
          range:
            $ref: '#/components/examples/StringRangeExample'
          greater:
            $ref: '#/components/examples/StringGreaterThanExample'
      - name: processType
        in: query
        style: form
        explode: false
        description: The type of the process to search for.
        schema:
          type: array
          items:
            type: string
            enum:
            - Process
            - Object
      responses:
        '200':
          description: A list of Calendar references were succesfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferencesItemsPage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getApiV7CalendarsByCalendarIdReferences
      x-operation-id-source: derived
  /api/v7/holidayRegions:
    get:
      summary: Return a list of holiday regions
      description: '### Permissions required: `System - Calendars permission`'
      operationId: getHolidayRegions
      tags:
      - Calendars
      responses:
        '200':
          description: A list of holiday regions was successfully retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HolidayRegion'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v7/holidayRegions/{holidayRegionId}/publicHolidays:
    get:
      summary: Return a list of holiday by region id
      description: '### Permissions required: `System - Calendars permission`'
      operationId: getHolidayByRegionId
      tags:
      - Calendars
      parameters:
      - name: holidayRegionId
        in: path
        description: The ID of the holiday region.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: A list of holiday by region id was successfully retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HolidayByRegionId'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  examples:
    StringEqualsExample:
      value:
        eq: Example
      summary: Search for a value equal to "Example".
    IntegerEqualsExample:
      value:
        eq: 123
      summary: Search for a value equal to 123.
    PatchReplaceExample:
      summary: Replace the value in a property.
      value:
      - op: replace
        path: /property
        value: propertyValue
    PatchCopyExample:
      summary: Copy a value from one property to another.
      value:
      - op: copy
        from: /sourceProperty
        path: /destinationProperty
    StringStartsWithExample:
      value:
        strtw: Exa
      summary: Search a value starting with "Exa".
    IntegerRangeExample:
      value:
        gte: 123
        lte: 321
      summary: Search for a value between 123 and 321 inclusive.
    IntegerLessThanExample:
      value:
        lte: 123
      summary: Search for a value less than or equal to 123.
    PatchAddToObjectExample:
      summary: Add new property values to an object.
      value:
      - op: add
        path: /property
        value: propertyValue
    StringGreaterThanExample:
      value:
        gte: Example
      summary: Search for a value alphanumerically after or equal to "Example".
    StringRangeExample:
      value:
        gte: Ex
        lte: F
      summary: Search for a value alphanumerically between "Ex" and "F".
    PatchAddToArrayExample:
      summary: Add values to a collection.
      value:
      - op: add
        path: /someArrayProperty
        value:
        - item1
        - item2
    PatchRemoveExample:
      summary: Remove a property value.
      value:
      - op: remove
        path: /propertyToDeleteValueFrom
    PatchMoveExample:
      summary: Move a value from one property to another.
      value:
      - op: move
        from: /sourceProperty
        path: /destinationProperty
  schemas:
    EqualsFilter:
      description: Used to filter values. Check for values that are equal to the given value.
      type: object
      properties:
        eq:
          type:
          - object
          - 'null'
          description: The value that the field should be equal to.
      example:
        eq: null
    GreaterThanOrEqualToFilter:
      description: Used to filter values. Check for values that are greater than or equal to the given value.
      type: object
      properties:
        gte:
          type:
          - object
          - 'null'
          description: The value that the field should be greater than or equal to.
      example:
        gte: null
    CloneCalendarModel:
      description: Contains details for cloning a calendar with a new name.
      type: object
      properties:
        name:
          type: string
          description: The name of the calendar to create.
          minLength: 1
          maxLength: 128
    BasicStringFilter:
      description: Used to filter strings. Check for strings that start with, equal, are greater than, are less than, or are between the given value(s).
      type: object
      anyOf:
      - $ref: '#/components/schemas/RangeOrEqualFilter'
      - $ref: '#/components/schemas/StartsWithStringFilter'
      example:
        strtw: null
        gte: null
        lte: null
        eq: null
    StartsWithStringFilter:
      description: Used to filter strings. Check for strings that start with the given value.
      type: object
      properties:
        strtw:
          type:
          - string
          - 'null'
          description: The value that the field should start with.
      example:
        strtw: null
    HolidayByRegionId:
      description: A model of holiday by region id.
      type: object
      properties:
        publicHolidayId:
          type: integer
          description: The ID of the holiday by region id.
        name:
          type: string
          description: The name of the public holiday.
        nextDate:
          type: string
          description: The next date of the public holiday.
      example:
        publicHolidayId: 33
        name: Coming of Age Day
        nextDate: 10/01/2023
    ReferencesItemsPage:
      description: Contains references of a specified object.
      type: object
      properties:
        pagingToken:
          $ref: '#/components/schemas/PagingToken'
        items:
          type: array
          description: A collection of references.
          items:
            $ref: '#/components/schemas/Reference'
    CreateCalendarModel:
      description: Contains details for creating a new calendar.
      type: object
      properties:
        name:
          type: string
          description: The name of the calendar to create.
          minLength: 1
          maxLength: 128
        workingWeek:
          type: array
          description: An array of working week. Each day can be added only 1 time.
          items:
            type: string
            enum:
            - Sunday
            - Monday
            - Tuesday
            - Wednesday
            - Thursday
            - Friday
            - Saturday
        region:
          type:
          - object
          - 'null'
          description: A region of the calendar.
          properties:
            regionId:
              type: integer
              description: The Id of the region.
            disabledPublicHolidaysIds:
              type: array
              description: An array of disabled public holidays Ids. Each holidays can be added only 1 time.
              items:
                type: integer
    RangeFilter:
      description: Used to filter values. Check for values that are greater than or equal to, less than or equal to, or between the given value(s).
      type: object
      anyOf:
      - $ref: '#/components/schemas/GreaterThanOrEqualToFilter'
      - $ref: '#/components/schemas/LessThanOrEqualToFilter'
      example:
        gte: null
        lte: null
    Region:
      description: A model of region.
      type: object
      properties:
        regionId:
          type: integer
          description: The ID of the region.
        disabledPublicHolidaysIds:
          type: array
          description: An array of IDs of the disabled public holidays.
          items:
            type: integer
            description: The ID of disabled public holidays.
      example:
        regionId: 1
        disabledPublicHolidaysIds:
        - 1
        - 2
    RangeOrEqualFilter:
      description: Used to filter values. Check for values that are equal to, greater than or equal to, less than or equal to, or between the given value(s).
      type: object
      oneOf:
      - $ref: '#/components/schemas/RangeFilter'
      - $ref: '#/components/schemas/EqualsFilter'
      example:
        gte: null
        lte: null
        eq: null
    UrlParameterError:
      description: An error occurred due to incorrect data supplied to url parameter.
      type: object
      properties:
        message:
          type: string
          description: A message about the error.
        messageDetail:
          type: string
          description: A detailed description about the error.
    LessThanOrEqualToFilter:
      description: Used to filter values. Check for values that are less than or equal to the given value.
      type: object
      properties:
        lte:
          type:
          - object
          - 'null'
          description: The value that the field should be less than or equal to.
      example:
        lte: null
    HolidayRegion:
      description: A model of holiday region.
      type: object
      properties:
        id:
          type: integer
          description: The ID of the holiday region.
        name:
          type: string
          description: The name of the region.
      example:
        id: 1
        name: England and Wales
    ValidationError:
      description: An error occurred during validation. See the response body for details on the invalid field.
      type: object
      properties:
        invalidField:
          type: string
          description: The field which is invalid.
        message:
          type: string
          description: A description of the error found with the field.
    PatchRequest:
      description: A request containing a JSON Patch document. See PatchDocument for details.
      type: array
      items:
        $ref: '#/components/schemas/PatchDocument'
    ErrorMessage:
      description: A message describing the problem encountered.
      type: string
    PatchDocument:
      description: A JSONPatch document as defined by RFC 6902. See http://jsonpatch.com/
      required:
      - op
      - path
      properties:
        op:
          type: string
          description: The operation to be performed.
          enum:
          - add
          - remove
          - replace
          - move
          - copy
        path:
          type: string
          description: A JSON-Pointer.
        value:
          type: object
          description: The value to be used within the operations..
        from:
          type: string
          description: A string containing a JSON Pointer value.
    Reference:
      description: Contains details of referenced item.
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The ID of the process/object.
        name:
          type: string
          description: The name of the process/object.
          minLength: 1
        description:
          type: string
          description: The description of process/object.
        type:
          type: string
          enum:
          - Process
          - Object
          - Unset
          description: The type of process/object
    Calendar:
      description: A model of calendar.
      type: object
      properties:
        id:
          type: integer
          description: The ID of the calendar.
        name:
          type: string
          description: The name of the calendar.
        workingWeek:
          type: array
          description: An array of days in the working work.
          items:
            type: string
        region:
          $ref: '#/components/schemas/Region'
      example:
        id: 1
        name: Working Week / No Holidays
        workingWeek:
        - Monday
        - Tuesday
        region:
          regionId: 1
          disabledPublicHolidaysIds:
          - 1
          - 2
    PagingToken:
      type: string
      description: The token to be used in the next request to return the next collection of items.
      example: U3VwZXIgc2VjcmV0IGRhdGEuIFNoaGho
    OtherHolydaysModel:
      description: Contains details for other holidays.
      type: object
      properties:
        holidays:
          type: array
          description: An array of other holidays.
          items:
            type: string
            format: date
    CreateCalendarResponseModel:
      description: Contains the ID of a calendar.
      type: object
      properties:
        id:
          type: integer
          description: The ID of the calendar.
  responses:
    BadRequest:
      description: The request is malformed or contains incorrect information. See the response for more details.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/UrlParameterError'
            - $ref: '#/components/schemas/ValidationError'
    NotAuthorized:
      description: The authentication token was either missing or invalid and must be refreshed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    NotFound:
      description: The requested resource could not be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    Forbidden:
      description: The authentication token does not give sufficient permissions to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    Conflict:
      description: The request conflicts with the current state of the resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: JWT token issued from Authentication Server.
      bearerFormat: JWT
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth-server/connect/token
          scopes:
            bp-api: API scope
            bpserver: Blue Prism Application scope