Batch mode of Smartlink generation

The main purpose of this mode is to generate thousands of smartlinks at a time.

In the Batch mode, Smartlink Creator gets one master smartlink and generates smartlinks like a master one but with other PDFs and parametrised assets.

Smartlink creation strategies

Strategy	Description
smallest (default)	Smartlink contains links to JS scripts and PDF file
mixed	A part of the JS scripts will be placed inside of the Smartlink
original	All the JS scripts and PDF file will be placed inside of the Smartlink

To start files generation, customer calls POST /api/batch/<batch_id>/start (multipart/form-data request) with following parameters:

Parameter	Required?	Description
batch_id	yes	Unique Batch ID. Used as folder name in the File Storage bucket for generated smartlinks. Symbols allowed:
api_url	no*	Path to the ARGOflow API to get information about smartlink provided in template_id parameter. Required if template_id is provided.
document_id	no*	Smartlink ID of template to be used for batch generation. Required if document_file is not provided
document_file	no	Template file (smartlink's JSON) to be used for batch. To get this JSON you can use a call like https://api.argoflow.io/smartlinks/
data	no	JSON with parameters for replacements in a template. See data JSON example below
data_file	no	JSON file with parameters for replacements in a template. See data JSON example below
max_errors	no	Max amount of errors allowed before cancelling a batch
callback_emails	no	Comma-separated list of email to be informed once batch is finished
callback_url	no	Customer's callback URL. It will be used to inform customer about batch job status
strategy	no	Creation strategy. Can be "smallest" (default), "mixed", "original"

API responds with a job details. E.g.:

{
    "batch_id": "my-first-batch",
    "job_id": "e5c5daefbadfff523f5e1f4b7e60eab8",
    "status": "In progress",
    "started": "2021-06-25T13:13:10.477Z",
    "finished": null,
    "succeededCount": 0,
    "erroredCount": 0
}

Data (or data_file) example:

[
  {
    "pdf": "https://storage.your-server.com/0.pdf",
    "reference_id": "5ef3501829bf41003d6da7b4",
    "suffix": "5f1ea1e9b982f900468aeb5b",
    "data": {
      "num_client": "240 000 009 425",
      "montant": "500",
      "date": "2020-10-11"
    }
  },
  {
    "pdf": "https://storage.your-server.com/1.pdf",
    "reference_id": "5ef3501829bf41003d612345",
    "suffix": "5f1ea1e9b982f900468aeb77",
    "data": {
      "num_client": "240 000 009 738",
      "montant": "414,97",
      "date": "2021-01-12"
    }
  }
]

In the data file, pdf is a link to PDF file that will be augmented.\ reference_id is the client's unique document id.\ suffix is the unique sentence to be used for generated file name which will be like /<batch_id>/<reference_id>.<suffix>.html.\ data is the set of parameters that will be used for substitution in the template.

Generated files naming scheme

To be able to provide smartlinks directly from the storage (using NGINX as reverse proxy) we need to easily get smartlink's filename from the smartlink URL. Hackers can guess reference id and hence have a link to users data. To make this more difficult, we can add a second unique sentence (suffix) to be added to the smartlink file name. So link to the smartlink will looks like:

https://storage.your-server.com/batch/<batch_id>/5ef3501829bf41003d6da7b4.5f1ea1e9b982f900468aeb5b.html

And file name will be

5ef3501829bf41003d6da7b4.5f1ea1e9b982f900468aeb5b.html

5ef3501829bf41003d6da7b4.	5f1ea1e9b982f900468aeb5b.	html
Customer's Reference ID Suffix.	Unique sentence to avoid guessing	Extension

Other batch generation related calls:

Method	Call	Description
GET	/api/batch/<batch_id>/<job_id>/cancel	Cancel job
GET	/api/batch/<batch_id>/<job_id>/status	Get job's status
GET	/api/batch/<batch_id>/<job_id>/log	Get job's log