Report operation



Introduction

Once you have created the "Case file", an "Evidence Group" within this "Case file" and some "Evidences" within this "Evidence Group", you can generate a report.


Operations

Generate report preview

HTTP Request

POST /api/v1/private/case-files/{caseFileId}/report-preview

In this request, there is one primary resource case-files. There are also 1 resource identifier that you need to replace with real values of your EADFactory account: caseFileId.

With the following information provided as JSON:

{
        "template": "BASIC",
        "languageCode": "es_ES",
        "data": {
          "groups": [
            {
              "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
              "code": "example code",
              "name": "example name",
              "description": "example name",
              "type": "FILE",
              "capturedFrom": "2023-10-25T05:48:54.530Z",
              "capturedUntil": "2023-10-25T05:48:54.530Z",
              "evidences": [
                {
                  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                  "title": "example title"
                }
              ]
            }
          ]
        },
        "additionalData": {
          "additionalProp1": {}
        },
        "metadata": {
          "additionalProp1": "string"
        }
      }

Request body parameters

Parameter Mandatory Datatype Description
template yes string The name of the template to use, e.g. "BASIC". Must match the pattern ^[A-Z][A-Z0-9_]+$ (uppercase letters, digits and underscores only) or you will get a 400 Bad Request. The catalogue of templates available for your tenant is managed by the document generation service; confirm the exact names with your EADFactory contact.
languageCode yes string The language of the report, e.g. "es_ES". It is combined with template to find the template, so it must match one of its languages exactly (for example es_ES or en_EN, not es or en_US). The available languages depend on the templates configured for your tenant.
data yes object The data of the report. Example:
 "data": {
            "groups": [
              {
                "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                "code": "example code",
                "name": "example name",
                "description": "example name",
                "type": "FILE",
                "capturedFrom": "2023-10-25T05:48:54.530Z",
                "capturedUntil": "2023-10-25T05:48:54.530Z",
                "evidences": [
                  {
                    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                    "title": "example title"
                  }
                ]
              }
            ]
          },
          
. List every "Evidence Group" you want in the report, each one with its id and the "Evidences" within it that you want to incorporate: the id and title of each one are enough, the rest is filled in from the evidence. Do not omit it unless your EADFactory contact confirms that your template collects the evidences by itself: otherwise the groups reach the report without evidences and the report cannot be generated.
additionalData no object Map with key:value format with extra data made available to the template. Some templates take their cover data from here, such as the report code and name or the link shown as a QR code; ask your EADFactory contact which keys yours uses. Missing keys come out empty in the report.
metadata no object Map with key:value format with metadata of the report preview

As response, you will get an HTML with the preview of the Report.

If the template is not available for your tenant, the response body carries an error instead of the HTML.

If template does not match the required pattern, you will get a 400 Bad Request response.

Generate signed report

HTTP Request

POST /api/v1/private/case-files/{caseFileId}/reports

In this request, there is one primary resource case-files. There are also 1 resource identifier that you need to replace with real values of your EADFactory account: caseFileId.

With the following information provided as JSON:

{
        "reportId": "4ga85f64-5717-4562-b3fc-2c963f66afb7",
        "template": "BASIC",
        "languageCode": "es_ES",
        "filename": "example-report",
        "data": {
          "groups": [
            {
              "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
              "code": "example code",
              "name": "example name",
              "description": "example name",
              "type": "FILE",
              "capturedFrom": "2023-10-25T05:48:54.530Z",
              "capturedUntil": "2023-10-25T05:48:54.530Z",
              "evidences": [
                {
                  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                  "title": "example title"
                }
              ]
            }
          ]
        },
        "additionalData": {
          "additionalProp1": {}
        },
        "metadata": {
          "additionalProp1": "string"
        },
        "deletionDate": "2030-01-01T00:00:00Z"
      }

Request body parameters

Parameter Mandatory Datatype Description
reportId yes UUID An identification for the report. UUID V4
template yes string The name of the template to use, e.g. "BASIC". Must match the pattern ^[A-Z][A-Z0-9_]+$ (uppercase letters, digits and underscores only) or you will get a 400 Bad Request. The catalogue of templates available for your tenant is managed by the document generation service; confirm the exact names with your EADFactory contact.
languageCode yes string The language of the report, e.g. "es_ES". It is combined with template to find the template, so it must match one of its languages exactly (for example es_ES or en_EN, not es or en_US). The available languages depend on the templates configured for your tenant.
filename no string Name of the generated report file. Defaults to reportId when not provided
data yes object The data of the report. Example:
 "data": {
            "groups": [
              {
                "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                "code": "example code",
                "name": "example name",
                "description": "example name",
                "type": "FILE",
                "capturedFrom": "2023-10-25T05:48:54.530Z",
                "capturedUntil": "2023-10-25T05:48:54.530Z",
                "evidences": [
                  {
                    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                    "title": "example title"
                  }
                ]
              }
            ]
          },
          
. List every "Evidence Group" you want in the report, each one with its id and the "Evidences" within it that you want to incorporate: the id and title of each one are enough, the rest is filled in from the evidence. Do not omit it unless your EADFactory contact confirms that your template collects the evidences by itself: otherwise the groups reach the report without evidences and the report cannot be generated.
additionalData no object Map with key:value format with extra data made available to the template. Some templates take their cover data from here, such as the report code and name or the link shown as a QR code; ask your EADFactory contact which keys yours uses. Missing keys come out empty in the report.
metadata no object Map with key:value format with metadata of the report
deletionDate no datetime Date from which the report will be scheduled for deletion. Must be at least the configured minimum threshold in the future

This operation is asynchronous: the request starts the generation and timestamping process of the report and the endpoint returns immediately with an empty body. You will be notified when the report is ready (see Webhook notifications), and you can then use Get Report PDF URL / Get Report ZIP URL to download it.

As response, you will get

201 Generated signed report request accepted

The 201 only means that the request was accepted. If the report cannot be generated afterwards (for example, because the template is not available for your tenant or a group has no evidences), it is never created and Get Report PDF URL keeps answering as if it did not exist.

If template does not match the required pattern, or deletionDate violates the minimum configured deletion threshold, you will get a 400 Bad Request response.

Update report

To update the scheduled deletion date of a report you can make the following request using the id of the "Case file" and the id of the report.

HTTP Request

PATCH /api/v1/private/case-files/{caseFileId}/reports/{reportId}

With the following information provided as JSON:

{
        "deletionDate": "2030-01-01T00:00:00Z"
      }

Request body parameters

Parameter Mandatory Datatype Description
deletionDate no datetime Date from which the report will be scheduled for deletion. Set to null to cancel a scheduled deletion

As response, you will get

204 Updated successfully

If the report does not exist, you will get a 404 Not found response. If deletionDate violates the minimum configured deletion threshold, you will get a 422 Unprocessable Entity response.

Delete report

To delete a report you can make the following request using the id of the report.

HTTP Request

DELETE /api/v1/private/reports/{reportId}

As response, you will get

204 Report deleted

If the report does not exist, you will get a 404 Not found response.

Get Report PDF URL

HTTP Request

GET /api/v1/private/reports/{reportId}/document

You need to replace reportId with the identifier of the report you want to download.

As response, you will get the following JSON object with the temporary download URL:

{
        "url": "http://example.io",
        "expiration": "2023-10-24T21:36:26.092Z"
      }

If the report type requested is not valid, you will get a 406 Not Acceptable response.

An identifier that does not resolve does not always come back as a 404. Measured behaviour: the request can hang for around 30 seconds and then return a 500. Set a client timeout above that, and treat a slow 500 here as "not there yet or not there at all", not as a platform failure worth retrying in a loop.

Reports are generated asynchronously, so a report you just asked for may not be ready yet. Poll with a backoff instead of retrying immediately.

Deprecated: the previous route GET /api/v1/private/case-files/{caseFileId}/reports/{reportId}/document is deprecated and kept only for backward compatibility. Use the route above instead.

Get Report ZIP URL

HTTP Request

GET /api/v1/private/reports/{reportId}/package

You need to replace reportId with the identifier of the report you want to download.

As response, you will get the following JSON object with the temporary download URL:

{
        "url": "http://example.io",
        "expiration": "2023-10-24T21:36:26.092Z"
      }

If the report type requested is not valid, you will get a 406 Not Acceptable response.

An identifier that does not resolve does not always come back as a 404. Measured behaviour: the request can hang for around 30 seconds and then return a 500. Set a client timeout above that, and treat a slow 500 here as "not there yet or not there at all", not as a platform failure worth retrying in a loop.

Reports are generated asynchronously, so a report you just asked for may not be ready yet. Poll with a backoff instead of retrying immediately.

Deprecated: the previous route GET /api/v1/private/case-files/{caseFileId}/reports/{reportId}/package is deprecated and kept only for backward compatibility. Use the route above instead.