Description

The PDFGeneratorAPIFileReceiver reads a JSON file and makes a call to a 3rd Party PDF Tool to create a PDF using the defined PDF Template and synthetically generated data.


Note: This tool only delivers data in the PDF format and does not control the pixels, fonts, and other details of laying out the delivered data of a PDF document - that is the job of the PDF Tool. This task must be performed by the PDF Tool. GenRocket supplies the data, and the tool uses the data to create the image or PDF. 


PDF Tool Example

PDF Generator API


PDF Generator API Notes:

  • If you do not have an account on the PDF Generator API, one will need to be created to use the PDF template to create a PDF file.
  • You can also go to the documentation of PDF Generator API to understand how the JSON files payload data will be mapped with the PDF template.


In This Article


Receiver Demonstration Video

The following video provides a full demonstration and example of how to use the PDFGeneratorAPIFileReceiver.

Important: This video shows using two Domains  - one to create the payload and one to create the actual PDF files. However, you can set it up using one Domain and assign both Receivers to the Domain. The Receiver generating the payload needs to be added first. Doing so provides better performance and reduces setup time.
 


Receiver Parameters

The following parameters may be configured for the PDFGeneratorAPIFileReceiver. Parameters with an asterisk (*) are required.

  • *outputPath - The location where the output file will be stored. It defaults to the configured resource.output.directory path.
  • outputSubDir - The prefix name of sub-directories that are auto-created under the outputPath and then appended with a number. (e.g., pdfData1, pdfData2, pdfData3, etc.). These subdirectories will be created within the user's output directory path based on the filesPerOutputSubDir parameter.
  • *filesPerOutputSubDir - The number of files to be generated per output subdirectory.
  • *configPath - The location where the PDF configuration file is stored on the user's local computer.
  • configSubDir - The subdirectory under the configPath directory where configuration and template files are stored.
  • *configFileName - Name of the configuration file.
  • *payloadFilesPath - The location of the JSON files on the user's local computer from where the PDFGeneratorAPIFileReceiver will read the file content and pass the data as a payload.
  • *payloadFilesSubDir - The prefix name of subdirectories under the payloadFilesPath where the payload JSON files are stored.


Configuration File for Output Files

A Configuration File is required to define the name of the generated PDF file(s). This file also includes the PDF Document API account and PDF template data to authenticate the REST API call. 


The following parameters can be configured for this file and are required to use the PDFGeneratorAPIFileReceiver: 

  • configPath - The location where the configuration file is stored on the user's local computer.
  • configSubDir - The subdirectory where the configuration file is stored on the user's local computer. For example, if the user's output path is the Downloads Folder and the configuration file is stored in a subdirectory titled "Config Files" within this folder, then Config Files would be entered for this parameter.
  • configName - Name of the configuration file to be used with the PDFGeneratorAPIFileReceiver.


    Note: If the configuration file is stored in a subdirectory of the output directory, then the user will need to specify it as well for the configSubDir parameter.


Configuration File Properties

To configure the PDF files generated from the PDFGeneratorAPIFileReceiver, a user will need to create an XML formatted configuration file with the following property elements below:

  • fileNameSegments  - This element tag is used to define the format for the generated PDF file's name.
  • apiDetails- This element tag is used to provide the PDFDocumentAPI account details.
    • Workspace - It is a unique string created by the PDF tool application that identifies the workspace.
    • Key - It is the API key found under the user's Account Settings in the PDF tool.
    • SecretKey - It is the API secret found under the user's Account Settings in the PDF tool.
    • TemplateId - It is the API request for resource Template Id, which will be used to generate PDF files (e.g., 123456, 214356, etc.).


Sample Configuration File

The following is an example configuration file showing the XML format that defines the configuration file of a PDFGeneratorAPIFileReceiver.


<config>
    <fileNameSegments>
        <fileNameSegment segmentType='Constant' value='Invoice-' />
        <fileNameSegment segmentType='Counter' value='1' />
        <fileNameSegment segmentType='Constant' value='.pdf' />
    </fileNameSegments>

    <apiDetails>
        <apiDetail detailType='Workspace' value='ADD_WORKSPACE_HERE'/>
        <apiDetail detailType='Key' value='ADD_YOUR_KEY_HERE'/>
        <apiDetail detailType='SecretKey' value='ADD_YOUR_SECRET_KEY_HERE'/>
        <apiDetail detailType='TemplateId' value='ADD_TEMPLATE_ID_HERE'/>
    </apiDetails>
</config>


Configuration File Example

In the example below, a configuration file titled config.properties resides in the user's resource output directory and will be used to format the generated PDF file(s). The configuration can be seen below: 



Note: If the configuration file is stored in a subdirectory of the output directory, then the user will need to specify it as well for the configSubDir parameter.


Example Stories

The example stories below, show different use cases where the PDFGeneratorAPIFileReceiver is used to create a PDF file(s) using the JSON file data as a payload.


Story 1 - Create a PDF File using the JSON File data

For this example, data will be output to a single PDF file within a user's defined output data path using a configuration file.


Receivers Parameters

The following configuration will generate one subdirectory titled pdfData and create one PDF file as per the name provided in the configuration file (e.g., Invoice-1.pdf).

  • outputSubDir- pdfData will be entered.
  • configName - PDFConfig.xml has been entered, which will be used by the PDFGeneratorAPIFileReceiver.
  • configPath - The output directory path has been entered here.
  • configSubDir - config has been entered here, which is the subdirectory of the output directory where the configuration file is stored on the user's local computer.
  • filesPerOutputSubDir - 10 files will be generated per outputSubDir subdirectory.


Configuration File

The following is an example configuration file showing the XML format that defines the configuration file of a PDFGeneratorAPIFileReceiver.


<config>
    <fileNameSegments>
        <fileNameSegment segmentType='Constant' value='Invoice' />
        <fileNameSegment segmentType='Constant' value='.pdf' />
    </fileNameSegments>

    <apiDetails>
        <apiDetail detailType='Workspace' value='ali@genrocket.com'/>
        <apiDetail detailType='Key' value='d12345678XXXXXXXXXXXXXXXXXXXXXXXXXXXXX86241be9'/>
        <apiDetail detailType='SecretKey' value='d5cc062ef9XXXXXXXXXXXXXXXXXXXXXXXXXXXXX034ec'/>
        <apiDetail detailType='TemplateId' value='27664'/>
    </apiDetails>
</config>



Config File Location

The following is the location of the PDFConfig.xml file:


Payload File Location

The following is the location of the payload file UserStory-1.json file:


File Output

The following is the subdirectory and file created based on the configuration above:


Sample Output



Story 2 - Create Multiple PDF Files with Incremental Counter as Suffix

In this example, data will be output to multiple PDF files within a user's defined output data path using a configuration file.


For example, if there are 10 JSON files as a payload, which will be generating 10 PDF files, they would be named as per the configuration files set up accordingly:

  • Invoice-1.pdf
  • Invoice-2.pdf
  • Invoice-3.pdf
  • ...
  • Invoice-10.pdf


Important: If data for multiple files exists in one JSON payload file, then only one PDF file will be generated, and it will only contain the first set of data. 


PDFGeneratorAPIFileReceiver Configuration File

The segmentType='Counter' with a value='1' is set up as a suffix, which can be used to add a file name for each file. 


<config>
    <fileNameSegments>
        <fileNameSegment segmentType='Constant' value='Invoice-' />
        <fileNameSegment segmentType='Counter' value='1' />
        <fileNameSegment segmentType='Constant' value='.pdf' />
    </fileNameSegments>

    <apiDetails>
        <apiDetail detailType='Workspace' value='ali@genrocket.com'/>
        <apiDetail detailType='Key' value='d12345678XXXXXXXXXXXXXXXXXXXXXXXXXXXXX86241be9'/>
        <apiDetail detailType='SecretKey' value='d5cc062ef9XXXXXXXXXXXXXXXXXXXXXXXXXXXXX034ec'/>
        <apiDetail detailType='TemplateId' value='27664'/>
    </apiDetails>
</config>



The generated files in each subdirectory will appear as shown below for this example: