Charthop guideline API

openapi: 3.2.0
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access Guideline API
  contact:
    name: ChartHop
    url: https://www.charthop.com
    email: support@charthop.com
servers:
- url: https://localhost
- url: http://localhost
tags:
- name: guideline
paths:
  /v1/org/{orgId}/guideline:
    get:
      tags:
      - guideline
      summary: Get all guidelines for a given comp review
      operationId: findGuidelinesForCompReview
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: compReviewId
        in: query
        description: comp review id
        required: true
        schema:
          type: string
      - name: includeDeleted
        in: query
        description: include deleted guidelines
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsGuideline'
    post:
      tags:
      - guideline
      summary: Create a new guideline
      operationId: createGuideline
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Created
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGuideline'
        required: true
  /v1/org/{orgId}/guideline/{id}:
    get:
      tags:
      - guideline
      summary: Get a specific guideline
      operationId: findGuideline
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: ID of the desired guideline
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Guideline'
    patch:
      tags:
      - guideline
      summary: Update a guideline
      operationId: updateGuideline
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGuideline'
        required: true
    delete:
      tags:
      - guideline
      summary: Delete a guideline
      operationId: deleteGuideline
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
  /v1/org/{orgId}/guideline/{id}/calculate:
    get:
      tags:
      - guideline
      summary: Calculate the matrix values for a specific guideline (which may apply to multiple scenarios in the comp review)
      operationId: calculateGuideline
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: ID of the desired guideline
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsGuidelineCalculation'
components:
  schemas:
    Attribution:
      type: object
      properties:
        principalUserId:
          type: string
          example: 588f7ee98f138b19220041a7
        agentUserIds:
          type: array
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        eventId:
          type: string
          example: 588f7ee98f138b19220041a7
        aiChatId:
          type: string
          example: 588f7ee98f138b19220041a7
        aiToolUseId:
          type: string
        channel:
          type: string
          enum:
          - WEB
          - MOBILE
          - SLACK
          - TEAMS
          - MCP
    GuidelineCalculation:
      type: object
      required:
      - guidelineId
      - jobId
      - compReviewId
      - guidelineLabel
      - appliedField
      - flagMode
      - isDeviated
      - deviation
      - fields
      properties:
        guidelineId:
          type: string
          example: 588f7ee98f138b19220041a7
        jobId:
          type: string
          example: 588f7ee98f138b19220041a7
        compReviewId:
          type: string
          example: 588f7ee98f138b19220041a7
        budgetPoolId:
          type: string
          example: 588f7ee98f138b19220041a7
        guidelineLabel:
          type: string
        min:
          type: object
        max:
          type: object
        target:
          type: object
        appliedField:
          type: string
        flagMode:
          type: string
          enum:
          - DEVIATION_THRESHOLD
          - NONE
        flagDeviationThreshold:
          type: number
        isDeviated:
          type: boolean
        deviation:
          $ref: '#/components/schemas/Deviation'
        fields:
          type: object
          additionalProperties:
            type: object
    Money:
      type: object
      required:
      - amount
      - currency
      properties:
        amount:
          type: number
        currency:
          type: string
        places:
          type: integer
          format: int32
    ResultsAccess:
      type: object
      required:
      - allowed
      properties:
        ids:
          type: array
          uniqueItems: true
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        allowed:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/AccessAction'
    Deviation:
      type: object
      properties:
        min:
          type: object
        max:
          type: object
    BasisFieldMatrix:
      type: object
      required:
      - includedFields
      - conditions
      properties:
        includedFields:
          type: array
          items:
            type: string
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/BasisCondition'
    ResultsGuidelineCalculation:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GuidelineCalculation'
        next:
          type: string
        access:
          type: array
          items:
            $ref: '#/components/schemas/ResultsAccess'
    Guideline:
      type: object
      required:
      - id
      - orgId
      - compReviewId
      - label
      - appliedField
      - sourceField
      - calculationType
      - flagMode
      - enablePopulateValue
      - basisType
      properties:
        id:
          type: string
          description: globally unique id
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent organization id
          example: 588f7ee98f138b19220041a7
        compReviewId:
          type: string
          description: comp review id
          example: 588f7ee98f138b19220041a7
        label:
          type: string
          description: guideline name
          example: Merit Guideline
          minItems: 1
          maxItems: 80
        budgetPoolId:
          type: string
          description: the budget pool the guideline is allocated from
          example: 588f7ee98f138b19220041a7
        participantsExpr:
          type: string
          description: CQL filter to determine which employees the guideline applies to
          example: is:person and tenure>=12
        appliedField:
          type: string
          description: the field the guideline applies to
          example: '''base'' or ''grantShares'''
        sourceField:
          type: string
          description: the field the guideline is calculated from
          example: '''base'' or ''grantShares'''
        calculationType:
          type: string
          description: how does the guideline calculate the target value? e.g. is there a range (min/max) or only a target
          example: TARGET
          enum:
          - RANGE
          - TARGET
        flagMode:
          type: string
          description: how does the guideline indicate deviations from the target amount
          example: NONE
          enum:
          - DEVIATION_THRESHOLD
          - NONE
        flagDeviationThreshold:
          type: number
          description: the threshold (percent) against which deviations from the guideline are flagged
          example: '0.75'
        enablePopulateValue:
          type: boolean
          description: whether or not the target values from the guidelines are pre-populated in the given columns
          example: 'false'
        basisType:
          type: string
          description: how an individual guideline value itself is calculated, e.g. percentage of the appliedField, fixed amount, or custom CQL
          example: CUSTOM
          enum:
          - CUSTOM
          - FIXED
          - CUSTOM_FIXED
          - PERCENTAGE
          - CUSTOM_PERCENTAGE
        basisExpr:
          type: string
          description: if basisType.CUSTOM, the custom CQL expression used to generate the guideline value
          example: 'tenure>12 ? (base * 0.04) : (base * 0.02)'
        basisFieldMatrix:
          description: if the guideline is calculated based on given field(s)
          $ref: '#/components/schemas/BasisFieldMatrix'
        fixedAmountRange:
          description: the value range if basisType.FIXED, the appliedField is of type Money, and the guidelines are not dependent on given fields (no BasisFieldMatrix is present)
          $ref: '#/components/schemas/MoneyRange'
        fixedValueRange:
          description: the value range if basisType.FIXED, the appliedField is NOT of type Money, and the guidelines are not dependent on given fields (no BasisFieldMatrix is present)
          $ref: '#/components/schemas/ValueRange'
        createId:
          type: string
          description: created by user id
          example: 588f7ee98f138b19220041a7
        createBehalfId:
          type: string
          description: created on behalf of user id
          example: 588f7ee98f138b19220041a7
        createAttribution:
          $ref: '#/components/schemas/Attribution'
        createAt:
          type: string
          description: created timestamp
          example: '2017-01-24T13:57:52Z'
        updateId:
          type: string
          description: last updated by user id
          example: 588f7ee98f138b19220041a7
        updateBehalfId:
          type: string
          description: last updated on behalf of user id
          example: 588f7ee98f138b19220041a7
        updateAttribution:
          $ref: '#/components/schemas/Attribution'
        updateAt:
          type: string
          description: last updated timestamp
          example: '2017-01-24T13:57:52Z'
        deleteId:
          type: string
          description: deleted by user id
          example: 588f7ee98f138b19220041a7
        deleteBehalfId:
          type: string
          description: deleted on behalf of user id
          example: 588f7ee98f138b19220041a7
        deleteAttribution:
          $ref: '#/components/schemas/Attribution'
        deleteAt:
          type: string
          description: deleted timestamp
          example: '2017-01-24T13:57:52Z'
    UpdateGuideline:
      type: object
      properties:
        label:
          type: string
          description: guideline name
          example: Merit Guideline
          minItems: 1
          maxItems: 80
        budgetPoolId:
          type: string
          description: the budget pool the guideline is allocated from
          example: 588f7ee98f138b19220041a7
        participantsExpr:
          type: string
          description: CQL filter to determine which employees the guideline applies to
          example: is:person and tenure>=12
        appliedField:
          type: string
          description: the field the guideline applies to
          example: '''base'' or ''grantShares'''
        sourceField:
          type: string
          description: the field the guideline is calculated from
          example: '''base'' or ''grantShares'''
        calculationType:
          type: string
          description: how does the guideline calculate the target value? e.g. is there a range (min/max) or only a target
          example: TARGET
          enum:
          - RANGE
          - TARGET
        flagMode:
          type: string
          description: how does the guideline indicate deviations from the target amount
          example: NONE
          enum:
          - DEVIATION_THRESHOLD
          - NONE
        flagDeviationThreshold:
          type: number
          description: the threshold (percent) against which deviations from the guideline are flagged
          example: '0.75'
        enablePopulateValue:
          type: boolean
          description: whether or not the target values from the guidelines are pre-populated in the given columns
          example: 'false'
        basisType:
          type: string
          description: how an individual guideline value itself is calculated, e.g. percentage of the appliedField, fixed amount, or custom CQL
          example: CUSTOM
          enum:
          - CUSTOM
          - FIXED
          - CUSTOM_FIXED
          - PERCENTAGE
          - CUSTOM_PERCENTAGE
        basisExpr:
          type: string
          description: if basisType.CUSTOM, the custom CQL expression used to generate the guideline value
          example: 'tenure>12 ? (base * 0.04) : (base * 0.02)'
        basisFieldMatrix:
          description: if the guideline is calculated based on given field(s)
          $ref: '#/components/schemas/BasisFieldMatrix'
        fixedAmountRange:
          description: the value range if basisType.FIXED, the appliedField is of type Money, and the guidelines are not dependent on given fields (no BasisFieldMatrix is present)
          $ref: '#/components/schemas/MoneyRange'
        fixedValueRange:
          description: the value range if basisType.FIXED, the appliedField is NOT of type Money, and the guidelines are not dependent on given fields (no BasisFieldMatrix is present)
          $ref: '#/components/schemas/ValueRange'
    ResultsGuideline:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Guideline'
        next:
          type: string
        access:
          type: array
          items:
            $ref: '#/components/schemas/ResultsAccess'
    MoneyRange:
      type: object
      properties:
        max:
          description: the maximum value in the range (type = Money)
          $ref: '#/components/schemas/Money'
        min:
          description: the minimum value in the range (type = Money)
          $ref: '#/components/schemas/Money'
        target:
          description: the target value for the range (type = Money)
          $ref: '#/components/schemas/Money'
    ValueRange:
      type: object
      properties:
        max:
          type: number
          description: the maximum value in the range (type = BigDecimal)
        min:
          type: number
          description: the minimum value in the range (type = BigDecimal)
        target:
          type: number
          description: the target value for the range (type = BigDecimal)
    BasisCondition:
      type: object
      required:
      - conditionExpr
      properties:
        conditionExpr:
          type: string
        amountRange:
          $ref: '#/components/schemas/MoneyRange'
        valueRange:
          $ref: '#/components/schemas/ValueRange'
    AccessAction:
      type: object
      required:
      - action
      properties:
        action:
          type: string
        fields:
          type: array
          uniqueItems: true
          items:
            type: string
        types:
          type: array
          uniqueItems: true
          items:
            type: string
    CreateGuideline:
      type: object
      required:
      - compReviewId
      - label
      - appliedField
      - sourceField
      - calculationType
      - flagMode
      - enablePopulateValue
      - basisType
      properties:
        compReviewId:
          type: string
          description: comp review id
          example: 588f7ee98f138b19220041a7
        label:
          type: string
          description: guideline name
          example: Merit Guideline
          minItems: 1
          maxItems: 80
        budgetPoolId:
          type: string
          description: the budget pool the guideline is allocated from
          example: 588f7ee98f138b19220041a7
        participantsExpr:
          type: string
          description: CQL filter to determine which employees the guideline applies to
          example: is:person and tenure>=12
        appliedField:
          type: string
          description: the field the guideline applies to
          example: '''base'' or ''grantShares'''
        sourceField:
          type: string
          description: the field the guideline is calculated from
          example: '''base'' or ''grantShares'''
        calculationType:
          type: string
          description: how does the guideline calculate the target value? e.g. is there a range (min/max) or only a target
          example: TARGET
          enum:
          - RANGE
          - TARGET
        flagMode:
          type: string
          description: how does the guideline indicate deviations from the target amount
          example: NONE
          enum:
          - DEVIATION_THRESHOLD
          - NONE
        flagDeviationThreshold:
          type: number
          description: the threshold (percent) against which deviations from the guideline are flagged
          example: '0.75'
        enablePopulateValue:
          type: boolean
          description: whether or not the target values from the guidelines are pre-populated in the given columns
          example: 'false'
        basisType:
          type: string
          description: how an individual guideline value itself is calculated, e.g. percentage of the appliedField, fixed amount, or custom CQL
          example: CUSTOM
          enum:
          - CUSTOM
          - FIXED
          - CUSTOM_FIXED
          - PERCENTAGE
          - CUSTOM_PERCENTAGE
        basisExpr:
          type: string
          description: if basisType.CUSTOM, the custom CQL expression used to generate the guideline value
          example: 'tenure>12 ? (base * 0.04) : (base * 0.02)'
        basisFieldMatrix:
          description: if the guideline is calculated based on given field(s)
          $ref: '#/components/schemas/BasisFieldMatrix'
        fixedAmountRange:
          description: the value range if basisType.FIXED, the appliedField is of type Money, and the guidelines are not dependent on given fields (no BasisFieldMatrix is present)
          $ref: '#/components/schemas/MoneyRange'
        fixedValueRange:
          description: the value range if basisType.FIXED, the appliedField is NOT of type Money, and the guidelines are not dependent on given fields (no BasisFieldMatrix is present)
          $ref: '#/components/schemas/ValueRange'