Skip to content

pdfshift adaptor documentation #698

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

pdfshift adaptor documentation #698

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b334bf7
fix: add pdf generator documentation
hunterachieng Aug 14, 2025
aaadb3f
fix: update docs and examples for pdfShift
hunterachieng Aug 15, 2025
e594c20
add pdf example
hunterachieng Aug 15, 2025
dc775a5
fix pdf examples and docs
hunterachieng Aug 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions adaptors/library/jobs/generate-pdf.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
// Generate a PDF document from a HTML string

fn(state => {
const { data } = state;

state.pdfHTMLContent = `<html>
<body style="font-family: Arial, sans-serif; font-size: 14px;">
<h1>Sales Report</h1>
<p>Date: ${data.date}</p>
<p>Total Sales: $${data.totalSales}</p>
</body>
</html>`;

return state;
});

generatePDF($.pdfHTMLContent, {
sandbox: true,
filename: 'trials.pdf', // Returns a JSON response containing an url parameter to PDFShift's Amazon S3 bucket.
// The URL expires after 48 hours
});

fn(state => {
const { data } = state;
const pdfData = JSON.parse(data);
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey this is weird - why are we JSON parsing this?

I think we need to update generatePDF to parse the JSON automatically. There's no sense in forcing users to do it.

Also, I think we need to better document what generatePDF returns. I assumed it was a PDF buffer of some kind

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It returns a PDF buffer or a base64. But if you want a url that is hosted on pdfShift's s3 bucket, then you add the filename: <filename> option which returns a JSON string :

 "data": "{\"success\":true,\"url\":\"https://pdfshift.s3.amazonaws.com/d/2/2025-08/fbe4debd68d841e4bf05eb04f0dd2693/trials.pdf\",\"filesize\":50023,\"duration\":2156,\"response\":{\"status-code\":200,\"content-length\":0,\"requests\":0,\"duration\":1985.0274124145508},\"executed\":\"2025-08-18T14:38:12.560874\",\"pdf_pages\":1}",

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, but my surprise and confusion here is a problem.

Where is this stuff documented? How is the user supposed to know?

console.log(`Download PDF in 48 hours from ${pdfData.url}`);
return { ...state, pdfData };
});
5 changes: 5 additions & 0 deletions adaptors/library/staticExamples.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,11 @@
"adaptor": "postgresql",
"name": "Using findValue with an array of data"
},
{
"expressionPath": "jobs/generate-pdf",
"adaptor": "pdfshift",
"name": "Generate a PDF from a HTML string"
},
{
"expressionPath": "jobs/kobotoolbox-get-suspected-patients",
"adaptor": "kobotoolbox",
Expand Down
42 changes: 42 additions & 0 deletions adaptors/pdfshift.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
title: PDFShift Adaptor
---

## About PDFShift

[PDFShift](https://pdfshift.io/) is a solution designed to automate document
conversion tasks.

## Integration Options

PDFShift has a REST API that enables external services like OpenFn to pull data
from PDFShift, or push data from external apps to PDFShift. This option is
suited for scheduled, bulk syncs or workflows that must update data in PDFShift
with external information. See [functions](/adaptors/packages/pdfshift-docs) for
more on how to use this adaptor to work with the API.

## Authentication

See [PDFShift docs](https://docs.pdfshift.io/#authentication) for the latest on
supported authentication methods. When integrating with PDFShift via OpenFn,
only one primary authentication method is supported.

1. Api Key (requires api key created after authenticating in PDFShift). See this
adaptor's
[Configuration docs](/adaptors/packages/pdfshift-configuration-schema) for
the required authentication parameters.

See platform docs on
[managing credentials](/documentation/manage-projects/manage-credentials) for
how to configure a credential in OpenFn. If working locally or if using a Raw
JSON credential type, then your configuration will look something like this:

```json
{
"apiKey": "sk_563874gfvftdv2t28462763fy23d28"
}
```

### Helpful Links

1. [PDFShift Documentation](https://docs.pdfshift.io/#introduction)