openapi: 3.0.1
info:
  title: Entitlements API (Beta)
  description: API documentation for Entitlement service
  version: 1.0.0_Beta
servers:
  - url: https://flex1001-ci.flexnetoperations.com/entitlements-api
    description: Generated server url
tags:
  - name: MaintenanceLineItem
    description: API for performing operations on Maintenance Line Items.
  - name: Entitlement
    description: API for performing operations on Entitlements and Line Items.
  - name: LineItem
    description: API for performing operations on Line Items.
paths:
  /v1/entitlement:
    post:
      tags:
        - Entitlement
      summary: Create a simple Entitlement
      operationId: postEntitlement
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Entitlement'
        required: true
      responses:
        '201':
          description: Created a simple entitlement successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/entitlement/{entitlementId}/maintenance-line-items:
    post:
      tags:
        - MaintenanceLineItem
      summary: Create maintenance line items
      operationId: postMaintenanceLineItems
      parameters:
        - name: entitlementId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MaintenanceLineItemRequestDTO'
        required: true
      responses:
        '201':
          description: Created maintenance line items successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/entitlement/{entitlementId}/line-items:
    get:
      tags:
        - LineItem
      summary: Get line items for an entitlement
      operationId: getLineItems
      parameters:
        - name: entitlementId
          in: path
          required: true
          schema:
            type: string
        - name: activationId
          in: query
          description: Activation ID to filter line items
          required: false
          schema:
            type: string
        - name: productName
          in: query
          description: Product name to filter line items
          required: false
          schema:
            type: string
        - name: startDate
          in: query
          description: Start date to filter line items
          required: false
          schema:
            type: string
        - name: licenseModelName
          in: query
          description: License Model Name to filter line items
          required: false
          schema:
            type: string
        - name: status
          in: query
          description: Status to filter line items
          required: false
          schema:
            type: string
        - name: page
          in: query
          description: Requested page number
          required: false
          schema:
            type: integer
            format: int32
        - name: limit
          in: query
          description: Number of records per page
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Get all line items for an entitlement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
    post:
      tags:
        - LineItem
      summary: Create a line item
      operationId: postLineItems
      parameters:
        - name: entitlementId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LineItemRequestDTO'
        required: true
      responses:
        '201':
          description: Created line items successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/entitlement/{entitlementId}/line-items/{activationId}/policies:
    patch:
      tags:
        - LineItem
      summary: Configure line item policies
      operationId: configureLineItemPolicies
      parameters:
        - name: entitlementId
          in: path
          required: true
          schema:
            type: string
        - name: activationId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Policy'
        required: true
      responses:
        '200':
          description: LineItem Policies configured successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/entitlement/{entitlementId}/additional-properties:
    patch:
      tags:
        - LineItem
      summary: Update attributes of line items for an entitlement
      operationId: updateEntitlementLineItemsProperties
      parameters:
        - name: entitlementId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LineItems'
        required: true
      responses:
        '200':
          description: Line Items updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdditionalPropertiesResponse'
        '400':
          description: Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/entitlements:
    get:
      tags:
        - Entitlement
      summary: Get a list of simple entitlements.
      operationId: getEntitlements
      parameters:
        - name: activationId
          in: query
          description: Activation ID associated with the entitlement
          required: false
          schema:
            type: string
        - name: accountId
          in: query
          description: Account ID associated with the entitlement
          required: false
          schema:
            type: string
        - name: accountName
          in: query
          description: Account name associated with the entitlement
          required: false
          schema:
            type: string
        - name: contactEmail
          in: query
          description: Contact email associated with the entitlement
          required: false
          schema:
            type: string
        - name: product
          in: query
          description: Product name associated with the entitlement
          required: false
          schema:
            type: string
        - name: version
          in: query
          description: Product version associated with the entitlement
          required: false
          schema:
            type: string
        - name: partNumber
          in: query
          description: Part number associated with the entitlement
          required: false
          schema:
            type: string
        - name: status
          in: query
          description: Status of the entitlement (draft,deployed,active,inactive,obsoleted)
          required: false
          schema:
            type: string
        - name: sort_by
          in: query
          description: Field to sort by (entitlement_id,created_on)
          required: false
          schema:
            type: string
        - name: sort_order
          in: query
          description: Order to sort by (asc/desc)
          required: false
          schema:
            type: string
        - name: page
          in: query
          description: Requested page number
          required: false
          schema:
            type: integer
            format: int32
        - name: limit
          in: query
          description: Number of records per page
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Get simple entitlement list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Invalid data provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
components:
  schemas:
    Account:
      required:
        - accountId
        - accountType
        - partnerTierName
      type: object
      properties:
        accountId:
          type: string
          description: ID of the account
          example: SampleOrg12345
        accountName:
          type: string
        accountType:
          type: string
          description: >-
            Type of the account. Valid types are PUBLISHER, CUSTOMER,
            CHANNEL_PARTNER, SELF_REGISTERED, UNKNOWN
          example: CUSTOMER
        partnerTierName:
          type: string
          description: >-
            Partner tier of the account owning the entitlement. Valid values are
            END_CUSTOMER and PARTNER_TIER_ONE
          example: END_CUSTOMER/PARTNER_TIER_ONE
        isCurrentOwner:
          type: boolean
          description: >-
            Whether this account is the current owner of the entitlement in the
            distribution chain
        contactEmail:
          type: string
          description: Email address of the Contact in the account
          example: Joe@example.com
      description: Account related to an entitlement
    Attribute:
      type: object
      properties:
        name:
          type: string
          description: Name of the custom attribute
          example: REGION
        value:
          type: object
          description: >-
            Value assigned to the custom attribute. If the value is of type
            Date, then it should use yyyy/MM/dd format. Similarly, appropriate
            value corresponding to the type of custom attribute must be
            provided.
          example: EMEA
      description: >-
        Represents entitlement custom attributes. Mandatory custom attributes
        must be provided for the request to be successful.
    Entitlement:
      required:
        - lineItems
      type: object
      properties:
        entitlementId:
          maxLength: 255
          minLength: 0
          pattern: ^(?!\s*$)(?!.*['"&%^()#@!~/<>`{}=|]).*$
          type: string
          description: >-
            Entitlement ID of the entitlement. If you specify the entitlement
            ID, then it must be unique across all entitlements and line items.
            If you specify the entitlement ID here, then the autoGenerate flag
            must be set to false
          example: ent-id-1234
        description:
          maxLength: 2000
          minLength: 0
          type: string
          description: Description of the entitlement
          example: Description for entitlement
        allowPortalLogin:
          type: boolean
          description: >-
            Whether the customer can use the entitlement ID to log into the
            End-User Portal after the entitlement is deployed
        shipToEmail:
          maxLength: 1000
          minLength: 0
          type: string
          description: Email address of the ship-to contact
          example: Joe@example.com
        shipToAddress:
          maxLength: 1000
          minLength: 0
          pattern: ^$|^[ a-zA-Z0-9_-]+$
          type: string
          description: Address of the ship-to contact
          example: Building-Street-City
        accounts:
          maxItems: 2147483647
          minItems: 0
          type: array
          description: >-
            List of accounts associated with the entitlement. If account is not
            provided, the entitlement will be associated with
            UNKNOWN_ORG_UNIT(default account).
          items:
            $ref: '#/components/schemas/Account'
        lineItems:
          maxItems: 2147483647
          minItems: 1
          type: array
          description: List of line items contained in the entitlement
          items:
            $ref: '#/components/schemas/LineItem'
        autoDeploy:
          type: boolean
          description: Flag to indicate if the entitlement should be auto-deployed
        emailTemplateVariation:
          pattern: ^(?!\s+$).*
          type: string
          description: Name of the email template to be used for entitlement related emails
          example: DEFAULT
        attributes:
          type: array
          description: >-
            List of entitlement custom attributes. Note that mandatory custom
            attributes must be included in this list
          items:
            $ref: '#/components/schemas/Attribute'
        autoGenerate:
          type: boolean
          description: Whether the entitlement ID is to be auto-generated.
          example: false
        status:
          type: string
          enum:
            - draft
            - deployed
            - obsolete
    LicenseModel:
      required:
        - licenseModelName
      type: object
      properties:
        licenseModelName:
          type: string
          description: specify a name that uniquely identifies this license model
          example: LicenseModelName
        issuer:
          type: string
          description: specify who is issuing the license
          example: SampleLicenseIssuer
        serialNumber:
          type: string
          description: specify the serial number of the license
          example: SampleSerialno
        vendorString:
          type: string
          description: Unique value assigned by each publisher to each license
          example: uniqueVendorString
        notice:
          type: string
          description: >-
            This field is usually set at entitlement time and includes customer
            name and purchase order
          example: Premium Feature A
      description: License model associated with the product
    LineItem:
      required:
        - product
        - startDate
      type: object
      properties:
        activationId:
          maxLength: 255
          minLength: 0
          pattern: ^(?!\s*$)(?!.*['"&%^()#@!~/<>`{}=|]).*$
          type: string
          description: >-
            Activation ID of the line item. If you specify the activation ID,
            then it must be unique across all entitlements and line items. If
            you specify the activation ID here, then the autoGenerate flag must
            be set to false
          example: act-id-1234
        product:
          type: array
          description: List of products entitled by this line item
          items:
            $ref: '#/components/schemas/Product'
        quantity:
          minimum: 0
          type: integer
          description: Number of copies for the entitlement
          format: int32
          example: 1
        quantityPerCopy:
          minimum: 1
          type: integer
          format: int32
        isActivatable:
          type: boolean
          description: Whether this line item is activatable
        isPermanent:
          type: boolean
          description: >-
            Whether this line item is permanent. A permanent line item has no
            expiration date.
        expiryDate:
          type: string
          description: End date of the line item in YYYY-MM-DD format
          example: '2025-01-01'
        startDate:
          pattern: ^\d{4}-\d{2}-\d{2}$
          type: string
          description: Start date of the line item in YYYY-MM-DD format
          example: '2025-01-01'
        attributes:
          type: array
          description: List of custom attributes related to the line item
          items:
            $ref: '#/components/schemas/Attribute'
        autoGenerate:
          type: boolean
          description: Whether the activation ID should be auto-generated
          example: false
        autoDeploy:
          type: boolean
          description: Whether the Line item should be auto-deployed
        orderType:
          type: string
          description: Type of order for the line item. The default is NEW_ORDER
          example: NEW_ORDER
          enum:
            - new_order
            - renewal_order
            - upgrade_order
            - upsell_order
            - invalid_order
        lineItemStatus:
          type: string
          enum:
            - draft
            - deployed
            - obsolete
      description: Represents a Line Item
    Product:
      required:
        - productName
        - productVersion
      type: object
      properties:
        productName:
          type: string
          description: Name of the product
          example: SampleProduct
        productVersion:
          type: string
          description: Version of the product
          example: SampleVersion-1.0
        licenseModel:
          $ref: '#/components/schemas/LicenseModel'
      description: Product entitled by the line item
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
    Response:
      type: object
      properties:
        status:
          type: string
    MaintenanceLineItem:
      required:
        - maintenanceProduct
        - startDate
      type: object
      properties:
        activationId:
          maxLength: 255
          minLength: 0
          pattern: ^(?!\s*$)(?!.*['"&%^()#@!~/<>`{}=|]).*$
          type: string
          description: >-
            Activation ID of the maintenance line item. If you specify the
            activation ID, then it must be unique across all entitlements and
            maintenance line items. If you specify the activation ID here, then
            the autoGenerate flag must be set to false
          example: act-id-1234
        maintenanceProduct:
          $ref: '#/components/schemas/MaintenanceProduct'
        isPermanent:
          type: boolean
          description: >-
            Whether this maintenance line item is permanent. A permanent
            maintenance line item has no expiration date.
        expiryDate:
          pattern: ^\d{4}-\d{2}-\d{2}$
          type: string
          description: End date of the maintenance line item in YYYY-MM-DD format
          example: '2025-01-01'
        startDate:
          pattern: ^\d{4}-\d{2}-\d{2}$
          type: string
          description: Start date of the maintenance line item in YYYY-MM-DD format
          example: '2025-01-01'
        attributes:
          type: array
          description: List of custom attributes related to the maintenance line item
          items:
            $ref: '#/components/schemas/Attribute'
        autoGenerate:
          type: boolean
          description: Whether the activation ID should be auto-generated
        autoDeploy:
          type: boolean
          description: Whether the maintenance Line item should be auto-deployed
      description: Represents a Maintenance Line Item
    MaintenanceLineItemRequestDTO:
      required:
        - maintenanceLineItems
      type: object
      properties:
        maintenanceLineItems:
          type: array
          items:
            $ref: '#/components/schemas/MaintenanceLineItem'
    MaintenanceProduct:
      required:
        - maintenanceProductName
        - maintenanceProductVersion
      type: object
      properties:
        maintenanceProductName:
          type: string
          description: Name of the maintenance product
        maintenanceProductVersion:
          type: string
          description: Version of the maintenance product
        partNumber:
          type: string
          description: Part number associated with maintenance product
      description: Maintenance Product entitled by the maintenance line item
    LineItemRequestDTO:
      required:
        - lineItems
      type: object
      properties:
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
    Policy:
      type: object
      properties:
        rehosts:
          $ref: '#/components/schemas/PolicyAttribute'
        returns:
          $ref: '#/components/schemas/PolicyAttribute'
        repairs:
          $ref: '#/components/schemas/PolicyAttribute'
        extraActivations:
          minimum: 0
          type: integer
          description: Number of extra activations
          format: int32
        cancelLicense:
          type: boolean
          description: Cancel license policy
        virtualLicense:
          type: boolean
          description: Virtual license policy
        acpiGenerationIdLicense:
          type: boolean
          description: ACPI Generation ID License Policy
      description: License Model Policy used in Line Item.
    PolicyAttribute:
      required:
        - policyTermUnit
      type: object
      properties:
        allowedCount:
          minimum: 0
          type: integer
          description: Allowed Policy Count for the given Line Item.
          format: int32
        policyTermDuration:
          minimum: 0
          type: integer
          description: License Model Policy term duration used is given Line Item.
          format: int32
        policyTermUnit:
          pattern: ^(Days|Weeks|Months|Years)$
          type: string
          description: >-
            License Model Policy term unit used is given Line Item. Valid types
            are Days, Weeks, Months, Years
      description: Represents License Model Policy Attributes used in Line Item.
    Attributes:
      type: object
      properties:
        name:
          type: string
          description: Name of the custom attribute
        value:
          type: object
          description: >-
            Value assigned to the custom attribute. If the value is of type
            Date, then it should use yyyy/MM/dd format. Similarly, appropriate
            value corresponding to the type of custom attribute must be
            provided.
        type:
          type: string
          description: >-
            Type of the custom attribute. It can be of LINE_ITEM or
            LICENSE_MODEL
          enum:
            - line_item
            - license_model
      description: >-
        Represents line item and license model custom attributes. Mandatory
        custom attributes must be provided for the request to be successful.
    LineItems:
      type: object
      properties:
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/UpdateLineItemAttributesDTO'
      description: Represents List of line items to be updated
    UpdateLineItemAttributesDTO:
      required:
        - activationId
      type: object
      properties:
        activationId:
          maxLength: 255
          minLength: 0
          pattern: ^(?!\s*$)(?!.*['"&%^()#@!~/<>`{}=|]).*$
          type: string
          description: >-
            Activation ID of the line item for which attributes has to be
            updated.
        orderType:
          type: string
          description: >-
            Order type can have values like 'New_Order', 'Renewal_Order',
            'Upgrade_Order' and Upsell_OrderThis is used to identify the type of
            order for the line item.
          enum:
            - new_order
            - renewal_order
            - upgrade_order
            - upsell_order
            - invalid_order
        parentActivationId:
          maxLength: 255
          minLength: 0
          pattern: ^(?!\s*$)(?!.*['"&%^()#@!~/<>`{}=|]).*$
          type: string
          description: >-
            Activation ID  which will be updated as a parent line item if order
            type relation exists between line items. If order type is 'New' then
            this field will be ignored.
        deploy:
          type: boolean
          description: Whether this line item is to be deployed
        product:
          $ref: '#/components/schemas/product'
        attributes:
          type: array
          description: List of custom attributes related to the line item and license model
          items:
            $ref: '#/components/schemas/Attributes'
    licenseModel:
      type: object
      properties:
        name:
          type: string
        issuer:
          type: string
        serialNumber:
          type: string
        vendorString:
          type: string
        notice:
          type: string
        overdraft:
          type: integer
          format: int32
        maxBorrowInterval:
          type: string
        autoProvision:
          type: boolean
        gracePeriodDays:
          type: integer
          format: int32
      description: >-
        Represents name of license model and couple of system attributes , if
        any attributes are not associated to license model then that attribute
        will be ignored though value is provided in request
    product:
      type: object
      properties:
        productName:
          type: string
          description: Product Name related to the line item
        productVersion:
          type: string
          description: Product Version related to the line item
        partNumber:
          type: string
          description: Part Number related to Product
        licenseModel:
          $ref: '#/components/schemas/licenseModel'
      description: Represents product and license model details
    ActivationIds:
      type: object
      properties:
        activationId:
          type: string
    AdditionalPropertiesResponse:
      type: object
      properties:
        status:
          type: string
        activationIds:
          type: array
          items:
            $ref: '#/components/schemas/ActivationIds'
        response:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ResultItem'
    ResultItem:
      type: object
      properties:
        status:
          type: string
        activationId:
          type: string
        errorMsg:
          type: string
