openapi: 3.0.0
info:
  title: Reports
  description: 'Reports API documentation'
  version: 1.0.0
servers:
  - url: 'https://id360.manageengine.com/api/v1'
    description: 'API Endpoint'
tags:
  - name: report
    description: 'Reports endpoint'
paths:
  /reports/{id}:
    get:
      tags:
        - report
      summary: 'Get Report Details'
      description: 'Used to get the previously saved report input data, view columns, and criteria for a specific report.'
      parameters:
        - name: id
          in: path
          required: true
          description: 'The ID of the report to fetch details for'
          example: 2000000000001
          schema:
            type: integer
        - $ref: '#/components/parameters/acceptHeader'
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/reports'
        '400':
          description: 'Bad Request'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/invalidParam'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - X-ZCSRF-TOKEN: [ ]
    patch:
      summary: Update report details
      description: To update criteria, view columns and inputs for a report
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: The ID of the report to generate.
          example: "12345" # Example based on context of id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/reports'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/acceptJobResponse'
                  links:
                    $ref: '#/components/schemas/links'

  /reports/{id}/data:
    get:
      summary: Retrieve Report Data
      description: Retrieves data for a specific report, allowing for sorting, filtering, pagination, and view selection.
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: The ID of the report to retrieve data for.
          example: "12345" # Example based on context of id
        - in: query
          name: sort
          schema:
            type: string
          description: Sort order for the results. Prepend with '-' for descending order.
          example: "-APFDiscADUserDetails_SAM_ACCOUNT_NAME"
        - in: query
          name: filter
          schema:
            type: string
          description: Filter criteria for the results.
          example: "APFDiscADUserDetails_SAM_ACCOUNT_NAME co \"John@admp.com\" and APFDiscADUserDetails_DISPLAY_NAME co \"John\""
        - in: query
          name: from
          schema:
            type: integer
            format: int32
          description: The starting index of the results to return.
          example: 0
        - in: query
          name: limit
          schema:
            type: integer
            format: int32
          description: The maximum number of results to return.
          example: 25
        - in: query
          name: view
          schema:
            type: string
          description: The view type for the report data.
          example: "default"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true # Allows for flexible keys like mail
                  meta:
                    type: object
                    properties:
                      start_index:
                        type: integer
                      limit:
                        type: integer
                      total_no_of_objects:
                        type: integer
                example:
                  data:
                    - mail: "#$&!#@erpdev19.com"
                      sAMAccountName: "#$&!#-11789910591"
                      memberOfLocation: "NestedGroup[distgrps]"
                      memberOf: "NestedGroup"
                      name: "#$&!#"
                      distinguishedName: "CN=\\#$&!\\#,CN=Users,DC=erpdev19,DC=com"
                      createdOn: "2023/04/05 08:23:02"
                    - mail: "ChildOuUser1@erpdev19.com"
                      sAMAccountName: "ChildOuUser1"
                      memberOfLocation: "Domain Users[Users]; Group_4f608f75-fd79-4962-b9ef-5057b4ffd535[distgrps]; mytestgroup[Users]; NestedGroup[distgrps]"
                      memberOf: "Domain Users; Group_4f608f75-fd79-4962-b9ef-5057b4ffd535; mytestgroup; NestedGroup"
                      name: "ChildOuUser1"
                      distinguishedName: "CN=ChildOuUser1,OU=ChildOU,OU=ParentOU,DC=erpdev19,DC=com"
                      createdOn: "2024/09/03 17:56:24"
                    - mail: "conference@erpdev19.com"
                      sAMAccountName: "conference"
                      memberOfLocation: "Domain Users[Users]; mytestgroup[Users]; NestedGroup[distgrps]"
                      memberOf: "Domain Users; mytestgroup; NestedGroup"
                      name: "Conference"
                      distinguishedName: "CN=Conference,CN=Users,DC=erpdev19,DC=com"
                      createdOn: "2023/08/03 04:08:20"
                    - mail: "Create@erpdev19.com"
                      sAMAccountName: "Create"
                      memberOfLocation: "Domain Users[Users]; NestedGroup[distgrps]"
                      memberOf: "Domain Users; NestedGroup"
                      name: "Create"
                      distinguishedName: "CN=Create,CN=Users,DC=erpdev19,DC=com"
                      createdOn: "2023/03/30 05:38:36"
                    - mail: "dev@erpdev19.com"
                      sAMAccountName: "dev"
                      memberOfLocation: "Ad created secuirty grp[distgrps]; Administrators[Builtin]; Compliance Management[Microsoft Exchange Security Groups]; dg10[distgrps]; DG_1[DG]; DG_10[DG]; DG_100[DG]; DG_1000[DG]; DG_101[DG]; DG_102[DG]; DG_103[DG]; DG_104[DG]; DG_105[DG]; DG_106[DG]; DG_107[DG]; DG_108[DG]; DG_109[DG]; DG_11[DG]; DG_110[DG]; DG_111[DG]; DG_112[DG]; DG_113[DG]; DG_114[DG]; DG_115[DG]; DG_116[DG]; DG_117[DG]; DG_118[DG]; DG_119[DG]; DG_12[DG]; DG_120[DG]; DG_121[DG]; DG_122[DG]; DG_123[DG]; DG_124[DG]; DG_125[DG]; DG_126[DG]; DG_127[DG]; DG_128[DG]; DG_129[DG]; DG_13[DG]; DG_130[DG]; DG_131[DG]; DG_132[DG]; DG_133[DG]; DG_134[DG]; DG_135[DG]; DG_136[DG]; DG_137[DG]; DG_138[DG]; DG_139[DG]; DG_14[DG]; DG_140[DG]; DG_141[DG]; DG_142[DG]; DG_143[DG]; DG_144[DG]; DG_145[DG]; DG_146[DG]; DG_147[DG]; DG_148[DG]; DG_149[DG]; DG_15[DG]; DG_150[DG]; DG_151[DG]; DG_152[DG]; DG_153[DG]; DG_154[DG]; DG_155[DG]; DG_156[DG]; DG_157[DG]; DG_158[DG]; DG_159[DG]; DG_16[DG]; DG_160[DG]; DG_161[DG]; DG_162[DG]; DG_163[DG]; DG_164[DG]; DG_165[DG]"
                      memberOf: "Ad created secuirty grp; Administrators; Compliance Management; dg10; DG_1; DG_10; DG_100; DG_1000; DG_101; DG_102; DG_103; DG_104; DG_105; DG_106; DG_107; DG_108; DG_109; DG_11; DG_110; DG_111; DG_112; DG_113; DG_114; DG_115; DG_116; DG_117; DG_118; DG_119; DG_12; DG_120; DG_121; DG_122; DG_123; DG_124; DG_125; DG_126; DG_127; DG_128; DG_129; DG_13; DG_130; DG_131; DG_132; DG_133; DG_134; DG_135; DG_136; DG_137; DG_138; DG_139; DG_14; DG_140; DG_141; DG_142; DG_143; DG_144; DG_145; DG_146; DG_147; DG_148; DG_149; DG_15; DG_150; DG_151; DG_152; DG_153; DG_154; DG_155; DG_156; DG_157; DG_158; DG_159; DG_16; DG_160; DG_161; DG_162; DG_163; DG_164; DG_165; DG_166; DG_167; DG_168; DG_169; DG_17; DG_170; DG_171; DG_172; DG_173; DG_174; DG_175; DG_176; DG_177; DG_178; DG_179; DG_18; DG_180; DG_181; DG_182; DG_183; DG_184; DG_185; DG_186; DG_187; DG_188; DG_189; DG_19; DG_190; DG_191; DG_192; DG_193; DG_194; DG_195; DG_196; DG_197; DG_198; DG_199; DG_2; DG_20; DG_200; DG_201; DG_202; DG_203; DG_204; DG_205; DG_206;"
                      name: "dev"
                      distinguishedName: "CN=dev,CN=Users,DC=erpdev19,DC=com"
                      createdOn: "2023/10/27 03:30:12"
                  meta:
                    start_index: 1
                    limit: 50
                    total_no_of_objects: 2

  /reports/{id}/data/total-count:
    get:
      tags:
        - report
      summary: 'Get total count - report table data'
      description: 'Retrieves the total number of objects for a specific report.'
      parameters:
        - name: id
          in: path
          required: true
          description: 'The ID of the report to fetch the count for'
          example: 2000000000001
          schema:
            type: integer
        - $ref: '#/components/parameters/acceptHeader'
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getReportCountResponse'
        '400':
          description: 'Bad Request'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/invalidParam'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - X-ZCSRF-TOKEN: [ ]

  /reports/{id}/export:
    post:
      summary: Export Report
      description: Exports data for a specific report based on provided filters and view, allowing selection of export type.
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: The ID of the report to export data from.
          example: "12345" # Example based on context of id
        - in: query
          name: sort
          schema:
            type: string
          description: Sort order for the results to be exported. Prepend with '-' for descending order.
          example: "-APFDiscADUserDetails_SAM_ACCOUNT_NAME"
        - in: query
          name: filter
          schema:
            type: string
          description: Filter criteria for the results to be exported.
          example: "APFDiscADUserDetails_SAM_ACCOUNT_NAME co \"John@admp.com\" and APFDiscADUserDetails_DISPLAY_NAME co \"John\""
        - in: query
          name: view
          schema:
            type: string
          description: The view type for the report data to be exported.
          example: "default"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: 'export.yml#/components/schemas/exportResource'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/acceptJobResponse'
                  links:
                    $ref: '#/components/schemas/links'

  /reports/{id}/export_settings:
    get:
      summary: Get Export Settings
      description: Retrieves the current export settings for a specific report.
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: The ID of the report to retrieve export settings for.
          example: "12345" # Example based on context of id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/reportExportSettings'
    put:
      summary: Modify Export Settings
      description: Updates the export settings for a specific report.
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: The ID of the report to update export settings for.
          example: "12345" # Example based on context of id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/reportExportSettings'
      responses:
        '200':
          description: Export settings updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/reportExportSettings'

  /reports/{id}/send-email:
    post:
      summary: Direct Send Email
      description: Sends a report via email based on specified filters, view, and email template.
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: The ID of the report to send via email.
          example: "12345" # Example based on context of id
        - in: query
          name: sort
          schema:
            type: string
          description: Sort order for the report data. Prepend with '-' for descending order.
          example: "-APFDiscADUserDetails_SAM_ACCOUNT_NAME"
        - in: query
          name: filter
          schema:
            type: string
          description: Filter criteria for the report data.
          example: "APFDiscADUserDetails_SAM_ACCOUNT_NAME co \"John@admp.com\" and APFDiscADUserDetails_DISPLAY_NAME co \"John\""
        - in: query
          name: view
          schema:
            type: string
          description: The view type for the report data.
          example: "default"
        - in: query
          name: templateId
          schema:
            type: string
          required: true
          description: The ID of the email template to use for sending the report.
          example: "2000000127109"
      responses:
        '202':
          description: 'Accepted'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/acceptJobResponse'
                  links:
                    $ref: '#/components/schemas/links'

components:
  parameters:
    acceptHeader:
      name: Accept
      in: header
      schema:
        type: string
      description: 'Accept header for the API'
      required: false
      example: 'application/json'
  schemas:
    gendoc-attributes-schema:
      type: object
      $ref: '#/components/schemas/reports'

    reports:
      type: object
      properties:
        inputs:
          $ref: '#/components/schemas/reportInputResource'
        view_columns:
          $ref: '#/components/schemas/viewColumns'
        criteria_filter:
          $ref: '#/components/schemas/criteriaFilter'

    reportInputResource:
      type: object
      properties:
        domains:
          type: array
          items:
            $ref: '#/components/schemas/domainWithOU'
        domain:
          $ref: '#/components/schemas/domainWithOU'
        period:
          type: object
          description: No of days input - used in date based reports
          properties:
            days:
              type: integer
              description: No of days
              example: 30
            range:
              type: string
              description: Range of days
              example: "last7Days"
            start_date:
              type: string
              description: Start date of range
              example: "31/3/2025 06:30:00 PM"
            end_date:
              type: string
              description: End date of range
              example: "1/4/2025 06:30:00 PM"
        duration:
          type: object
          description: Used in logon hours report
          properties:
            days:
              type: array
              description: Array of days
              items:
                type: string
              example:
                - "Monday"
                - "Tuesday"
                - "Wednesday"
                - "Thursday"
                - "Friday"
                - "Saturday"
            from:
              type: string
              example: "4"
              description: selected value in hour
            to:
              type: string
              example: 24
              description: selected value in hour
        group_type:
          type: string
          example: "global"
          enum:
            - "distribution"
            - "security"
          description: Used in group type and scope reports.
        group_scope:
          type: string
          example: "universal"
          enum:
            - "global"
            - "domain_local"
            - "universal"
          description: Used in group type and scope reports
        attribute:
          type: string
          description: Used in attribute based reports
          example: "samAccountName"
        matching_criteria:
          type: string
          description: Matching criteria for attribute based reports
          example: "matchAll"
          enum:
            - "matchAll"
            - "matchAny"
        photo_based_selected:
          type: object
          description: Used in photo based reports
          properties:
            user_based_photo:
              type: string
              description: Used in photo based reports to specify user based photo
              example: "userWithPhoto"
              enum:
                - "userWithPhoto"
                - "userWithOutPhoto"
            user_based_photo_attribute:
              type: string
              description: Used in photo based reports to specify user based photo attribute
              example: "photo"
              enum:
                - "thumbnailPhoto"
                - "thumbnailLogo"
                - "photo"
        logon_permission:
          type: string
          example: "permittedHours"
          description: Used in logon hour based reports
        top:
          type: integer
          description: Used in Top N Big groups
          example: 7
        exclude_disabled_users:
          type: boolean
          description: Used in reports having advanced filter dropdown checkbox
          example: true
        never_logged_on_users:
          type: boolean
          description: Used in reports having advanced filter dropdown checkbox
          example: true
        account_expired_users:
          type: boolean
          description: Used in reports having advanced filter dropdown checkbox
          example: true
        based_on:
            type: string
            description: Used in reports having advanced filter dropdown checkbox
            example: "lastLogonTime"
        groups:
          type: array
          description: Used in popup input based reports for groups
          items:
            type: string
          example:
            - "2000000153382"
            - "2000000153332"
        exclude_nested_groups:
          type: boolean
          description: Used in reports having advanced filter dropdown checkbox
          example: false
        users:
          type: array
          description: Array of user IDs for manager report, array of manager user IDs.
          items:
            type: string
          example:
            - "2000000152382"
            - "2000000153332"
        attributes:
          type: array
          description: Used in popup input based reports based on attribute IDs
          items:
            type: string
          example:
            - "2000000152382"
            - "2000000153332"
        os:
          type: array
          description: Array of OS Ids for OS based reports
          items:
            type: string
          example:
            - "2000000100069"
            - "2000000099143"
        policies:
          type: array
          description: Array of policy Ids for policy based reports
          items:
            type: string
          example:
            - "2000000152382"
            - "2000000153332"

    viewColumns:
      type: array
      description: List of columns to be displayed in the report view.
      items:
        type: string
      example:
        - mail
        - sAMAccountName
        - memberOfLocation
        - memberOf
        - name
        - distinguishedName
        - createdOn

    criteriaFilter:
      type: object
      properties:
        rows:
          type: array
          items:
            type: object
            properties:
              appId:
                type: string
                description: The application ID associated with the criteria.
                example: "2000000021027"
              field_id:
                type: string
                description: The ID of the field being filtered.
                example: "2000000093880"
              display_name:
                type: string
                description: The display name of the field.
                example: "Object ID"
              operator_id:
                type: string
                description: The ID of the operator used for filtering.
                example: "2000000092917"
              operator_display_name:
                type: string
                description: The display name of the operator.
                example: "Starts With"
              logic_operator:
                type: string
                description: The logical operator used in the criteria (e.g., AND, OR).
                example: "AND"
              logic_operator_display_name:
                type: string
                description: The display name of the logical operator.
                example: "wsmclient.criteria.logic_operator.and"
              rowType:
                type: string
                description: Type of row, e.g., 'row'.
                example: "row"
              type:
                type: string
                description: Type of criteria, e.g., '2000000092896'.
                example: "2000000092896"
              value_component_id:
                type: string
                description: Component ID for the value input.
                example: "CRITERIA_TEXT_FIELD"
              value_object:
                type: string
                description: The value associated with the criteria.
                example: "one"
          example:
            - appId: "2000000021027"
              field_id: "2000000093880"
              display_name: "Object ID"
              operator_id: "2000000092917"
              operator_display_name: "Starts With"
              logic_operator: "AND"
              logic_operator_display_name: "wsmclient.criteria.logic_operator.and"
              rowType: "row"
              type: "2000000092896"
              value_component_id: "CRITERIA_TEXT_FIELD"
              value_object: "one"
            - appId: "2000000021027"
              field_id: "2000000093880"
              display_name: "Object ID"
              operator_id: "2000000092917"
              operator_display_name: "Starts With"
              logic_operator: "OR"
              logic_operator_display_name: "wsmclient.criteria.logic_operator.or"
              rowType: "row"
              type: "2000000092896"
              value_component_id: "CRITERIA_TEXT_FIELD"
              value_object: "two"
            - appId: "2000000021027"
              field_id: "2000000093880"
              display_name: "Object ID"
              operator_id: "2000000092917"
              operator_display_name: "Starts With"
              logic_operator: "AND"
              logic_operator_display_name: "wsmclient.criteria.logic_operator.and"
              rowType: "row"
              type: "2000000092896"
              value_component_id: "CRITERIA_TEXT_FIELD"
              value_object: "three"
        pattern:
          type: string
          description: A string representation of the logical structure of the criteria.
          example: "( 1 OR  2 AND  3 )"

    domainWithOU: # try to move inside report input
      type: object
      properties:
        id:
          type: string
          example: "200090909090"
          description: Domain ID
        ous:
          type: object
          description: Object to specify selected and unselected OUs
          properties:
            selected:
              type: array
              description: List of selected OUs ID
              items:
                type: integer
              example:
                - 20000909435000
                - 20000909435030
                - 20000909435004
            unselected:
              type: array
              description: List of unselected OUs ID
              items:
                type: integer
              example:
                - 20000909435900
                - 20000082399090
            exclude_child_ou:
              type: boolean
              description: A flag to specify exclusion of child OUs
              example: false

    domainWithoutOU:
      type: object
      properties:
        id:
          type: string
          example: "200008008080"
          description: Domain ID

    reportExportSettings:
      type: object
      properties:
        file_name:
          type: string
          description: The default file name for the exported report.
          example: "file name"
        description:
          type: string
          description: A description for the export settings.
          example: "description"
        include_logo_in_header:
          type: boolean
          description: Indicates whether the logo should be included in the report header.
          example: true
        show_logo_on_first_page_only:
          type: boolean
          description: Indicates whether the logo should appear only on the first page.
          example: true
        show_hyphen_for_empty_values:
          type: boolean
          description: Indicates whether a hyphen should be shown for empty values in the report.
          example: true
        include_serial_number_column:
          type: boolean
          description: Indicates whether a serial number column should be included in the report.
          example: true

    getReportCountResponse:
      type: object
      properties:
        total_no_of_objects:
          type: integer
          example: 310

    acceptJobResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the job.
          example: '2000000293042'
          readOnly: true
        status:
          type: string
          description: Status of the process initiated.
          enum:
            - 'QUEUED'
            - 'RUNNING'
            - 'WARNING'
            - 'COMPLETED'
            - 'ERROR'
          example: RUNNING
          readOnly: true
        message:
          type: string
          description: Message providing additional information about the accept response.
          example: Process is initiated, check jobs for current status.
          readOnly: true

    links:
      type: object
      readOnly: true
      properties:
        status:
          type: object
          properties:
            href:
              type: string
              example: /jobs/2000000293042
              description: URL to get the status of the job

    invalidParam:
      type: object
      properties:
        error_code:
          type: string
          example: "INVALID_PARAMETER"
        message:
          type: string
          example: "Invalid parameter value provided."
    unauthorized:
      type: object
      properties:
        error_code:
          type: string
          example: "UNAUTHORIZED"
        message:
          type: string
          example: "Authentication required or failed."
    serverError:
      type: object
      properties:
        error_code:
          type: string
          example: "INTERNAL_SERVER_ERROR"
        message:
          type: string
          example: "An unexpected error occurred."

  securitySchemes:
    X-ZCSRF-TOKEN:
      type: apiKey
      in: header
      name: X-ZCSRF-TOKEN
      description: >
        CSRF token to prevent cross-site request forgery attacks.
        Ensure this token is included in the request header.