4.3.11. TaskReportGenerate

Description

The method launches the process of generating a report file for the completed task.

Attention

• The system automatically generates reports only for tasks with the Completed status. For tasks with the Rejected, Canceled or Stalled statuses, report generation is not supported;

• Before generating the report, ensure that the task has the Completed status. To check the status, use the TaskStatus or TaskReport methods;

• When the task transitions to the Completed status, the system automatically generates a report in PDF format (by default). Available formats for automatic generation: CSV, JSON, PDF; You can change the default format or disable auto-generation in the Project settings ➝ the Generate a report tab.

• The TaskReportGenerate method can be used if you need a report in a non-default format (e.g., JSON or CSV instead of PDF).

Request

{
  "user_id":(number),
  "methods":[
    {
      "method":"TaskReportGenerate",
      "params":{
        "project_id":(number),
        "task_ids":' id1 | [id1,id2] | "*" ',
        "report_format":(string)
      }
    }
  ]
}

where:

• user_id — an integer value, a user identifier;

• project_id — an integer value, a user project identifier;

• task_ids — task identifiers, the field can be specified in one of the following formats:

  • id1 — an integer value, a task identifier,

  • [id1,id2] — an array of integer values, task identifiers,

  • "*" — a string, the “asterisk” symbol, request for all completed tasks.

• report_format — a string, specifies the format of the report file. Available formats: CSV, JSON, PDF.

Reply

{
  "reply":[
    {
      "method":"TaskReportGenerate",
      "result":[
        {
          "task_ids_in_process":[],
          "format":(string)
        }
      ],
      "errors":[(string)]
    }
  ]
}

where:

• task_ids_in_process — an array of integer values, task identifiers;

• format — a string, specifies the format of the report file. Available formats: CSV, JSON, PDF;

• errors — an array of strings that returns a list of errors.

Example

Request by the cURL utility

#1. Request a report for a single task.
curl http://172.16.1.41/ctrl_api/v1/json \
 -H "Content-Type: application/json" \
 --data '{"user_id":1,"methods":[{"method":"TaskReportGenerate","params":{"project_id":2,"task_ids":2213,"report_format":"JSON"}}]}'

#2. Request a report for tasks with task_id: 2213, 2222, 2288. The third task has a non-existent value specified in the task_ids field.
curl http://172.16.1.41/ctrl_api/v1/json \
 -H "Content-Type: application/json" \
 --data '{"user_id":1,"methods":[{"method":"TaskReportGenerate","params":{"project_id":2,"task_ids":[2213,2222,2288]"report_format":"JSON"}}]}'

#3. Request a report for an array of tasks with task_id: 2213, 2222, 2288, 2289, 2290. The example demonstrates possible values ​​for the errors field: a non-existent task (2288); a task that has been started but not yet completed (2289); a task with a ready-made report (2290).
curl http://172.16.1.41/ctrl_api/v1/json \
 -H "Content-Type: application/json" \
 --data '{"user_id":1,"methods":[{"method":"TaskReportGenerate","params":{"project_id":2,"task_ids":[2213,2222,2288,2289,2290],"report_format":"JSON"}}]}'

Reply to request from example #1

{
  "reply": [
    {
      "method": "TaskReportGenerate",
      "result": [
        {
          "task_ids_in_process": [
            2213
          ],
          "format": "JSON"
        }
      ]
    }
  ]
}

Reply to request from example #2

{
  "reply": [
    {
      "method": "TaskReportGenerate",
      "result": [
        {
          "task_ids_in_process": [
            2213,
            2222
          ],
          "format": "JSON"
        }
      ]
    }
  ]
}

Reply to request from example #3

{
  "reply": [
    {
      "method": "TaskReportGenerate",
      "result": [
        {
          "task_ids_in_process": [
            2213,
            2222
          ],
          "format": "JSON"
        }
      ],
      "errors": [
        "Cannot generate a report for tasks that are incomplete or do not exist: 2288, 2289",
        "The report has already been generated or is currently being generated for these tasks: 2290"
      ]
    }
  ]
}