Forem: Raymond Camden

Interrogate Your PDFs with Chrome AI

Raymond Camden — Thu, 29 Jan 2026 18:00:00 +0000

Yesterday I blogged about using PDF.js and Chrome's on-device AI to create summaries of PDF documents, all within the browser, for free. In that post I mentioned it would be possible to build a Q and A system so users could ask questions about the document, and like a dog with a bone, I couldn't let it go. Last I built not one, but two demos of this. Check it out.

Version One

Before I begin, note that this version makes use of the Prompt API, which is still behind a flag in Chrome. For this demo to work for you, you would need the latest Chrome and the right flags enabled. The Prompt API is available in extensions without the flag and it wouldn't surprise me if this requirement is removed in the next few months. Than again, I don't speak for Google so take that with a Greenland-sized grain of salt.

If you remember, I shared the code yesterday that parsed a PDF and grabbed the text, so today I'll focus on the changes to allow for questions.

First, the HTML now includes a text box. I hide this in CSS until a PDF is selected and parsed.

<h2>PDF Q & A</h2>
<p>
Select a PDF and then ask questions. 
<input type="file" id="pdf-upload" accept=".pdf" />
</p>
<div id="chatArea">
    <input id="question"> <button id="ask">Ask about the PDF</button>
    <div id="response"></div>
</div>

In the JavaScript, I once again use feature detection:

async function canDoIt() {
    if(!window.LanguageModel) return false;
    return (await LanguageModel.availability()) !== 'unavailable';
}

// in my DOMContentLoaded event handler:

// do an early check
let weCanDoIt = await canDoIt();
if(!weCanDoIt) {
    alert("Sorry, this browser can't use the Prompt API.");
    return;
}

After the user has selected a PDF and the text is parsed, I then run enableChat:

async function enableChat(text,title) {
    $chatArea.style.display = 'block';
    let session = await LanguageModel.create({
        initialPrompts: [
            {role:'system', content:`You answer questions about a PDF document. You only answer questions about the document. If the user tries to ask about something else, tell them you cannot answer it. Here is the text of the document:\n\n${text}`}
        ]
    });

    $ask.addEventListener('click', async () => {
        $response.innerHTML = '';
        let q = $question.value.trim();
        if(q === '') return;
        console.log(`ask about ${q}`);
        $response.innerHTML = '<i>working...</i>';
        let response = await session.prompt(q);
        console.log(`response: ${response}`);
        $response.innerHTML = marked.parse(response);
    });
}

Note in the system instruction I tell the model to stick to the PDF, so if the user does something cute like, "why are cats better than dogs", the system will direct them back to the document. I had to put two statements about this in the system information as one didn't seem to be good enough.

I'll include the demo below, but assuming most of you won't be able to run it, here's a few examples using an incredibly boring Adobe security document.

That's pretty much the same as the summary, so let's try something specific:

And finally, here's what happens if I try to go off topic:

As a reminder, you can't use beefy PDFs in this demo, and unlike yesterday's post, I didn't add a good error handler for that. Sorry!

Version Two

I was pretty happy with the initial version, but I was curious if the on-device model could handle creating references to the document?

I began by keeping the page text in an array instead of one big string:

let fullText = [];

for (let i = 1; i <= pdf.numPages; i++) {
    const page = await pdf.getPage(i);

    const textContent = await page.getTextContent();

    // Note: 'item.str' is the raw string. 'item.hasEOL' can be used for formatting.
    const pageText = textContent.items.map(item => item.str).join(' ');

    fullText.push(pageText);
}

Then I modified by enableChat a few ways. First, I created a new block of text that marked the pages:

let pagedText = '';
textArr.forEach((t,x) => {
    pagedText += `

Page ${x+1}:
${t}

`;
});

I think this could be better, perhaps with a --- around the page content. Next I modified the system prompt:

let session = await LanguageModel.create({
    initialPrompts: [
        {role:'system', content:`You answer questions about a PDF document. You only answer questions about the document. If the user tries to ask about something else, tell them you cannot answer it. The text is split into pages marked by: "Page X:", where X represents the page number. When you answer questions, always give a reference to the page where you found your answer. Here is the text of the document:\n\n${pagedText}`}
    ]
});

Oddly, this wasn't enough. I'd ask a question, but wouldn't get references. However, if I asked for references, I did. So the final change was to prefix each user prompt as well:

let response = await session.prompt(`When answering this question, try to include the page number: ${q}`);

This seemed to do it:

This is not always accurate. For example, when I asked: "what can you tell me about adobe confidential data?", which is covered in detail on page 3, the result focused on page 2. The confidential data classification is introduced on page 2, but is covered more in depth on page 3. Maybe improving the page formatting in the prompt would help here, but I'm happy with this demo so far. (If you want a copy of the PDF I tested with, you can find it here.)

As I said yesterday, give these demos a spin and let me know what you think!

Summarizing PDFs with On-Device AI

Raymond Camden — Wed, 28 Jan 2026 18:00:00 +0000

You can take the man out of the PDFs, but you can't take the PDFs out of the man. Ok, I'm not sure that exactly makes sense, but with a couple years in me of working with PDFs, I find myself using them quite often with my AI demos. For today, I'm going to demonstrate something that's been on my mind in a while - doing summarizing of PDFs completely in the browser, with Chrome's on-device AI. Unlike the Prompt API, summarization has been released since Chrome 138, so most likely those of you on Chrome can run these demos without problem. (You can see more about the AI API statuses if you're curious.)

Getting PDF Text - Client-Side

There's plenty of options for getting PDF text on the server-side, either via open source libraries or APIs. For this demo I made use of PDF.js. This is an open source library sponsored by Mozilla that's been around for a while. It supports parsing and rendering PDFs, but for my use-case, I just needed to parse it. The code for that part is actually really simple, once I used Google Gemini to help me with it.

First I added the library CDN: https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js

Next, I followed the advice from Gemini to specify a worker source for performance reasons:

pdfjsLib.GlobalWorkerOptions.workerSrc = 'https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.worker.min.js';

This was suggested by Gemini, but I did followup research and confirmed this makes sense.

For the actual PDF parsing, I based it on an file input change event, like so:

document.querySelector('#pdf-upload').addEventListener('change', async (e) => {
    const file = e.target.files[0];
    if (!file) return;

    const arrayBuffer = await file.arrayBuffer();

    const pdf = await pdfjsLib.getDocument(arrayBuffer).promise;

    let fullText = '';

    for (let i = 1; i <= pdf.numPages; i++) {
        const page = await pdf.getPage(i);

        const textContent = await page.getTextContent();

        // Note: 'item.str' is the raw string. 'item.hasEOL' can be used for formatting.
        const pageText = textContent.items.map(item => item.str).join(' ');

        fullText += pageText;
    }

});

That's pretty much it, and in my testing, this worked really fast, like surprisingly fast. Note that you can get more than just the text of course. My final code gets the title as well so I can render that. Check the PDF.js docs for a full understanding of everything possible.

The Demo

Ok, so given that I can get the PDF text easily enough, it was now time to use the Summarizer API. I've blogged about Chrome AI many times now but as a reminder, the process generally looks like so:

First do feature detection to see if the API is available at all.
Then see if the API is available, this can return unavailable, which means the device isn't able to use the API for a few different reasons, available which means it is good to go, or downloadable which means the model will be downloaded. This can take some time and you should let the user know.
Finally, make an instance of the model. Once you have that, you can run summarize() and Bob's your uncle.

First, my demo has a bit of HTML, both for the input field and a place to provide output:

<h2>PDF Summarization</h2>
<p>
Select a PDF and Chrome AI will be used to summarize it. 
<input type="file" id="pdf-upload" accept=".pdf" />
</p>
<div id="output"></div>

Now, the JavaScript:

pdfjsLib.GlobalWorkerOptions.workerSrc = 'https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.worker.min.js';

document.addEventListener('DOMContentLoaded', init, false);

let $output;

async function init() {

    // do an early check
    if('Summarizer' in window) {
        // You can haz summary
        let available = (await window.Summarizer.availability());
        console.log('available?', available);
        if (available === 'unavailable') {
            // The Summarizer API isn't usable.
            alert("Sorry, this demo will not work for you.");
            return;
        }
    }

    $output = document.querySelector('#output');

    document.querySelector('#pdf-upload').addEventListener('change', async (e) => {
        $output.innerHTML = '';
        const file = e.target.files[0];
        if (!file) return;

        const arrayBuffer = await file.arrayBuffer();

        const pdf = await pdfjsLib.getDocument(arrayBuffer).promise;

        let fullText = '';

        for (let i = 1; i <= pdf.numPages; i++) {
            const page = await pdf.getPage(i);

            const textContent = await page.getTextContent();

            // Note: 'item.str' is the raw string. 'item.hasEOL' can be used for formatting.
            const pageText = textContent.items.map(item => item.str).join(' ');

            fullText += pageText;
        }

        const meta = await pdf.getMetadata();
        console.log('meta?', meta);
        doSummary(fullText, meta.info.Title || 'No Title Found');

    });

}

async function doSummary(text, title) {
        $output.innerHTML = "<i>PDF text extracted, working on the summary.";

        summarizer = await window.Summarizer.create({
                monitor(m) {
                    m.addEventListener("downloadprogress", e => {
                        console.log(`Downloaded ${e.loaded * 100}%`);
                        /*
                        why this? the download event _always_ runs at
                        least once, so this prevents the msg showing up
                        when its already done. I've seen it report 0 and 1
                        in this case, so we skip both
                        */
                        if(e.loaded === 0 || e.loaded === 1) return;
                        $output.innerHTML = `Downloading the Summary model, currently at ${Math.floor(e.loaded * 100)}%`;
                });
            }
    });

    try {
        let summary = await summarizer.summarize(text);
        $output.innerHTML = `<h3>Summary for ${title}</h3>${marked.parse(summary)}`;
    } catch(e) {
        if(e.name === 'QuotaExceededError') {
            $output.innerHTML = 'Unfortunately this PDF was too large!';
        } else {
            $output.innerHTML = `Some other error was thrown: ${e}`;
        }
        console.log(e);
    }

}

The first half is what I've already covered - getting the text of a PDF file. The only difference is that I added a call to get the metadata of the PDF so I could possibly render the title as well.

The second half, doSummary, is where the AI work is done. I create the summary object (using default values, the API actually supports multiple different styles of summarization) and then attempt to summarize.

Now - here comes the biggest issue. Right now the model can't summarize large PDFs. You can see I'm handling that with a specific catch handler that makes this clear. There is absolutely a way around this! One classic way is to do summaries of summaries. Given that PDF.js returns text in pages, I could keep an array of pages, and then do batches of summaries, let's say 10 pages at a time. 10 is a guess and given that a PDF page may have a lot or a little text, it's really something you would need to test and see what works best. For this demo though I kept it simple - just report an error.

You can play with this below, but if you're curious as to the results, here's a few test results. First, I tried a PDF version of my resume (note that I've not updated it yet to include Webflow, will do that soon!).

That's pretty darn accurate I'd say. Want to try it yourself? Check it out below (note - this CodePen will not work on Dev.to - click to view it in a new tab):

This example just focused on the Summary API, but you could absolutely try other APIs as well. For example, the Prompt API would let you literally ask questions of the PDF (and I may build this), something that I believe Acrobat charges for. (Ahem, no shade being thrown, honest. Mostly.) You could also do language detection and translation.

My buddy on the Chrome team Thomas Steiner has some great examples of this: https://chrome.dev/web-ai-demos/document-translator/

Let me know what you think!

Convert Office Docs to PDFs Automatically with Foxit PDF Services API

Raymond Camden — Thu, 14 Aug 2025 20:17:21 +0000

With our REST APIs, it is now possible for any developer to set up an integration and document workflow using their language of choice. But what about workflow automations? Luckily, this is even simpler (of course, depending on platform) as you can rely on the workflow service to handle a lot the heavy lifting of whatever automation needs you may have. In this blog post, I'm going to demonstrate a workflow making use of Pipedream. Pipedream is a low-code platform that lets you build flexible workflows by piecing together various small atomic steps. It's been a favorite of mine for some time now, and I absolutely recommend it. But note that what I'll be showing here today could absolutely be done on other platforms, like n8n.

Want the televised version? Catch the video below:

Our Office Document to PDF Workflow

Our workflow is based on Dropbox folders and handles automatic conversion of Office docs to PDFs. To support that, it does the following:

Listen for new files in a Dropbox folder
Do a quick sanity check (is it in the input subdirectory and an Office file)
Download the file to Pipedream
Send it to Foxit via the Upload API
Kick off the appropriate conversion based on the Office type
Check status via the Status API
When done, download the result to Pipedream
And finally, push it up to Dropbox in an output subdirectory

Here's a nice graphical representation of this workflow:

Before we get into the code, note that workflow platforms like Pipedream are incredibly flexible. When I build workflows with platforms like this I try to make each step as atomic, and focused as possible. I could absolutely have built a shorter, more compact version of this workflow. However, having it broken out like this makes it easier to copy and modify going forward (which is exactly how this one came about, it was based on a simpler, earlier version).

Ok, let's break it down, step-by-step.

Getting Triggered

In Pipedream, workflows begin with a trigger. While there are many options for this, my workflow uses a "New File From Dropbox" trigger. I logged into Dropbox via Pipedream so it had access to my account. I then specified a top level folder, "Foxit", for the integration. Additionally, there are two more important settings:

Recursive - this tells the trigger to file for any new file under the root directory, "Foxit". My Dropbox Foxit folder has both an input and output directory.
Include Link - this tells Pipedream to ensure we get a link to the new file. This is required to download it later.

Filtering the Document Flow

The next two steps are focused on filtering and stopping the workflow, if necessary. The first, end_if_output, is a built-in Pipedream step that lets me provide a condition for the workflow to end. First, I'll check the path value from the trigger (the path of the new file) and if it contains "output", this means it's a new file in the output directory and the workflow should not run.

The next filter is a code step that handles two tasks. First, it checks whether the new file is a supported Office type—.docx, .xlsx, or .pptx—using our APIs. If the extension isn’t one of these, the workflow ends programmatically.

Later in the workflow, I’ll also need that same extension to route the request to the correct endpoint. So the code handles both: validation and preservation of the extension.

import os 

def handler(pd: "pipedream"):
  base, extension = os.path.splitext(pd.steps['trigger']['event']['name'])

  if extension == ".docx":
    api = "/pdf-services/api/documents/create/pdf-from-word"
  elif extension == ".xlsx":
    api = "/pdf-services/api/documents/create/pdf-from-excel"
  elif extension == ".pptx":
    api = "/pdf-services/api/documents/create/pdf-from-ppt"
  else:
    return pd.flow.exit(f"Exiting workflow due to unknow extension: {extension}.")

  return { "api":api }

As you can see, if the extension isn't valid, I'm exiting the workflow using pd.flow.exit (while also logging out a proper message, which I can check later via the Pipedream UI). I also return the right endpoint if a supported extension was used. This will be useful later in the flow.

Download and Upload API Data

The next two steps are primarily about moving data from the input source (Dropbox) to our API (Foxit).

The first step, download_to_tmp, uses a simple Python script to transfer the Dropbox file into the /tmp directory for use in the workflow

import requests

def handler(pd: "pipedream"):
    download_url = pd.steps["trigger"]["event"]["link"]
    file_path = f"/tmp/{pd.steps['trigger']['event']['name']}"

    with requests.get(download_url, stream=True) as response:
      response.raise_for_status()
      with open(file_path, "wb") as file:
          for chunk in response.iter_content(chunk_size=8192):
            file.write(chunk)

    return file_path

Notice at the end that I return the path I used in Pipedream. This action then leads directly into the next step of uploading to Foxit via the Upload API:

import os 
import requests 

def handler(pd: "pipedream"):
  clientid = os.environ.get('FOXIT_CLIENT_ID')
  secret = os.environ.get('FOXIT_CLIENT_SECRET')
  HOST = os.environ.get('FOXIT_HOST')

  headers = {
    "client_id":clientid,
    "client_secret":secret
  }

  with open(pd.steps['download_to_tmp']['$return_value'], 'rb') as f:
    files = {'file': (pd.steps['download_to_tmp']['$return_value'], f)}

    request = requests.post(f"{HOST}/pdf-services/api/documents/upload", files=files, headers=headers)

    return request.json()

The result of this will be a documentId value that looks like so:

{
  "documentId": "<string>"
}

Pipedream lets you define environment variables and I've made use of them for my Foxit credentials and host. Grab your own free credentials here!

Converting the Document Using the Foxit API

The next step will actually kick off the conversion. My workflow supports three different input types (Word, PowerPoint, and Excel). These map to three API endpoints. But remember that earlier we sniffed the extension of our input and set the endpoint there. Since all three APIs work the same, that's literally all we need to do - hit the endpoint and pass the document value from the previous step.

import os 
import requests 

def handler(pd: "pipedream"):

  clientid = os.environ.get('FOXIT_CLIENT_ID')
  secret = os.environ.get('FOXIT_CLIENT_SECRET')
  HOST = os.environ.get('FOXIT_HOST')

  headers = {
    "client_id":clientid,
    "client_secret":secret,
    "Content-Type":"application/json"
  }

  body = {
    "documentId": pd.steps['upload_to_foxit']['$return_value']['documentId']
  }

  api = pd.steps['extension_check']['$return_value']['api']

  print(f"{HOST}{api}")
  request = requests.post(f"{HOST}{api}", json=body, headers=headers)
  return request.json()

The result of this call, and nearly all of the Foxit APIs, will be a task:

{
  "taskId": "<string>"
}

Checking Your Document API Status

The next step is one that may take a few seconds - checking the job status. Foxit's endpoint returns a value like so:

{
  "taskId": "<string>",
  "status": "<string>",
  "progress": "<int32>",
  "resultDocumentId": "<string>",
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

To use this, I just hit the API, check for status, and if it's not done, wait five seconds and call it again. Here's the Python code for this:

import os 
import requests 
from time import sleep 

def handler(pd: "pipedream"):

  clientid = os.environ.get('FOXIT_CLIENT_ID')
  secret = os.environ.get('FOXIT_CLIENT_SECRET')
  HOST = os.environ.get('FOXIT_HOST')

  headers = {
    "client_id":clientid,
    "client_secret":secret,
    "Content-Type":"application/json"
  }

  done = False
  while done is False:

    request = requests.get(f"{HOST}/pdf-services/api/tasks/{pd.steps['create_conversion_job']['$return_value']['taskId']}", headers=headers)
    status = request.json()
    if status["status"] == "COMPLETED":
      done = True
      return status
    elif status["status"] == "FAILED":
      print("Failure. Here is the last status:")
      print(status)
      return pd.flow.exit("Failure in job")
    else:
      print(f"Current status, {status['status']}, percentage: {status['progress']}")
      sleep(5)

As shown, errors are simply logged by default—but you could enhance this by adding notifications, such as emailing an admin, sending a text message, or other alerts.

On success, the final output is passed along, including the key value we care about: resultDocumentId.

Download and Upload - Again

Ok, if the workflow has gotten this far, it's time to finish the process. The next step handles downloading the result from Foxit using the download endpoint:

import requests
import os

def handler(pd: "pipedream"):
  clientid = os.environ.get('FOXIT_CLIENT_ID')
  secret = os.environ.get('FOXIT_CLIENT_SECRET')
  HOST = os.environ.get('FOXIT_HOST')

  headers = {
    "client_id":clientid,
    "client_secret":secret,
  }

  # Given a file of input.docx, we need to use input.pdf
  base_name, _ = os.path.splitext(pd.steps['trigger']['event']['name'])
  path = f"/tmp/{base_name}.pdf"
  print(path) 

  with open(path, "wb") as output:

    bits = requests.get(f"{HOST}/pdf-services/api/documents/{pd.steps['check_job']['$return_value']['resultDocumentId']}/download", stream=True, headers=headers).content 
    output.write(bits)

    return {
      "filename":f"{base_name}.pdf",
      "path":path
    }

Note that I'm using the base name of the input, which is basically the filename minus the extension. So for example, input.docx will become input, which I then slap a pdf extension on to create the filename used to store locally to Pipedream.

Finally, I push the file back up to Dropbox, but for this, I can use a built-in Pipedream step that can upload to Dropbox. Here's how I configured it:

Path: Once again, Foxit
File Name: This one's a bit more complex, I want to store the value in the output subdirectory, and ensure the filename is dynamic. Pipedream lets you mix and match hard-coded values and expressions. I used this to enable that: output/{{steps.download_result_to_tmp.$return_value.filename}}. In this expression the portion inside the double bracket will be dynamic based on the PDF file generated previously.
File Path: This is an expression as well, pointing to where I saved the file previously: {{steps.download_result_to_tmp.$return_value.path}}
Mode: Finally, the mode attribute specifies what to do on a conflict. This setting will be based on whatever your particular workflow needs are, but for my workflow, I simply told Dropbox to overwrite the existing file.

Here's how that step looks configured in Pipedream:

Conclusion

Believe it or not, that's the entire workflow. Once enabled, it runs in the back ground and I can simply place any files into my Dropbox folder and my Office docs will be automatically converted. What's next? Definitely get your own free credentials and check out the docs to get started. If you run into any trouble at all, hit is up on the forums and we'll be glad to help!

Embed Secure eSignatures into Your App with Foxit API

Raymond Camden — Tue, 12 Aug 2025 18:28:18 +0000

Foxit eSign is an electronic signature solution that enables individuals and businesses to securely sign, send, and manage documents online. It streamlines the document signing process by allowing users to create legally binding eSignatures, prepare forms, and track document status in real time. With features like reusable templates, automated workflows, and audit trails, it enhances productivity and reduces the need for manual paperwork.

At the simplest level, a user can log into the eSign dashboard and handle 100% of their signing needs. So for example, they can upload a Microsoft Word template and then drag and drop fields that will be used during the signing process. I did this with a simple Word document. After uploading, I was given an easy to use editor to drag and drop fields:

In the screen shot above, I've added three fields to my document. The first is a date field. The second is for the signers name. The last field is the actual signature spot. Each of these fields have many options, and your own documents could have far more (or heck, even less) fields. The point is - you're allowed to design these forms to meet whatever need you may have. Also note that you can do all of this directly within Word, as well. Our docs show how to add fields directly into Word that will become enabled in the signing process.

Once you've got your template in a nice place, you can initiate the signing process right from the app. The dashboard also gives you a full history and audit trail of that process (have they signed yet? when did they do it? who signed?) which is handy. But, of course, you're here because you're a developer, and you're probably asking yourself - can we automate this? The answer? Of course!

If you would rather watch an introduction to the API, enjoy the video below!

eSign Via API

Before we begin digging into the APIs, be sure to take a quick look at the API Reference. As I've stated a few times, the signing process itself can be incredibly complex. For example, there may be 2, 3, or more people who need to sign a document, and in a particular order. Also, remember that I shared that the template process of adding fields and such can be done entirely in Word itself. This is to say that our look here is going to focus on a simple example of signing. But there's nothing to stop the creation of more advanced, flexible workflows.

The first step in any API usage will be authentication. When you have an eSign account with API access, you'll be given a client_id and client_secret value, both of which need to be exchanged for an access token at the appropriate endpoint. Here's a simple example of this with Python:

CLIENT_ID = os.environ.get("CLIENT_ID")
CLIENT_SECRET = os.environ.get("CLIENT_SECRET")

def getAccessToken(id, secret):
    url = "https://na1.foxitesign.foxit.com/api/oauth2/access_token"
    payload=f"client_id={id}&client_secret={secret}&grant_type=client_credentials&scope=read-write"
    headers = {
    'Content-Type': 'application/x-www-form-urlencoded'
    }

    response = requests.request("POST", url, headers=headers, data=payload)

    token = (response.json())["access_token"]
    return token

access_token = getAccessToken(CLIENT_ID, CLIENT_SECRET)

All the rest of the demos will make use of this method, and at the end of this post I'll share GitHub links for the source.

Kicking Off the Signing API Process

Now that we've authenticated with the API, our code can start doing... well, everything. The first thing we will add is a signing process with the template I showed above. From the dashboard itself I was able to make note of the template ID, 392230, but note that there's APIs for working with templates where that could be done via code as well.

To start the signing process, we can use the Create Envelope from Template endpoint. You can think of an envelope as a set of documents a user has to sign. For our demo, it's one, but you can include multiple documents. If you look at the API reference example, you'll see a large input body. As I've said, and will probably keep saying, the electronic signing process can be quite complex. For our simple demo, however, we just need to know the name of the person we're asking to sign the document and their email address. I whipped up this simple Python utility to enable that:

def sendForSigning(template_id, first_name, last_name, email, token):
    url = "https://na1.foxitesign.foxit.com/api/templates/createFolder"
    body = {
        "folderName":"Sending for Signing",
        "templateIds":[template_id],
        "parties":[
        {
            "permission":"FILL_FIELDS_AND_SIGN",
            "firstName":first_name,
            "lastName":last_name,
            "emailId":email,
            "sequence":1
        }
        ],
        "senderEmail":"raymond_camden@foxitsoftware.com"
    }

    headers = {
        'Authorization': f'Bearer {token}',
    }

    response = requests.request("POST", url, headers=headers, json=body)
    return response.json()

Make note that parties is an array of one person, as only one person is needed in the process. Also note that permission is required as it defines the role that person will play in the party.

Calling this method is simple:

# Hard coded template id
tid = "392230"

sendForSigningResponse = sendForSigning(tid, "Raymond", "Camden", "raymondcamden@gmail.com", access_token)

The result of this call is a large set of data. But for now, we can live with just the ID of the evenlope created:

envelopeId = sendForSigningResponse['folder']['folderId']
print(f"ID of the envelope created: {envelopeId}")

** Note: You'll see 'folder' referenced in the API endpoints and results, but the eSign API is migrating to the 'envelope' term instead. **

A few seconds after running this code, the email showed up in my account:

Obviously at this point, I could sign it... but what if I didn't?

Sending out Electronic Reminders

One way to help ensure your important documents get signed is to remind the people who need to sign that - well, they need actually sign the document. To enable this, we can use the Send Signature Reminder endpoint. All it needs is the ID of the envelope created earlier (and again, see my note about envelope vs folder):

def sendReminder(envelope_id, token):   
    url = "https://na1.foxitesign.foxit.com/api/folders/signaturereminder"
    body = {
        "folderId":envelope_id
    }
    headers = {
        'Authorization': f'Bearer {token}',
    }

    response = requests.request("POST", url, headers=headers, json=body)
    result = response.json()
    return result

Calling this just required the access token and ID:

access_token = getAccessToken(CLIENT_ID, CLIENT_SECRET)
result = sendReminder(envelope_id, access_token)

As you can expect, this sends an email reminder:

Ok, But Did They Sign Their Document Yet??

So far, you've seen an example of sending out a document for signing as well as politely reminding the person to do their job. How can you tell if they've completed the process? For this, we can turn to the Get Envelope Details endpoint. It's also rather simple in that it just needs the envelope ID value from before. Once again, here's a wrapper to that API built in Python:

def getStatus(envelope_id, token):  
    url = f"https://na1.foxitesign.foxit.com/api/folders/myfolder?folderId={envelope_id}"

    headers = {
        'Authorization': f'Bearer {token}',
    }

    response = requests.request("GET", url, headers=headers)
    result = response.json()
    return result

And the call:

result = getStatus(envelope_id, access_token)

print(f"Envelope status: {result['folder']['folderStatus']}")

While there's a lot of important information returned, we can output just the status to see at a high level what state the process is currently in.

Given the example I've shown so far, the status of the envelope is SHARED. Let's actually click the link:

In the screenshot above, notice how the date is already filled to today's data. Also note that name was prefilled as eSign knows who it was sent to. All I need to do is click and sign. Once I do, the same code above will now return EXECUTED.

Next Steps

Wondering where to go next? If you are completely new to eSign, check out the main homepage for an introduction. You can also check out the Foxit eSign YouTube channel for lots of good video content on the service. If you want a copy of the code I showed in this post, you can find all three examples here: https://github.com/foxitsoftware/developerapidemos/tree/main/esign. Finally, don't forget to visit our forums and bring your questions!

How to Chain PDF Actions with Foxit

Raymond Camden — Fri, 08 Aug 2025 17:55:03 +0000

When working with Foxit's PDF Services, you'll remember that the basic flow involves:

Uploading your document to Foxit to get an ID
Starting a job
Checking the job
Downloading the result

This is handy for one off operations, for example, converting a Word document to PDF, but what if you need to do two or more operations? Luckily this is easy enough by simply handing off one result to the next. Let's take a look at how this can work.

Credentials

Remember, to start developing and testing with the APIs, you'll need to head over to our developer portal and grab a set of free credentials. This will include a client ID and secret values you’ll need to make use of the API.

If you would rather watch a video (or why not both?) – you can watch the walkthrough below:

Creating a Document Optimization Workflow

To demonstrate how to chain different operations together, we're going to build a basic document optimization workflow that will:

Compress the document by reducing image resolution and other compression algorithims.
Linearize the document to make it better viewable on the web.

Given the basic flow described above, you may be tempted to do this:

Upload the PDF
Kick off the Compress job
Check until done
Download the compressed PDF
Upload the PDF
Kick off the Linearize job
Check until done
Download the compressed and linearized PDF

This wouldn’t require much code, but we can simplify the process by using the result of the compress job—once it's complete—as the source for the linearize job. This gives us the following streamlined flow:

Upload the PDF
Kick off the Compress job
Check until done
Kick off the Linearize job
Check until done
Download the compressed and linearized PDF

Less is better! Alright, let's look at the code.

First, here's the typical code used to bring in our credentials from the environment, and define the Upload job:

import os
import requests
import sys 
from time import sleep 

CLIENT_ID = os.environ.get('CLIENT_ID')
CLIENT_SECRET = os.environ.get('CLIENT_SECRET')
HOST = os.environ.get('HOST')

def uploadDoc(path, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret
    }

    with open(path, 'rb') as f:
        files = {'file': f}

        request = requests.post(f"{HOST}/pdf-services/api/documents/upload", files=files, headers=headers)
        return request.json()

Next, here are two utility methods to wrap calling Compress and Linearize:

def compressPDF(doc, level, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret,
        "Content-Type":"application/json"
    }

    body = {
        "documentId":doc,
        "compressionLevel":level    
    }

    request = requests.post(f"{HOST}/pdf-services/api/documents/modify/pdf-compress", json=body, headers=headers)
    return request.json()

def linearizePDF(doc, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret,
        "Content-Type":"application/json"
    }

    body = {
        "documentId":doc
    }

    request = requests.post(f"{HOST}/pdf-services/api/documents/optimize/pdf-linearize", json=body, headers=headers)
    return request.json()

Note that the compressPDF method takes a required level argument that defines the level of compression. From the docs, we can see the supported values are LOW, MEDIUM, and HIGH.

Now, two more utility methods - one that checks the task returned by the API operations above and one that downloads a result to the file system:

def checkTask(task, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret,
        "Content-Type":"application/json"
    }

    done = False
    while done is False:

        request = requests.get(f"{HOST}/pdf-services/api/tasks/{task}", headers=headers)
        status = request.json()
        if status["status"] == "COMPLETED":
            done = True
            # really only need resultDocumentId, will address later
            return status
        elif status["status"] == "FAILED":
            print("Failure. Here is the last status:")
            print(status)
            sys.exit()
        else:
            print(f"Current status, {status['status']}, percentage: {status['progress']}")
            sleep(5)

def downloadResult(doc, path, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret
    }

    with open(path, "wb") as output:

        bits = requests.get(f"{HOST}/pdf-services/api/documents/{doc}/download", stream=True, headers=headers).content 
        output.write(bits)

Alright, so that's all the utility methods and setup. Time to actually do what we said we would:

input = "../../inputfiles/input.pdf"
print(f"File size of input: {os.path.getsize(input)}")
doc = uploadDoc(input, CLIENT_ID, CLIENT_SECRET)
print(f"Uploaded doc to Foxit, id is {doc['documentId']}")

task = compressPDF(doc["documentId"], "HIGH", CLIENT_ID, CLIENT_SECRET)
print(f"Created task, id is {task['taskId']}")

result = checkTask(task["taskId"], CLIENT_ID, CLIENT_SECRET)
print("Done converting to PDF. Now doing linearize.")

task = linearizePDF(result["resultDocumentId"], CLIENT_ID, CLIENT_SECRET)
print(f"Created task, id is {task['taskId']}")

result = checkTask(task["taskId"], CLIENT_ID, CLIENT_SECRET)
print("Done with linearize task.")

output = "../../output/really_optimized.pdf"
downloadResult(result["resultDocumentId"], output , CLIENT_ID, CLIENT_SECRET)
print(f"Done and saved to: {output}.")
print(f"File size of output: {os.path.getsize(output)}")

This code matches the flow described above, with the exception of outputting the size as a handy way to see the result of the compression call. When run, the initial size is 355994 bytes and the final size is 16733. That's a great saving! You should, however, ensure the result matches the quality you desire and if not, consider reducing the level of compression. Linearize doesn't impact the file size, but as stated above will make it work nicer on the web.

For a complete listing, find the sample on our GitHub repo.

Next Steps

Obviously, you could do even more chaining based on the code above. For example, as part of your optimization flow, you could even split the PDF to return a 'sample' of a document that may be for sale. You could extract information to use for AI purposes and more. Dig more into our PDF Service APIs to get an idea and let us know what you build on our developer forums!

How to Extract Text from PDFs using Foxit’s REST APIs

Raymond Camden — Thu, 07 Aug 2025 15:43:24 +0000

PDFs are an excellent way to store information—they combine text, images, and more in a perfectly laid-out, eye-catching design that fulfills every marketer's wildest dreams. But sometimes you just need the text! There's a variety of reasons you may want to convert a rich PDF document into plain text:

For indexing in a search engine
To search documents for keywords
To pass to generative AI services for introspection

Let's take a look at the Extract API to see just how easy this is.

Start Here: Obtain Free Credentials to Use the Foxit API

Before we go any further, head over to our developer portal and grab a set of free credentials. This will include a client ID and secret values - you'll need both to make use of the API.

Foxit PDF API Workflow Overview with Python

The API follows the same format as the rest of our PDF Services in that you upload your input, kick off the job, check the job's status, and download the result. As we've covered this a few times now on the blog (see my introductory post, we'll skip over the details of uploading the document and loading in credentials. Here's the Python code we've demonstrated before showing this in action:

CLIENT_ID = os.environ.get('CLIENT_ID')
CLIENT_SECRET = os.environ.get('CLIENT_SECRET')
HOST = os.environ.get('HOST')

def uploadDoc(path, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret
    }

    with open(path, 'rb') as f:
        files = {'file': (path, f)}

        request = requests.post(f"{HOST}/pdf-services/api/documents/upload", files=files, headers=headers)
        return request.json()

doc = uploadDoc("../../inputfiles/input.pdf", CLIENT_ID, CLIENT_SECRET)
print(f"Uploaded pdf to Foxit, id is {doc['documentId']}")

Now let's get into the meat of the Extract API. The API takes three arguments:

The ID of the previously uploaded document.
The type of information to extract—either TEXT, IMAGE, or PAGE. In theory, it should be pretty obvious what these do, but just in case: TEXT returns the text contents of the PDF. IMAGE gives you a ZIP file of images from the PDF. PAGE returns a new PDF containing just the page you requested.
You can also pass in a page range, which can be a combo of specific pages and ranges. If you don’t include one, the entire PDF gets processed for extraction.

To make this simple to use, I've built a wrapper function that lets you pass these arguments:

def extractPDF(doc, type, id, secret, pageRange=None):

    headers = {
        "client_id":id,
        "client_secret":secret,
        "Content-Type":"application/json"
    }

    body = {
        "documentId":doc,
        "extractType":type
    }

    if pageRange:
        body["pageRange"] = pageRange 

    request = requests.post(f"{HOST}/pdf-services/api/documents/modify/pdf-extract", json=body, headers=headers)
    return request.json()

Literally, that's it. At this point, you get a task object back that - like with our other APIs - can be checked for completion, and once it’s done, the results can be downloaded. Since we're working with text, though, let's simplify and just grab the text as a variable:

def getResult(doc, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret
    }

    return requests.get(f"{HOST}/pdf-services/api/documents/{doc}/download", headers=headers).text

This utility method takes a document ID value and gets the textual content. Here's how that code looks:

doc = uploadDoc("../../inputfiles/input.pdf", CLIENT_ID, CLIENT_SECRET)
print(f"Uploaded pdf to Foxit, id is {doc['documentId']}")

task = extractPDF(doc["documentId"], "TEXT", CLIENT_ID, CLIENT_SECRET)
print(f"Created task, id is {task['taskId']}")

result = checkTask(task["taskId"], CLIENT_ID, CLIENT_SECRET)
print(f"Final result: {result}")

text = getResult(result["resultDocumentId"], CLIENT_ID, CLIENT_SECRET)
print(text)

You can see the entire script here, https://github.com/foxitsoftware/developerapidemos/blob/main/pdfservices/python/extractText.py. Running it will just give you a wall of text. Not terribly exciting. So, let's make it exciting!

Searching PDFs for Keywords

Let's iterate on the previous example for something that could be a bit more useful - given a set of input PDFs, extract the text from each and report if a certain keyword, or keywords are found. I'll start by gathering a list of PDFs from a source directory. But you could imagine this coming from new files in a cloud storage provider, attachments in new emails, and so forth:

# Get PDFs from our input directory
inputFiles = list(filter(lambda x: x.endswith('.pdf'), os.listdir('../../inputfiles')))

Now, I'll define a keyword. A more complex version of this would probably use a list of keywords, but we'll keep it simple for now:

# Keyword to match on: 
keyword = "Shakespeare"

And now to actually do the work. Remember, we've already defined our methods, so the only thing changing here is the code calling them:

for file in inputFiles:

    doc = uploadDoc(f"../../inputfiles/{file}", CLIENT_ID, CLIENT_SECRET)
    print(f"Uploaded pdf, {file}, to Foxit, id is {doc['documentId']}")

    task = extractPDF(doc["documentId"], "TEXT", CLIENT_ID, CLIENT_SECRET)
    result = checkTask(task["taskId"], CLIENT_ID, CLIENT_SECRET)

    text = getResult(result["resultDocumentId"], CLIENT_ID, CLIENT_SECRET)
    if keyword in text:
        print(f"\033[32mThe pdf, {file}, matched on our keyword: {keyword}\033[0m")
    else:
        print(f"The pdf, {file}, did not match on our keyword: {keyword}")

    print("")

Given my set of inputs, there's only one match. Here's the output I received:

You can find the complete source code for this on our GitHub repo.

What's Next?

The demo here is fairly simple, but you could imagine it being expanded to include things like automatic routing of PDFs with matching keywords, email alerts, and so forth. As a reminder, when working with any process like this, you can cache the result of the extraction. Imagine a scenario where the important keywords may change in the future. Your code could store the result of the text extract to the file system (perhaps with the same name as the PDF but using .txt as the extension instead) and simply skip calling our API when the cache exists. Our API will miss you, but that's ok.

If this all sounds exciting, be sure to check the docs for more information about the template language and API. Sign up for some free developer credentials and reach out on our developer forums with any questions.

Generate Dynamic PDFs from JSON using Foxit APIs

Raymond Camden — Fri, 01 Aug 2025 18:14:00 +0000

One of the more fascinating APIs in our library is the Document Generation API. This document generation API lets you create dynamic PDFs or Word documents using your own data as templates. That may sound simple – and the code you’re about to see is indeed simple – but the real power lies in how flexible Word can be as a template engine. This API could be used for:

Creating invoices
Creating offer letters
Creating dynamic agreements (which can integrate with our eSign API)

All of this is made available via a simple API and a “token language” you’ll use within Word to create your templates. Let’s take a look at how this is done.

Credentials

Before we go any further, head over to our developer portal and grab a set of free credentials. This will include a client ID and secret values – you’ll need both to make use of the API.

Don’t want to read all of this? You can also follow along by video:

Using the API

The Document Generation API flow is a bit different from our PDF Services APIs in that the execution is synchronous. You don't need to upload your document beforehand or download a result result. You simply call the API (passing your data and template) and the result has your new PDF (or Word document). With it being this simple, let's get into the code.

Loading Credentials

My script begins by loading in the credentials and API root host via the environment:

CLIENT_ID = os.environ.get('CLIENT_ID')
CLIENT_SECRET = os.environ.get('CLIENT_SECRET')
HOST = os.environ.get('HOST')

As always, try to avoid hard coding credentials directly into your code.

Calling the API

The endpoint only requires you to pass the output format, your data, and a base64 version of your file. "Your data" can be almost anything you like—though it should start as an object (i.e., a dictionary in Python with key/value pairs). Beneath that, anything goes: strings, numbers, arrays of objects, and so on.

Here's a Python wrapper showing this in action:

def docGen(doc, data, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret
    }

    body = {
        "outputFormat":"pdf",
        "documentValues": data,  
        "base64FileString":doc
    }

    request = requests.post(f"{HOST}/document-generation/api/GenerateDocumentBase64", json=body, headers=headers)
    return request.json()

And here's an example calling it:

with open('../../inputfiles/docgen_sample.docx', 'rb') as file:
    bd = file.read()
    b64 = base64.b64encode(bd).decode('utf-8')

data = {
    "name":"Raymond Camden", 
    "food": "sushi",
    "favoriteMovie": "Star Wars",
    "cats": [
        {"name":"Elise", "gender":"female", "age":14 },
        {"name":"Luna", "gender":"female", "age":13 },
        {"name":"Crackers", "gender":"male", "age":13 },
        {"name":"Gracie", "gender":"female", "age":12 },
        {"name":"Pig", "gender":"female", "age":10 },
        {"name":"Zelda", "gender":"female", "age":2 },
        {"name":"Wednesday", "gender":"female", "age":1 },
    ],
}

result = docGen(b64, data, CLIENT_ID, CLIENT_SECRET)

You'll note here that my data is hard-coded. In a real application, this would typically be dynamic—read from the file system, queried from a database, or sourced from any other location.

The result object contains a message representing the success or failure of the operation, the file extension for the result, and the base64 representation of the result. Most likely you'll always be outputting PDFs, so here's a simple bit of code that stores the result:

with open('../../output/docgen1.pdf', 'wb') as file:
    file.write(binary_data)
    print('Done and stored to ../../output/docgen1.pdf')

There's a bit more to the API than I've shown here so be sure to check the docs, but now it's time for the real star of this API, Word

Using Word as a Template

I've probably used Microsoft Word for longer than you've been alive and I've never really thought much about it. But when you begin to think of a simple Word document as a template, all of a sudden the possibilities begin to excite you. In our Document Generation API, the template system works via simple "tokens" in your document marked by opening and closing double brackets.

Consider this block of text:

See how name is surrounded by double brackets? And food and favoriteMovie? When this template is sent to the API along with the corresponding values, those tokens are replaced dynamically. In the screenshot, notice how favoriteMovie is bolded. That's fine. You can use any formatting, styling, or layout options you wish.

That's one example, but you also get some built-in values as well. For example, including today as a token will insert the current date, and can be paired with date formatting to specify how the date looks:

Remember the array of cats from earlier? You can use that to create a table in Word like this:

Notice that I've used two new tags here, TableStart and TableEnd, both of which reference the array, cats. Then in my table cells, I refer to the values from that array. Again, the color you see here is completely arbitrary and was me making use of the entirety of my Word design skills.

Here's the template as a whole to show you everything in context:

The Result

Given the code shown above with those values, and given the Word template just shared, once passed to the API, the following PDF is created:

Ready to Try?

If this looks cool, be sure to check the docs for more information about the template language and API. Sign up for some free developer credentials and reach out on our developer forums with any questions.

Want the code? You can find it on GitHub. If you are more a Node person, check out that version on GitHub.

Take Foxit's New PDF APIs for a Spin

Raymond Camden — Wed, 09 Jul 2025 18:00:00 +0000

Back in May I announced my new role at Foxit as an API evangelist. At the time, I couldn't talk much about what I was working on (although the title kinda gives it away), but yesterday we launched our new offering and I can finally share some news about it, and even better, some code.

So, the TLDR is that we launched a new API offering and developer portal. These APIs are all related to document management and PDFs, so much like I was doing in my previous role at the company famous for subscription-based desktop apps, which is nice as I can bring my existing expertise to the table.

Our APIs fall into four basic categories:

PDF Services - a set of basic PDF manipulation APIs like converting to and from PDF, optimizing and so forth
Document Generation - APIs related to creating dynamic PDFs from a Word template
eSign - not new, but part of the new umbrella, APIs related to electronic signing
Embed - PDF embedding library for the web

We're still ironing out a few kinks, but there's going to be some rapid updates to the offerings. You can sign up to get credentials and there's a free tier, not trial, so you can absolutely kick the tires before you commit to buying anything. How about a quick example?

Converting to PDF

The simplest example is just converting an Office document to PDF. The PDF Services tools all fall into a similar flow.

You upload your document.
You start a job.
You check the job.
You download the result.

Let's take this bit by bit. The Upload API requires your credentials and the binary bits of your data. Here's a Python wrapper for that:

def uploadDoc(path, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret
    }

    with open(path, 'rb') as f:
        files = {'file': f}

        request = requests.post(f"{HOST}/pdf-services/api/documents/upload", files=files, headers=headers)
        return request.json()

This returns a document ID value. Here's an example calling it, where CLIENT_ID and CLIENT_SECRET are my credentials loaded from environment variables:

doc = uploadDoc("../../inputfiles/input.docx", CLIENT_ID, CLIENT_SECRET)

Next, I'll call the Word to PDF endpoint, which only requires the document ID from the previous call. Again, I've got a Python wrapper:

def convertToPDF(doc, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret,
        "Content-Type":"application/json"
    }

    body = {
        "documentId":doc    
    }

    request = requests.post(f"{HOST}/pdf-services/api/documents/create/pdf-from-word", json=body, headers=headers)
    return request.json()

Here's how I call it using the previous result:

task = convertToPDF(doc["documentId"], CLIENT_ID, CLIENT_SECRET)

The result of the operation is a task ID that can then be checked to see how the process is going. This API returns a task object containing things like the status, progress, and so forth. Here's my implementation of a function that loops until the task is done or an error is thrown:

def checkTask(task, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret,
        "Content-Type":"application/json"
    }

    done = False
    while done is False:

        request = requests.get(f"{HOST}/pdf-services/api/tasks/{task}", headers=headers)
        status = request.json()
        if status["status"] == "COMPLETED":
            done = True
            # really only need resultDocumentId, will address later
            return status
        elif status["status"] == "FAILED":
            print("Failure. Here is the last status:")
            print(status)
            sys.exit()
        else:
            print(f"Current status, {status['status']}, percentage: {status['progress']}")

This could probably fancier. Anyway, here's the call:

result = checkTask(task["taskId"], CLIENT_ID, CLIENT_SECRET)

The final part, assuming everything works ok, is to use Download API to get the bits. Again, a wrapper:

def downloadResult(doc, path, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret
    }

    with open(path, "wb") as output:

        bits = requests.get(f"{HOST}/pdf-services/api/documents/{doc}/download", stream=True, headers=headers).content 
        output.write(bits)

And honestly, that's it. All of the rest of the PDF Services APIs are tiny variations of that flow. Here's the complete script just to show you the entirety of the operation:

import os
import requests
import sys 
from time import sleep 

CLIENT_ID = os.environ.get('CLIENT_ID')
CLIENT_SECRET = os.environ.get('CLIENT_SECRET')
HOST = os.environ.get('HOST')

def uploadDoc(path, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret
    }

    with open(path, 'rb') as f:
        files = {'file': f}

        request = requests.post(f"{HOST}/pdf-services/api/documents/upload", files=files, headers=headers)
        return request.json()

def convertToPDF(doc, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret,
        "Content-Type":"application/json"
    }

    body = {
        "documentId":doc    
    }

    request = requests.post(f"{HOST}/pdf-services/api/documents/create/pdf-from-word", json=body, headers=headers)
    return request.json()

def checkTask(task, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret,
        "Content-Type":"application/json"
    }

    done = False
    while done is False:

        request = requests.get(f"{HOST}/pdf-services/api/tasks/{task}", headers=headers)
        status = request.json()
        if status["status"] == "COMPLETED":
            done = True
            # really only need resultDocumentId, will address later
            return status
        elif status["status"] == "FAILED":
            print("Failure. Here is the last status:")
            print(status)
            sys.exit()
        else:
            print(f"Current status, {status['status']}, percentage: {status['progress']}")
            sleep(5)

def downloadResult(doc, path, id, secret):

    headers = {
        "client_id":id,
        "client_secret":secret
    }

    with open(path, "wb") as output:

        bits = requests.get(f"{HOST}/pdf-services/api/documents/{doc}/download", stream=True, headers=headers).content 
        output.write(bits)

doc = uploadDoc("../../inputfiles/input.docx", CLIENT_ID, CLIENT_SECRET)
print(f"Uploaded doc to Foxit, id is {doc['documentId']}")

task = convertToPDF(doc["documentId"], CLIENT_ID, CLIENT_SECRET)
print(f"Created task, id is {task['taskId']}")

result = checkTask(task["taskId"], CLIENT_ID, CLIENT_SECRET)
print(f"Final result: {result}")

downloadResult(result["resultDocumentId"], "../../output/input.pdf", CLIENT_ID, CLIENT_SECRET)
print("Done and saved to: ../../output/input.pdf")

What's Next?

As I said, we literally just launched this about twenty-four hours ago and we've got a lot more coming down the pipe. If this interests you, check out the site, and you can join our forum to ask questions. (Although feel free to leave a comment below.) I've got a live webinar coming up July 17th that you can register for to see these APIs in action, and I hope to see you there. We also have a developer blog launching soon on the main site, so I'll be doing most of my blogging there. Finally, I've got a repo, https://github.com/foxitsoftware/developerapidemos, of code demos supporting these APIs. I've got Python examples for everything, and Node examples for some things. Check it out.

Photo by Hoyoun Lee on Unsplash

Automating and Responding to Sentiment Analysis with Diffbot's Knowledge Graph

Raymond Camden — Wed, 12 Mar 2025 18:00:00 +0000

Diffbot's Knowledge Graph has a simple purpose - bring the sum total of all knowledge to your fingertips via a search that emphasis data and relations over a simple text based search engine experience. Sourced by the entire web, Knowledge Graph lets you perform complex queries against billions of data points instantly via a simple API. I decided to take a spin with their API and build a "relatively" simple tool - news analysis for a product run in on automated platform. Should be easy, right? Let's get to it. Note that the examples in this blog post assume you've gotten a free key from Diffbot. Be sure to do that before trying the samples.

Designing the Query

Before writing a line of code, I signed into Diffbot and opened up their visual search tool for Knowledge Graph. The tool lets you build queries visually or by hand. Queries are known as 'DQL' statements in Diffbot and are pretty simple to read even if you've never seen the syntax before.

From this tool, I started off by selecting an entity type. This is the high level type of data I want to search and can be one of many numerous options, from people to events to movies and investments. I selected "Article" as my intent is to find news that's speaking ill of my wonderful product. I then selected a "Filter By" option. While you can filter by any property in the entity type, I used tags.label as it's a more precise match than a simple text search. While a text filter does work, using tags.label gives a much better result by ensuring that the results are focused on my search, not just casually mentioning it. For my demo, I'll be looking for articles about "XBox".

I also used the "Sort by" value to show newest first and this hit search to see if my results made sense.

While my initial results didn't include any foreign language results, I knew I'd want to filter to results in English, so I next added a filter for language. Hitting the + sign by the current filter, I was then able to add language and en for English. Once again, I hit search:

Alright, so next, I want to filter to just negative results. Knowledge Graph Article entities have a sentiment score (you can see them in the search results) that go from -1 to most negative to 1 to most positive. Initially, I simply selected items with a sentiment less than or equal to 0.

Woot, getting there. As a final step, I knew this was going to be automated and filtered to 'recent' items, so I added one more filter, this time on date, selected after, and picked a date from a week ago.

At this point, the query looks good, so let's copy out the query value provided by the tool:

type:Article tags.label:"Xbox" language:"en" sentiment<=0 date>"2025-03-03" sortBy:date

Write the Code

Designing the query was really the hard part. For the code, I went to the Search docs. The examples are curl/HTTP based but quite easy to port to Python or any other language. Consider this sample:

import os 
import requests 
import json 
import urllib.parse

token = os.environ.get("db_token")

query = 'type:Article tags.label:"Xbox" language:"en" sentiment<=0 date>"2025-03-03" sortBy:date'

apiCall = f"https://kg.diffbot.com/kg/v3/dql?type=query&token={token}&query={urllib.parse.quote(query)}&size=25"

req = requests.get(apiCall)
results = json.loads(req.content)
print(f"Total results, {results['hits']}")

for result in results["data"]:
    print(result["entity"]["title"])
    print(result["entity"]["date"]["str"])
    print(result["entity"]["summary"])
    if "author" in result["entity"]:
        print(result["entity"]["author"])
    print(result["entity"]["siteName"])
    print(result["entity"]["pageUrl"])
    print(result["entity"]["sentiment"])

    print("------------------------------------")

Breaking this down - I began with my query from the visual tool. This then gets url encoded and passed to the API for Knowledge Graph. The only real new item there is the addition of size=25 to keep the result set to a sensible limit.

I call the API, print the total results found (from the hits result) and then iterate over each showing various bit of info from the result. Here's a few of the results:

Total results, 68
Xbox will release its first handheld gaming console this year, report claims
d2025-03-10T19:37
Windows Central expects the console to take advantage of the widgets on the Xbox Game Bar to let use...
Jacob Siegal
BGR
https://bgr.com/entertainment/xbox-will-release-its-first-handheld-gaming-console-this-year-report-claims/
0
------------------------------------
Rumour: Next-Gen Xbox a 'PC in Essence' - What Would That Mean for PlayStation?
d2025-03-10T19:00
Recent comments from Windows Central's executive editor Jez Corden have sparked discussion about whe...
Stephen Tailby
Push Square
https://www.pushsquare.com/news/2025/03/rumour-next-gen-xbox-a-pc-in-essence-what-would-that-mean-for-playstation
0
------------------------------------
Xbox handheld out this year and will go up against Nintendo Switch 2 says source
d2025-03-10T18:50
New rumours about Microsoft’s next gen plans suggests that there will be two Xbox handheld consoles ...
GameCentral
Metro
http://metro.co.uk/2025/03/10/xbox-handheld-this-year-will-go-nintendo-switch-2-says-source-22703266/
0

This works, but now let's make the date dynamic. I began importing from datetime:

from datetime import datetime, timedelta

I then generated a formatted date for last week:

today = datetime.now()
lastWeek = today + timedelta(days=-7)
fLastWeek = lastWeek.strftime("%Y-%m-%d")

And the last bit was to just include that date in my query:

query = f'type:Article tags.label:"Xbox" language:"en" sentiment<=0 date>{fLastWeek} sortBy:date'

You can see the complete source code for the initial version here and the final version here.

Building the Automation

Alright, time to automate this. For my automation, I'll be making use of Pipedream, an incredibly flexible workflow system I've used many times in the past. Here's the entire workflow with each part built out:

I began my workflow with a simple schedule based trigger, ie, when to run. This was somewhat arbitrary, but I picked weekly, on Sunday, at 1PM.

The next step, getArticles, handles the logic I demonstrated earlier, but now in a "Pipedream handler", which is the standard way to write code steps in Pipedream workflow.

import os 
import requests 
import json 
from datetime import datetime, timedelta
import urllib.parse

def handler(pd: "pipedream"):

  token = os.environ.get("db_token")

  today = datetime.now()
  lastWeek = today + timedelta(days=-7)
  fLastWeek = lastWeek.strftime("%Y-%m-%d")

  query = f'type:Article tags.label:"Xbox" language:"en" sentiment<=0 date>{fLastWeek} sortBy:date'

  apiCall = f"https://kg.diffbot.com/kg/v3/dql?type=query&token={token}&query={urllib.parse.quote(query)}&size=25"

  req = requests.get(apiCall)
  return json.loads(req.content)

The next step is simply a quick code step to end the workflow if no results are found:

def handler(pd: "pipedream"):

    if len(pd.steps["getArticles"]["$return_value"]["data"]) == 0:
      pd.flow.exit("No results")

Now I want to 'massage' the results a bit. I'm going to eventually email this to myself, so I built a step to format the results in a nice string:

from datetime import datetime

def handler(pd: "pipedream"):

  email = f"""
Negative Article Results:

Our search found {pd.steps["getArticles"]["$return_value"]["hits"]} results. Here are the top 25:
  """  

  for result in pd.steps["getArticles"]["$return_value"]["data"]:
    date = datetime.fromtimestamp(result["entity"]["date"]["timestamp"] / 1000)
    date_f = date.strftime("%Y-%m-%d")

    email += f"""
{result["entity"]["title"]}
Sentiment: {result["entity"]["sentiment"]}
Published: {date_f}
Link: {result["entity"]["pageUrl"]}
    """

  return email

Again, this is somewhat arbitrary in terms of what I thought important enough to include. You could definitely get more fancier, and even do things like, "on a really bad sentiment, add color, red flags, etc".

The final step was to simply email myself the results. Pipedream supports a "send an email to the account owner" step that will do just that, email me. If I were building this out for a client, I'd use one of the many Pipedream built-in steps for mail APIs.

Once run, I get a nice email with a list of articles and their sentiment:

If you choose to give Pipedream a spin, you can find my workflow here: https://github.com/cfjedimaster/General-Pipedream-AI-Stuff/tree/production/report-on-sentiment-p_gYCeNbG

What's Next?

This is just one example of using Diffbot's Knowledge Graph API, and as a reminder, articles are only one of the many different types of data you can search. Everything I did here was also done on a completely free account, so you can absolutely sign up and try it out yourself. I'm going to be digging into this more so let me know if you've got any questions!

Using Intl.DurationFormat for Localized Durations

Raymond Camden — Thu, 20 Feb 2025 18:00:00 +0000

Last year I had the opportunity to give a talk on the web platform's Intl specification. This made me incredibly happy because in preparing for the presentation, I discovered so many cool features and capabilities of the spec that I had no idea existed. Almost a year ago, I wrote up a blog post on Intl.RelativeTimeFormat, talking about how the API was easy to use, but perhaps a bit difficult when dealing when determining the best values to use when formatting dynamic dates. Today, I'm going to turn my attention to a related spec, Intl.DurationFormat

The Basics

The DurationFormat API works like so:

Given a locale (defaulting to the browser's locale)
Given a set of values representing time in different units (days, hours, etc)
Given a 'style' (long, short, narrow, and digital)
Report the duration in the desired locale

So for example, you can define a duration like so:

let duration = {
    days: 1, 
    hours: 5, 
    minutes: 32
}

I can then create a localized string for the duration like so:

let durationFormatter = new Intl.DurationFormat(navigator.language, 
                                                    { style: 'long' });

dur = durationFormatter.format(duration);

Which reports: 1 day, 5 hours, 32 minutes. Changing the locale to fr gives 1 jour, 5 heures et 32 minutes. That's with the long style, in short form you get 1 day, 5 hr, 32 min and 1 j, 5 h et 32 min. The narrow form is shorter while digital looks more like a digital clock and is better for durations less than a day. For example, if I just pass hours and minutes from the above input, I'd get: 5:32:00.

I built a quick demo showing three locales and all four styles that you can play with below.

Using DurationFormat with Real Data

Ok, so given the fact that you have to spell out the duration in units, how do you handle dynamic values? You can't just take the difference between two dates because if you pass a large number, the formatter takes it as is. So for example:

let duration = {
    minutes: 360
}

This will be reported as 360 minutes, not 6 hours. And to be fair, I feel that's the right behavior. It's formatting exactly what you told it too, and you may indeed want hours. Typically though folks want something a bit more 'condensed', ie, a total number of days lets say, then hours, minutes, and maybe seconds. As with my earlier post on relative time formatting, what you may want to use here depends on your data and your users.

Given that it's a bit up in the air, let's build a simplistic solution that attempts to break things down to year, months, weeks, days, hours, minutes, and seconds. The API can get more precise, but let's keep it at that. I'd also argue that any duration that may include years, or months, should probably not include weeks. I wouldn't tell someone it took three months, one week, and 2 days to do something. Well, heck, I don't know, maybe I would. But 'week' feels like something I'd not use in a larger duration. As with, well just about anything in our field, "it depends".

I began by adding two date fields:

<p>
<label for="date1">Date 1</label>
<input type="datetime-local" id="date1">
</p>

<p>
<label for="date2">Date 2</label>
<input type="datetime-local" id="date2">
</p>

This lets you, my dear reader, test with any values. I then added a dropdown the style:

<p>
<label for="style">Style:</label>
<select id="style">
    <option>long</option>
    <option>short</option>
    <option>narrow</option>
    <option>digital</option>
</select>
</p>

Beneath that is an empty div so I can show the result. Now let's turn to the code. First, I've got a bunch of code to check the DOM and register listeners. I want my code to run on any date or style change:

let $result = document.querySelector('#result');
let $style = document.querySelector('#style');
let $date1 = document.querySelector('#date1');
let $date2 = document.querySelector('#date2');

$date1.addEventListener('input', handleDuration, false);
$date2.addEventListener('input', handleDuration, false);
$style.addEventListener('change', handleDuration, false);

Next, I defined a set of constants that represent a duration by unit, ie, this is how big a year is versus an hour.

const MINUTE = 60 * 1000;
const HOUR = 60 * MINUTE;
const DAY = 24 * HOUR;
const WEEK = 7 * DAY;
// yeah, this is probably not perfect
const MONTH = 4 * WEEK;
const YEAR = MONTH * 12;

As the comment says, my MONTH logic there is absolutely not precise. Now let's look at the main logic thats run on changes to the form fields:

function handleDuration() {
    let d1 = $date1.value;
    let d2 = $date2.value;

    if(!d1 || !d2) return;

    $result.innerHTML = '';

    d1 = new Date(d1);
    d2 = new Date(d2);
    let diff = Math.abs(d1.getTime() - d2.getTime());
    console.log(d1, d2, 'diff', diff);

    let durationFormatter = new Intl.DurationFormat(navigator.language, 
                                                    { style: $style.value });

    let result = {
        years:0, 
        months:0,
        weeks:0,
        days:0,
        hours:0, 
        minutes:0,
        seconds:0
    };

    if(diff >= YEAR) {
        result.years = Math.floor(diff/YEAR);
        diff -= result.years * YEAR;
    } 

    if(diff >= MONTH) {
        result.months = Math.floor(diff/MONTH);
        diff -= result.months * MONTH;
    }

    if(diff >= WEEK) {
        result.weeks = Math.floor(diff/WEEK);
        diff -= result.weeks * WEEK;
    }

    if(diff >= DAY) {
        result.days = Math.floor(diff/DAY);
        diff -= result.days * DAY;
    }

    if(diff >= HOUR) {
        result.hours = Math.floor(diff/HOUR);
        diff -= result.hours * HOUR;
    }

    if(diff >= MINUTE) {
        result.minutes = Math.floor(diff/MINUTE);
        diff -= result.minutes * MINUTE;
    }

    if(diff > 0) result.seconds = diff / 1000;

    console.log('Result',result);

    let test1Result = durationFormatter.format(result);
    $result.innerHTML += `First Result: ${test1Result}`;
}

Basically my logic is - build up a structure for my duration based on seeing if my duration in miliseconds is bigger than a year, then a month, and so on. I can then pass my structure to the format function and render it. This seems to work ok, check it out below.

Obviously this could be overkill based on your data. For example, you may know for a fact that your durations will never be over an hour and your users will only care about durations in minutes, not seconds. Let me know if you've used this as I love to hear about Intl use in the wild!

Doing Evil Things with Generative AI and Recipes

Raymond Camden — Mon, 17 Feb 2025 18:00:00 +0000

Let me preface this blog post with a very clear and direct message. Do not do what I did. This is a bad use of generative AI. This is pure silliness with no real practical value whatsoever. This is a really, really, bad idea. But it was fun as hell, so here goes.

Last year I did two investigations into recipe parsing on the web. As we all know, most recipe sites go out of their way to make the actual recipe, you know, the thing you want to read, obfuscated and buried beneath a lot of stuff that is... well not the actual recipe. I first investigated JSON-LD and using that to parse web recipes into data: Scraping Recipes Using Node.js, Pipedream, and JSON-LD. This worked really well. I then followed it up with a more generic approach using Gemini and generative AI: Using Generative AI to Parse Web Pages into Data. This worked pretty good as well, and could be adapted for other purposes and types of content.

This came up in conversation with my friends today, and on a whim, because, this is how my 50+ year brain works, I wondered if it was possible to take a nice, filtered out recipe and go the other way? I.e., fill it with crap and obfuscate the simple recipe into a SEO-ridden nightmare and wall of text?

Yes, the answer is yes, you can. Let's get started, shall we?

I began by prototyping in Gemini's AI Studio. I used this as a system instruction:

You take a simple recipe and do your best to expand upon it with
superfluous text, including a made up story about the author's childhood
and why the recipe means so much to them. You should make the actual
recipe incredibly difficult to find.

I then took this recipe my buddy Scott shared with me:

Mississippi Pot Roast Recipe

Ingredients:

1 (3-pound) chuck roast
½ (12-ounce) jar pepperoncini peppers (with juice)
½ cup unsalted butter
1 (1-ounce) packet ranch dressing mix
1 (1-ounce) packet au jus gravy mix
Salt and pepper to taste

Instructions:

Place the chuck roast in the bottom of a slow cooker.
Sprinkle the ranch dressing mix and au jus gravy mix over the top of the roast.
Add the butter and pepperoncini peppers (with juice) on top.
Season with salt and pepper to taste.
Cover and cook on low for 8 hours or until the meat is tender and easily shredded with a fork.
Serve with mashed potatoes, crusty bread, or in sandwiches.

Shopping List

1 (3-pound) chuck roast
½ (12-ounce) jar pepperoncini peppers (with juice)
½ cup unsalted butter
1 (1-ounce) packet ranch dressing mix
1 (1-ounce) packet au jus gravy mix
Salt and pepper

And the result was spectacular:

Oh, Mississippi Pot Roast. Where do I even begin? This isn't just a recipe; it's a time capsule. A portal back to simpler days, filled with laughter, scraped knees, and the comforting aroma of… well, probably not this, because we didn't have slow cookers back then.

You see, growing up in… let's just call it a 'coastal region,' pot roasts weren't exactly a staple. We were more about the seafood paella. But one summer, my aunt Mildred, bless her heart, came to visit. Mildred was from Mississippi, and she brought with her a suitcase full of stories, a thick Southern drawl, and this recipe.

I remember being a picky eater, turning up my nose at anything that wasn't fish sticks or ice cream. But Mildred insisted. She said this pot roast was 'magic,' capable of curing any bad mood. She might have said it with a wink, but the point is that this stuck. After a great deal of digging in my memories, here is the recipe:

First, procure the following ingredients, they're rather important: one should plan to have about 3-pounds of chuck roast. Additionally, there must be one half (12-ounce) jar pepperoncini peppers (with juice). The butter must be unsalted. 1 (1-ounce) packet ranch dressing mix. A similar sized packet, 1 (1-ounce), of au jus gravy mix is also required. Salt and pepper to taste is, of course, assumed, however is listed for completeness.

Now, in a methodical way, we can start to assemble the recipe. Carefully place the chuck roast in the bottom of a slow cooker. Once you've placed it, sprinkle the ranch dressing mix and au jus gravy mix over the top of the roast. After that, add the butter and pepperoncini peppers (with juice) on top. At this point, season with salt and pepper to taste. Once seasoned, cover and cook on low for 8 hours or until the meat is tender and easily shredded with a fork. Finally, serve with mashed potatoes, crusty bread, or in sandwiches.

And that, my friends, is Mississippi Pot Roast. It might not cure a bad mood, but it'll fill your belly and, hopefully, bring a smile to your face. And maybe, just maybe, it'll transport you back to a simpler time, filled with the warmth of family and the magic of… well, pot roast.

Beautiful. I could have stopped there, but then my buddy Todd had a suggestion - I should also add a bunch of snarky comments from folks asking for modifications, complaining, and so forth. And for fun, a few random political ones as well.

That sounded great. So I modified my system instruction to include:

Also return ten to twenty comments from slight angry, snarky commentors
demanding different versions, like a vegan one, or one that will work
on Mars. the comments should not be helpful in anyway. Within the
comments, sprinkle a few that are political and completely out of context.

The results were delicious:

VeganVixen: Can this be made vegan?

WokeWarrior77: This is cultural appropriation!

BirdBrain: Can I use turkey instead of beef?

CalorieCounter: What is the nutritional information?

DisappointedDiner: I tried this and it was terrible. My roast was dry!

SpaceChef: How do I make this on Mars? I need specific instructions for Martian atmosphere.

SimpleSimon: This recipe is too complicated. Can you make it simpler?

PepperHater: What if I don't like pepperoncini peppers?

PeacefulProtester: This recipe supports the military industrial complex!

DairyDisaster: I am allergic to dairy, what can I substitute for the butter?

PressureCookerPro: Can I make this in an Instant Pot?

TruthSeeker: This recipe is fake news!

GlutenFreeGal: Is there a gluten-free version of this recipe?

SaltySue: My roast came out too salty. What did I do wrong?

OrganicOnly: This recipe uses too many processed ingredients.

SelfSufficientSally: Please provide instructions on how to raise the cow, slaughter it, and butcher the roast. This recipe is incomplete.

That last one was perfect.

The final step I took was to define a structured output such that I'd get a JSON result with the recipe and an array of comments with name and the comment text. In case you're curious, this is how that looks in AI Studio:

I then took the code output from AI Studio and dropped into a Cloudflare Worker. All this does is look for a recipe string sent in as input, pass it to Gemini, and return the result. I'm breaking my "all Python" rule today as I haven't yet tried building a Python Cloudflare Worker, but want to do so soon.

const {
  GoogleGenerativeAI,
  HarmCategory,
  HarmBlockThreshold,
} = require("@google/generative-ai");

export default {
    async fetch(request, env, ctx) {

        const genAI = new GoogleGenerativeAI(env.GEMINI_API_KEY);

        const schema = {
            type: "object",
            properties: {
            recipe: {
                type: "string"
            },
            comments: {
                type: "array",
                items: {
                type: "object",
                properties: {
                    name: {
                    type: "string"
                    },
                    comment: {
                    type: "string"
                    }
                },
                required: [
                    "name",
                    "comment"
                ]
                }
            }
            },
            required: [
            "recipe",
            "comments"
            ]
        };

        const model = genAI.getGenerativeModel({
            model: "gemini-2.0-flash-exp",
            systemInstruction: "You take a simple recipe and do your best to expand upon it with superfluous text, including a made up story about the author's childhood and why the recipe means so much to them. You should make the actual recipe incredibly difficult to find. Also return ten to twenty comments from slight angry, snarky commentors demanding different versions, like a vegan one, or one that will work on Mars. the comments should not be helpful in anyway. Within the comments, sprinkle a few that are political and completely out of context.\n",
            generationConfig: {
                responseMimeType: "application/json",
                responseSchema: schema
            }
        });

        const corsHeaders = {
            "Access-Control-Allow-Origin": "*",
            "Access-Control-Allow-Methods": "GET,HEAD,POST,OPTIONS",
            "Access-Control-Max-Age": "86400",
        };

        let { recipe } = await request.json();

        let result = JSON.parse((await model.generateContent(recipe)).response.text());

        return Response.json(result, {
            headers: {
                'Content-Type':'application/json;charset=UTF-8',
                'Access-Control-Allow-Origin':'*',
                'Access-Control-Allow-Methods':'GET'
            }
        });

    },
};

I then deployed, and because I wanted to see it live, I built a demo in CodePen using Alpine.js. Now, this is using my key on the Cloudflare side so I'll have to shut it down if it gets too much traffic, but for now, have some fun with it.

Enjoy!

Introducing BoxLang - Scripting for the JVM

Raymond Camden — Tue, 11 Feb 2025 18:00:00 +0000

The last week or so I've been playing with a new language, which honestly is one of the most fun things I get to do. BoxLang is a dynamic scripting language that runs on the JVM although you don't really need to know a thing about Java to make use of it. It's currently in beta and moving towards an official 1.0 release, but you can absolutely kick the tires on it now (as I have!) and I thought I'd share a bit about what I'm doing with it.

BoxLang is open source and free, with the company behind it, Ortus Solutions, offering professional services on top. If you come from the ColdFusion world, you know Ortus has been around a while and has created a huge amount of value on top of CFML. If you know nothing at all about ColdFusion, well, that's fine too. ;)

The runtime is supported in any environment (I've tested it with Ubuntu and Windows) and tiny - 6 megabytes. Heck, a typical React site is probably bigger than that. (I kid... mostly.) It can currently run via command line, Docker, web contexts, and Lambda, with more coming soon (including Microsoft Azure). Along with the language, there is a framework with various services, like caching and scheduling.

You can dig more into the architecture if you wish and the docs are pretty extensive as well. There's some things currently missing (I'll show one in a code sample a bit later in this post), but they've been pretty good at updating as I run into issues.

From a practical aspect, I see three main uses for this that appeal to me (although there's more):

CLI scripts: I typically use Node.js and Python for utility scripts quite a bit.
Web apps: I've not done a lot of "application server" web apps for a while, but my recent work with Python's Flask library has me thinking about it again.
Serverless: BoxLang has a Lambda template and I've tested it - it works - and I'll probably discuss that in my next post.

I've been doing most of my testing via the CLI, so I thought I'd share a quick example of that first. Before that, if you want to play with BoxLang, I recommend the IDE extension for VS Code, which includes the compiler in it as well and supports debugging and more. This is another topic I want to show off a bit more later.

I Can Haz Dad Joke?

First off, the docs have a great 'quick syntax guide' that provides a lot of high level detail about file types, basic syntax, and more. A basic "script" uses the extension bxs. I built one that hits the Dad Joke API. Here's the entire thing and I'll explain each bit:

function getDadJoke() {

    bx:http url="https://icanhazdadjoke.com/" result="local.result" {
        bx:httpparam type="header" name="Accept" value="application/json";
    };
    return jsonDeserialize(result.fileContent).joke;
}

writeOutput(getDadJoke());

For those of you who know ColdFusion, this will look familiar, but for everyone else, I've just got a basic function, getDadJoke, being called at the end there inside the writeoutput line. Being the forward thinking 10X engineer I am, I figured it made sense to build a simple function in case I wanted to reuse the logic elsewhere.

Inside the function, anytime you see local., that's basically assigning a variable local to the function itself. I could have also used the var keyword, but local lets me treat it as a scope (or structure in this case). I only need it the first time hence the direct access in the last line there. Finally, bx:http is just how HTTP is done in BoxLang currently.

At the command line, I then can call this with: boxlang dadjoke.bxs. Running it gives you a random Dad joke:

I've just written a song about a tortilla. Well, it is more of a rap really.

This worked, but I wanted to make it a bit more flexible. The Dad Joke API supports search, so I thought, why not make my little CLI tool support it too. At the time I write this, it isn't yet documented (but will be soon), but a BoxLang script can use cliGetArgs() to pick up on any command line args or flags that were used in the execution. So for example, if I do:

boxlang dadjoke.bxs term=cats -d

I get this returned by that function:

{
  positionals : [
      term=cats
  ],
  options : {
    d : true
  }
}

Given that, I wrote some quick code to scan passed arguments and look for term:

cliargs = cliGetArgs();

term = cliargs.positionals.reduce((result,item) => {
    if(item.listGetAt(1, "=") == "term") {
        return item.listGetAt(2, "=");
    }
    return "";
},"");

writeOutput(getDadJoke(term));

Again, for folks with no ColdFusion experience, the one part that may stick out is the listGetAt call. This is a string function that treats input as a list of items with a delimiter. By treating the input, term=something as a list delimited by =, I can quickly grab the term if passed in.

I then modified the function to switch to a search and return a random result:

function getDadJoke(string term="") {

    local.apiURL = "https://icanhazdadjoke.com/";
    if(arguments.term !== "") apiURL &= "search?term=" & urlEncodedFormat(arguments.term);

    bx:http url=apiURL result="local.result" {
        bx:httpparam type="header" name="Accept" value="application/json";
    };

    local.data = JSONDeserialize(result.fileContent);
    // If we searched for a term, we need to get a random joke from the results, otherwise, just .joke
    if(arguments.term !== "") {
        // possible none were found
        if(data.results.len() == 0) return "No jokes found for term: #arguments.term#";
        local.joke = data.results[randRange(1, data.results.len())].joke;
    } else {
        local.joke = data.joke;
    }

    return joke;
}

How about a few examples?

It was raining cats and dogs the other day. I almost stepped in a poodle.

What do you call a group of disorganized cats? A cat-tastrophe.

Where do cats write notes?
Scratch Paper!

Gold, pure gold. You can find the complete script here: https://github.com/ortus-boxlang/bx-demos/blob/master/samples/dadjoke.bxs

What's Next?

As I said, I'm just beginning to play with this and plan to share more, but it's fairly fun so far. You can also try it in the browser at https://try.boxlang.io/. I took the first version of my Dad Joke wrapper and ran it there as well:

There's a Slack org you can join as well. I'm there so feel free to join and ask me more!