Invoice Tutorial¶

Invoice Report Tutorial¶

In this tutorial, we'll set up all necessary components in a blank workspace to create a new template for printing invoices.

Assuming you have just launched a new workspace that is completely blank, we'll set up a few crucial elements:

Set Up a Theme¶

A theme controls the aesthetics of your report, such as the choice of colors and typography styles.

Navigate to the Themes page and create a new theme named "Blue theme." Once there, follow these steps:

Introduce a new color named primary with the value #3b25e4. This color will subsequently be accessible throughout your report by its name.
On the Text tab, initially set the Font Family to Inter and the Font Size to 14px.
Because Inter is an external font, switch to the External CSS tab and append the following link: https://fonts.googleapis.com/css2?family=Inter:[email protected]. Returning to the Text tab will confirm the font is now correctly applied.
Proceed to define the styles for paragraphs and headers.

Once the text styles are complete, proceed to the Tables tab and ensure the following settings:

For Headers:

Set the font weight to Bold, the font size to 11px, and set the text to Uppercase.
Set a bottom border of 1px solid black.

For Cells:

Apply a bottom border of 1px dashed lightgray.

Preview the table styles to confirm they match your desired default look. Remember to click Save theme when finished.

Languages, Report Types, Page Types¶

A few more Workspace Configuration changes need to be added:

In Languages, add English and French with codes en and fr accordingly, indicating the supported languages, and add culutre codes as en-US and fr
Under Report Types, create a new type called Invoice with the code invoice.
In Page Types, introduce a Standard page with the description "Standard counted page".

Templates¶

Think of templates as the blueprint for page layouts and design, similar to Slide Masters in PowerPoint.

Visit the Templates section to create a new template named "Standard", and apply the "Blue theme".

When the editor appears, please execute the following steps:

Enable the Standard page type from the left sidebar.
Drag and drop the Flow component from the component palette to the top of the page, above the "Placeholder (master)". You can also use "Elements" tab on the left sidebar and drag & drop components there.
Add the Text component into the created flow.
Double-click the text and enter your company's actual name.
Using the right sidebar, style the text using the primary font color, set the size to 24px, and make it bold.
Locate the Spacer component and place it just below the flow.
Adjust the spacer to set the top padding.
Scroll to the bottom of the page and add a Text component there.
Update this text to {$page.number} of {$report.pageCount}.
In the Text component's editor on the right sidebar, align the text to the right.
Go to the Page tab in the top ribbon and activate the "Count this page" option.

Upon completion, you have created a Standard page template with consistent headers and footers for each page of its type.

Next, navigate to the Reports section by clicking the product logo at the top left corner.

Making the Invoice¶

Create a new report named "Invoice" with the type set to Invoice and select the Standard template. A blank editor will open up.

JSON Data¶

Add the invoice data before introducing any visual components. For the purposes of this example, use the static JSON object provided:

{
  "invoiceNumber": "12345",
  "dateIssued": "2024-01-27",
  "dueDate": "2024-02-10",
  "recipient": {
    "name": "ABC Enterprises",
    "address": "456 Enterprise Blvd, Commerce City, CC 67890",
    "phone": "987-654-3210",
    "email": "[email protected]"
  },
  "items": [
    {
      "description": "Product 1",
      "quantity": 10,
      "unitPrice": 29.99,
      "total": 299.9
    },
    {
      "description": "Product 2",
      "quantity": 5,
      "unitPrice": 49.99,
      "total": 249.95
    }
  ],
  "subTotal": 549.85,
  "taxRate": 0.07,
  "taxAmount": 38.49,
  "total": 588.34,
  "notes": "Thank you for your business. Please make payment by the due date."
}

To utilize this data within your report, add it as a data source by clicking on "Data sources" in the Report tab on the top ribbon. Name the new data source invoice, select the JSON type, and input the provided JSON data.

Adding Visual Elements¶

New Page¶

To begin, click on the New page button located within the Pages tab on the left-hand sidebar. Choose the Standard page type from your page options. You'll be presented with a blank sheet that already incorporates your defined company template.

Now you can move on to adding the necessary visual elements to construct your invoice.

Title¶

Begin by placing a Text element at the top of the page.
Double-click the newly added Text element and type Invoice #{$data.invoice.invoiceNumber} into the field.
Center the text, apply a bold style, and set the font size to 24px.
Incorporate a Spacer before and after the text to fine-tune the vertical spacing.

Bill To Section¶

Add a Flow element below the title and make it horizontal using the right sidebar.
Inside this flow, create a new vertical Flow. Resize it to obtain about half of the page width and set an aproximate height of 100px. This can also be adjusted in the Appearance tab, as needed.
Insert a Text element titled "BILL TO" into the vertical flow, make the text bold, and set the font color to primary.
Below that, add another Text block with {$data.invoice.recipient.name}. Make it bold and set 20px for font size.
Continue with a Text block for the address using {$data.invoice.recipient.address}.
Right-click the address text component, select Locate to find it in the Elements tree, copy it, and then paste it as a duplicate within the parent Flow.
Adjust the duplicate element's text to {$data.invoice.recipient.phone} and replicate this step once more for the email, ensuring to use {$data.invoice.recipient.email}.

Details Section¶

Add another Flow element within the horizontal Flow, just next to the "Bill To" section.
In "Elements" tab, insert a new vertical Spacer between two flows and resize it to be approximately 100px wide. Now, two flows should be side by side.
Copy the "BILL TO" element and paste it into the new vertical Flow, renaming it to "DETAILS".
Below that, add a Key Value Grid component.
Click Configure on the right to set up keys and values.
The first key-value pair should be Issue Date: and {$data.invoice.dateIssued:d}. On top left add another key-value pair with Due Date: and {$data.invoice.dueDate:d}. Note the :d suffix in the string template. This means format as a date.
Close the editor and adjust the styling in the Row Styling area, bolding the Value and setting the Key Field Width to 100px.

Invoice Items¶

Select the "BILL TO" text element in your report.
Use the Locate function to find and highlight this element within your document's element hierarchy.
Right-click the highlighted element and select Copy from the context menu.
Right-click the top-level Content select Paste.
Once the element is pasted, rename it to "ITEMS" by double-clicking on the text or using the properties panel placed on the right side of the editor.
Add Spacers as necessary by dragging and dropping them from the component palette.
Below the "ITEMS" heading, insert a Data Table component to organize the itemized details of the invoice.
In the Data source field of the data table's properties, select invoice.items.
Click on Generate columns to automatically create column fields based on your JSON structure.
For further customization such as formatting currency, double-click the table or access the Column settings.
In the Description column, scroll down to Footer and Caption section, enable footer and input "TOTAL" under Text field which will appear as the table's summary row.
For the Unit Price column, under Content menu, establish a Custom format by selecting the Format type option and entering currency;USD;2, which denotes the currency format and two decimal precision.
For Total column, apply the same currency formatting, scroll down to Footer and Caption section and modify the footer's aggregate function to Sum to automatically calculate the sum of the items' totals.

Save the completed adjustments. Your data table is now ready.

Total Section¶

To keep this tutorial concise, we will skip detailing this section. Utilize your knowledge of Flow, Text, and Key Value Grid components to assemble this part on your own.

Notes¶

Below everything, add a "NOTES" Text element, styling it in bold with the primary color font.
Insert another Text element and populate it with {$data.invoice.notes}.
Access the Appearance tab on the right and in the Box Style, insert the following CSS styling:
```
padding: 8px;
border: 1px dashed lightgray;
min-height: 100px;
```

Preview and PDF Export¶

Finally, to review your report:

Click on the Report tab in the top ribbon.
Check the Preview report to evaluate the final look.
Adjust any spacing as necessary to ensure a consistent format.
Use the Export PDF option to create a PDF version of your document.

Generating PDFs using the API¶

To enable PDF generation of the report using the API, please follow these additional setup steps:

Access the Report Types in the Workspace Configuration section. Set the default report for the invoice report type to the newly created report.
Navigate to Personal Access Tokens by clicking on the user menu in the top right corner of the screen.
Create a new token, often referred to as a PAT, and ensure it's stored in a secure location. This token will be revealed only once and grants API access to the application, mirroring the privileges of the logged-in user.
Utilize a tool such as Postman, curl, or an equivalent to send a request formatted as follows:

GET http://localhost:80/api/v1/ws/{workspaceId}/reports/{reportTypeCode}/pdf

To find your workspace ID, refer to the URL in your browser—it's the number located directly after ws/. The {reportTypeCode} should be set to invoice, as defined when you initially configured the report types.

It's essential to include the Authorization header set to Bearer {PAT} with your request.

And with that, you can straightforwardly download the invoice.

Providing Data for the Invoice¶

Should you use the static JSON data source, the same invoice details will always be applied. However, it's possible to override this by supplying your own data using the data query string parameter. Ensure the keys in the provided object match the names of the data sources in the report, with corresponding data structures.

{
  "invoice": {
    "invoiceNumber": "54321",
    "dateIssued": "2024-02-27",
    "dueDate": "2024-03-10",
    "recipient": {
      "name": "XYZ Enterprises",
      "address": "567 Enterprise Blvd, Commerce City, CC 56789",
      "phone": "987-654-3210",
      "email": "[email protected]"
    },
    "items": [
      {
        "description": "Product 1",
        "quantity": 10,
        "unitPrice": 29.99,
        "total": 299.90
      },
      {
        "description": "Product 2",
        "quantity": 5,
        "unitPrice": 49.99,
        "total": 249.95
      }
    ],
    "subTotal": 549.85,
    "taxRate": 0.07,
    "taxAmount": 38.49,
    "total": 588.34,
    "notes": "The data for this invoice is provided through the data query string parameter."
  }
}

Conclusion¶

By completing this tutorial, you're now equipped with the knowledge to set up a workspace, develop a new report, and access it using the API.