Report operation
Contents
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:
. 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:
. 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.