Guides

Export a PDF

Generate and download a PDF of a document that can be pushed to another system.

Overview

Often you will want to keep copies of completed and approved documents in another system of record. To enable this the GraphQL API provides the exportDocument mutation. Exporting a PDF of a document can take a moment, so it is done in two steps.

Request that a document be exported
When the export operation is complete, download the PDF document.

Enable document export

By default documents are not exportable. This is a configurable setting in each app. Before you can export a document through code you'll need to enable that setting. It's the Allow the exporting of documents in this app in the Form Settings of each app.

If you don't turn on this setting, you'll receive errors when you attempt to export a document via the GraphQL API.

Callback URL

This operation requires that you have a web server setup that exposes a callback URL that Kuali can call when the export operation is complete and the exported document is ready for download. Kuali will call this URL/server with information about the document and where it can be downloaded.

Step 1: Request that the document be exported

To initialize the export, call the exportDocument mutation. There are three variables you need to set for this to work.

id: This is the id of the document that you want to export.
options: Determines what to include in the export. One or more of the options can be used at a time.
- document: Includes the main document content.
- history: Includes the workflow history of the document.
- comments: Includes comments made by approvers in the workflow process.
callbackUrl: When the export is prepared Kuali will call this url with information on where to retrieve the exported document.

Query

mutation($id: ID!, $callbackUrl: String!, $options: [String!]!, $useStaticIpProxy: Boolean) {
  exportDocument(id: $id, callbackUrl: $callbackUrl, options: $options, useStaticIpProxy: $useStaticIpProxy)
}

curl 'https://subdomain.kualibuild.com/app/api/v0/graphql' -H 'Content-Type: application/json' -H 'Authorization: Bearer apikey' --data-binary '{"query":"mutation($id: ID!, $callbackUrl: String!, $options: [String!]!, $useStaticIpProxy: Boolean) { exportDocument(id: $id, callbackUrl: $callbackUrl, options: $options, useStaticIpProxy: $useStaticIpProxy)}","variables":{
  "id": "640299b46f0562f58f91a1ba",
  "options": [
    "document",
    "history",
    "comments"
  ],
  "callbackUrl": "<< insert your callback url here >>",
  "useStaticIpProxy": true
}}' --compressed

import fetch from 'node-fetch'

const subdomain = 'subdomain'
const apikey = 'apikey'

const query = `mutation($id: ID!, $callbackUrl: String!, $options: [String!]!, $useStaticIpProxy: Boolean) {
                 exportDocument(id: $id, callbackUrl: $callbackUrl, options: $options, useStaticIpProxy: $useStaticIpProxy)
               }`

const variables = {
  "id": "640299b46f0562f58f91a1ba",
  "options": [
    "document",
    "history",
    "comments"
  ],
  "callbackUrl": "<< insert your callback url here >>",
  "useStaticIpProxy": true
}


fetch(`https://${subdomain}.kualibuild.com/app/api/v0/graphql`, {
  method:'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${apikey}`
  },
  body: JSON.stringify({query, variables})
})
.then(res => res.text())
.then(data => console.log(data))
.catch(err => console.log(err))

<?php

$subdomain = "subdomain";
$apikey = "apikey";

$url = "https://{$subdomain}.kualibuild.com/app/api/v0/graphql";

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$headers = array(
  "Content-Type: application/json",
  "Authorization: Bearer {$apikey}",
);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

$data= '{"query":"mutation($id: ID!, $callbackUrl: String!, $options: [String!]!, $useStaticIpProxy: Boolean) { exportDocument(id: $id, callbackUrl: $callbackUrl, options: $options, useStaticIpProxy: $useStaticIpProxy)}","variables":{
  "id": "640299b46f0562f58f91a1ba",
  "options": [
    "document",
    "history",
    "comments"
  ],
  "callbackUrl": "<< insert your callback url here >>",
  "useStaticIpProxy": true
}}';

curl_setopt($curl, CURLOPT_POSTFIELDS, $data);

//for debug only!
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);

$resp = curl_exec($curl);
curl_close($curl);
var_dump($resp);

require 'net/http'
require 'uri'
require 'json'

subdomain = "subdomain"
apikey = "apikey"

uri = URI.parse("https://#{subdomain}.kualibuild.com/app/api/v0/graphql")
request = Net::HTTP::Post.new(uri)
request.content_type = "application/json"
request["Authorization"] = "Bearer #{apikey}"
request.body = JSON.dump({
  "query" => "mutation($id: ID!, $callbackUrl: String!, $options: [String!]!, $useStaticIpProxy: Boolean) {
                exportDocument(id: $id, callbackUrl: $callbackUrl, options: $options, useStaticIpProxy: $useStaticIpProxy)
              }",
  "variables" => {
    "id": "640299b46f0562f58f91a1ba",
    "options": [
      "document",
      "history",
      "comments"
    ],
    "callbackUrl": "<< insert your callback url here >>",
    "useStaticIpProxy": true
  }
})

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end

puts response.code
puts response.body

import java.io.*;
import java.util.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.Charset;

public class exampleCreate {
  public static void main(String[] args) throws IOException {
    String subdomain = "subdomain";
    String apikey = "apikey";

    URL url = new URL("https://" + subdomain + ".kualibuild.com/app/api/v0/graphql");
    HttpURLConnection http = (HttpURLConnection)url.openConnection();
    http.setRequestMethod("POST");
    http.setDoOutput(true);
    http.setRequestProperty("Content-Type", "application/json");
    http.setRequestProperty("Origin", "https://" + subdomain + ".kualibuild.com");
    http.setRequestProperty("Authorization", "Bearer " + apikey);

    String data = "{\"query\":\"mutation($id: ID!, $callbackUrl: String!, $options: [String!]!, $useStaticIpProxy: Boolean) { exportDocument(id: $id, callbackUrl: $callbackUrl, options: $options, useStaticIpProxy: $useStaticIpProxy)}\",\"variables\":{\"id\":\"640299b46f0562f58f91a1ba\",\"options\":[\"document\",\"history\",\"comments\"],\"callbackUrl\":\"<<insertyourcallbackurlhere>>\",\"useStaticIpProxy\":true}}";

    byte[] out = data.getBytes(Charset.forName("UTF-8"));

    OutputStream stream = http.getOutputStream();
    stream.write(out);
    System.out.println(http.getResponseCode() + " " + http.getResponseMessage());
    BufferedReader in = new BufferedReader(new InputStreamReader(http.getInputStream()));
    String inputLine;
    StringBuffer response = new StringBuffer();
    while ((inputLine = in.readLine()) != null) {
        response.append(inputLine);
    }
    in.close();
    //print in String
    System.out.println(response.toString());
    http.disconnect();
  }
}

Variables

{
  "id": "640299b46f0562f58f91a1ba",
  "options": [
    "document",
    "history",
    "comments"
  ],
  "callbackUrl": "<< insert your callback url here >>",
  "useStaticIpProxy": true
}

Results

Note the exportDocument attribute. That's the jobId that will be needed in the next step.

{
  "data": {
    "exportDocument": "20ddc927-3ba7-4d00-9f8f-87c7ce437a9d"
  }
}

Step 2: Accept the callback

As previously mentioned when the document is generated, Kuali will make a request to the callbackUrl you set in the exportDocument mutation. It will be a GET request that includes two query parameters: jobId and url.

Use the jobId to match against the exportDocument id returned by the exportDocument mutation. This is important. You may be issuing many exportDocument mutations and you cannot predict the order in which they will complete. This will also allow you to verify that every export request completes successfully.

The jobId will look something like this:

f72eab61-56c0-49a2-9bb6-fd48a4d4be89

The url will look something like this:

https://s3.us-west-2.amazonaws.com/co.kuali.app.pdf-dev/640299b46f0562f58f91a1ba-1677954001679.pdf?AWSAccessKeyId=AKIAVBSLLKX72XMZXPPD&Expires=1677954902&Signature=2T4MFC5aqP0jm1VsY3yDBCAn5y0%3D

Note that for security reasons the url is temporary and will expire. It will only be valid for a short period of time.

Kuali GraphQL Documentation