API
Running Ultradox from your own application or website is simple.
Introduction
Just call the URL of your flow and pass the content that your flow needs either as parameters in the URL or in the body of the request.
You can either run the flow, download the generated document or embed your app into your website.
We have composed a couple of examples how to invoke Ultradox on different platforms.
You can copy and paste those snippets into your application or website to get started instantly. At the bottom of this page you will find the supported data formats reference.
Generate API key
Access to your flow is authorized by the Ultradox key. The key is part of the URL, so creating a new key will revoke access to your flow.
Find the key by clicking on File > Integrate or pressing the link icon right in the main toolbar of the Ultradox editor.
This dialog will also provide the URL to run your flow or download the generated document.
Run
When calling the URL to run your flow, all building blocks will be executed just as if you would press the Run button in the Ultradox editor.
You can watch and debug the execution in the Ultradox editor when triggering your flow via the URL.
Ultradox will return an execution report in JSON format that gives you information about the steps that have been executed.
Replace [your key goes here] with the API key of your flow
# Execute in your shell to run your flow
curl http://www.ultradox.com/run/[your key goes here]
<a href="http://www.ultradox.com/run/[your key goes here]" target="_blank">Click to run</a>
// Execute in your App Script function to run your flow
var response = UrlFetchApp.fetch('http://www.ultradox.com/run/[your key goes here]');
var code = response.getResponseCode();
URL url = new URL("http://www.ultradox.com/run/[your key goes here]");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
int code = connection.getResponseCode();
Logger.getLogger("StaticTrigger").info(code == HttpURLConnection.HTTP_OK ? "Success" : "Error: " +code);
URL url = new URL("http://www.ultradox.com/run/[your key goes here]");
URLFetchService urlFetchService = URLFetchServiceFactory.getURLFetchService();
HTTPRequest request = new HTTPRequest(url, HTTPMethod.GET, withDefaults().setDeadline(30.0));
HTTPResponse response = urlFetchService.fetch(request);
int code = response.getResponseCode();
// this example uses jQuery to make a painless JSONP call
$.getJSON("http://www.ultradox.com/jsonp?id=[your key goes here]&action=RUN&callback=?", null,
function(response) {
var code = response.code; // "ok" or "error"
var message = response.message;
}
);
The execution of your flow must not take longer than 60 seconds.
If you are exceeding this execution time limit, your flow will be cancelled and you will receive an error.
When calling long-running flows, use runAsync instead.
Download
If your flow is generating a document (e.g. a PDF or Word document) you can download it by invoking the download URL.
In the following examples we have already specified a sample flow generating a document to get you started.
Feel free to try out the snippets and download the provided example.
Generate and download your own document by replacing the string WNGkRelSf4oykbBWCsrNZ0yVVcAWPU with the key of your own Ultradoc.
# Execute in your shell to save result to a file called processed.pdf
curl http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU > processed.pdf
<a href="
http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?filename=mydocument.pdf
" target="_blank">Click to Download</a>
// Retrieve generated PDF using UrlFetch
var response = UrlFetchApp.fetch('http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU');
// Store generated PDF in a blob
var blob = response.getBlob();
URL url = new URL("http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU");
InputStream inputStream = url.openStream();
FileOutputStream outputStream = new FileOutputStream(new File("processed.pdf"));
transfer(inputStream, outputStream);
URL url = new URL("http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU");
URLFetchService urlFetchService = URLFetchServiceFactory.getURLFetchService();
HTTPRequest request = new HTTPRequest(url, HTTPMethod.GET, withDefaults().setDeadline(30.0));
HTTPResponse response = urlFetchService.fetch(request);
byte[] content = response.getContent();
When using the download URL in your browser, the document will be called untitled.pdf by default.
You can set the filename by passing the filename parameter as shown in the HTML example.
Passing parameters (GET)
Some flows allow or even require additional parameters to be passed upon invocation.
When calling Ultradox you can simply add those parameters to the URL.
The first parameter in a valid URL is separated with a ? while subsequent parameters are delimited by &
Again we have used the key of a sample document that gets downloaded. Replace the string JaFxzA9G0ac4Npx83lvY78M9kO5lNO with your own key to run your own flow.
# Pass position, dateOfInterview and refused as URL parameters
curl http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU
?position=Sales%20Representative&dateOfInterview=2014-01-31&refused=false
>processed.pdf
<a href="http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?position=Sales%20Representative&dateOfInterview=2014-01-31&refused=false" target="_blank">Create and Download</a>
function getParameters() {
var response = UrlFetchApp.fetch('http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?position=Sales%20Representative&dateOfInterview=2014-01-31&refused=true');
var blob = response.getBlob();
var code = response.getResponseCode();
Logger.log(code === 200 ? "Success" : "Error Code: " + code);
// sending out email just for demo purposes
// in real applications send out personalized emails using Ultradox instead
GmailApp.sendEmail("[your email goes here to send this to yourself]", "Your generated document",
"See attachment",
{ attachments: [
{ fileName: blob.getName(),
mimeType: "application/pdf",
content: blob.getBytes()
}
]
}
);
}
URL url = new URL("http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?position=Sales%20Representative&dateOfInterview=2014-01-31&refused=true");
InputStream inputStream = url.openStream();
FileOutputStream outputStream = new FileOutputStream(new File("processed.pdf"));
transfer(inputStream, outputStream);
URL url = new URL("http://www.ultradox.com/download?WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?position=Sales%20Representative&dateOfInterview=2014-01-31&refused=true");
URLFetchService urlFetchService = URLFetchServiceFactory.getURLFetchService();
HTTPRequest request = new HTTPRequest(url, HTTPMethod.GET, withDefaults().setDeadline(30.0));
HTTPResponse response = urlFetchService.fetch(request);
byte[] content = response.getContent();Complete examples on GitHub
Passing parameters (POST)
Some Ultrdocs allow or even require large data to be passed upon invocation. You can specify those parameters in the body of a POST request either in JSON format or form encoded.
Have a look at the HTML example for form encoded data, all the other examples use the JSON format.
In the examples we have again specified the id of a sample document that gets downloaded using the DOWNLOAD action. You can set your own id by replacing the string JaFxzA9G0ac4Npx83lvY78M9kO5lNO with the integration id of your Ultradoc.
Note: Of course, you can also use the RUN action with POST parameters.
# Execute in your shell and the processed Ultradoc will be saved to a file called processed.pdf
curl http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU
-X POST
-H "Content-Type: application/json"
-d '{"position": "Sales Representative", "dateOfInterview": "2014-01-31", "refused": "false"}'
> processed.pdf
<form action="http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU" target="_blank">
<input type="text" name="position" required placeholder="Position">
<input type="text" name="dateOfInterview" required placeholder="Date of Interview, format YYYY-MM-DD">
<input type="text" name="refused" required placeholder="Refused: true / false">
<input type="submit" value="Create and Download">
</form>
function postParameters() {
var payload = {
position: "Sales Representative",
dateOfInterview: "2014-01-31",
refused: true
};
var options = {
contentType: "application/json",
method : "post",
payload : Utilities.jsonStringify(payload)
};
var response =
UrlFetchApp.fetch('http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU',
options)
var blob = response.getBlob();
var code = response.getResponseCode();
Logger.log(code === 200 ? "Success" : "Error Code: " + code);
// sending out email just for demo purposes
// in real applications send out personalized emails using Ultradox instead
GmailApp.sendEmail("[your email goes here to send this to yourself]", "Your generated document",
"See attachment",
{ attachments: [
{ fileName: blob.getName(),
mimeType: "application/pdf",
content: blob.getBytes()
}
]
}
);
}
// this example requires GSON: http://code.google.com/p/google-gson/
URL url = new URL("http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("POST");
connection.setRequestProperty("Content-Type", "application/json");
connection.setDoInput(true);
connection.setDoOutput(true);
Gson gson = new Gson();
// have a look at GitHub gist below to see full code for Payload class
Payload payload = new Payload("Sales Representative", "2014-01-31", true);
String json = gson.toJson(payload);
byte[] bytes = json.getBytes();
connection.setRequestProperty("Content-Length", Integer.toString(bytes.length));
OutputStream os = connection.getOutputStream();
os.write(bytes);
os.close();
InputStream inputStream = connection.getInputStream();
FileOutputStream outputStream = new FileOutputStream(new File("processed.pdf"));
transfer(inputStream, outputStream);
// this example requires GSON: http://code.google.com/p/google-gson/
URL url = new URL("http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU");
URLFetchService urlFetchService = URLFetchServiceFactory.getURLFetchService();
HTTPRequest request = new HTTPRequest(url, HTTPMethod.POST, withDefaults().setDeadline(30.0));
request.setHeader(new HTTPHeader("Content-Type", "application/json"));
Gson gson = new Gson();
// have a look at GitHub gist below to see full code for Payload class
Payload payload = new Payload("Sales Representative", "2014-01-31", true);
String json = gson.toJson(payload);
request.setPayload(json.getBytes());
request.setHeader(new HTTPHeader("Content-Type", "application/json"));
HTTPResponse response = urlFetchService.fetch(request);
byte[] content = response.getContent();Complete examples on GitHub
Passing complex content
When your applications become more complex and you have more than one data set to process and that data might even have a nested structure, you can still use Ultradox.
In that case all you have to do is bring your data in a matching JSON format and pass it along in the body of a POST request.
In the examples we have again specified the id of a sample document that gets downloaded.
You can set your own key by replacing the string kNjCQaAALBCCtRH7gSJvasHF5fqJIW with the integration key of your flow.
Depending on your flow change the structure of the JSON passed accordingly.
The pure HTML solution deserves special attention. Ultradox has a feature that allows you to pass complex objects and even lists of objects using GET requests. This is especially nice when using links in HTML .
To pass properties of objects you simply use the dot notation for the name of a parameter like in object.property .
If you want a list of objects you pass along as many parameters of the same name as you want. If you pass both object.property=Prop1 and object.property=Prop2 as parameters to a GET request, Ultradox will receive a list of objects one having Prop1 as a property, the other Prop2. Have a look at the HTML tab for a complete example.
Of course, you can also run your flow with complex parameters instead of triggering the download.
When making HTML GET requests with many URL parameters make sure your client can handle them as there is a limitation on the URL length in many HTTP implementations. Also, make sure your parameters are URLEncoded.
# Execute in your shell and the processed Ultradoc will be saved to a file called processed.pdf
curl http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?locale=DE
-X POST
-H "Content-Type: application/json"
-d '{
"name": "Olli",
"events": [
{
"title": "Strategy Meeting",
"startTime": "2014-02-01T10:00:00+01",
"endTime": "2014-02-01T11:30:00+01",
"description": "Discussion of the floreysoft strategy",
"location": "Telemannstraße 22, 20255 Hamburg"
}, {
"title": "Dinner",
"startTime": "2014-02-01T20:00:00+01",
"endTime": "2014-02-01T22:30:00+01",
"description": "Dinner with Le Chef",
"location": "Gaußstraße 3, 22765 Hamburg"
}
]
}'
>processed.pdf
<!-- Manual URL enconding at http://www.albionresearch.com/misc/urlencode.php -->
<a href="http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?name=Olli&
events.title=Strategy%20Meeting&
events.startTime=2014-02-01T10%3A00%3A00%2B01&
events.endTime=2014-02-01T11%3A30%3A00%2B01&
events.description=Discussion%20of%20the%20floreysoft%20strategy&
events.location=Telemannstra%C3%9Fe%2022%2C%2020255%20Hamburg&
events.title=Dinner&
events.startTime=2014-02-01T20%3A00%3A00%2B01&
events.endTime=2014-02-01T22%3A30%3A00%2B01&
events.description=Dinner%20with%20Le%20Chef&
events.location=Gau%C3%9Fstra%C3%9Fe%203%2C%2022765%20Hamburg
" target="_blank">Create and Download</a>
function postComplex() {
// to show that stringifying real dates does work as well
var date = new Date();
var events = {
name: "Olli",
events: [
{
title: "Strategy Meeting",
startTime: "Fri Feb 01 10:00:00 CET 2014",
endTime: "Fri Feb 01 11:30:00 CET 2014",
description: "Discussion of the floreysoft strategy",
location: "Telemannstraße 22, 20255 Hamburg"
}, {
title: "Dinner",
startTime: "Fri Feb 01 20:00:00 CET 2014",
endTime: date,
description: "Dinner with Le Chef",
location: "Gaußstraße 3, 22765 Hamburg"
}
]
};
var options = {
contentType: "application/json",
method : "post",
payload : Utilities.jsonStringify(events)
};
var response =
UrlFetchApp.fetch('http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?locale=DE',
options)
var blob = response.getBlob();
var code = response.getResponseCode();
Logger.log(code === 200 ? "Success" : "Error Code: " + code);
// sending out email just for demo purposes
// in real applications send out personalized emails using Ultradox instead
GmailApp.sendEmail("[your email goes here to send this to yourself]", "Your generated document",
"See attachment",
{ attachments: [
{ fileName: blob.getName(),
mimeType: "application/pdf",
content: blob.getBytes()
}
]
}
);
}
// this example requires GSON: http://code.google.com/p/google-gson/
URL url = new URL(
"http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?locale=DE");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("POST");
connection.setRequestProperty("Content-Type", "application/json");
connection.setDoInput(true);
connection.setDoOutput(true);
Events events = new Events("Olli");
events.addEvent(new Event("Strategy Meeting", new Date(113, 01, 01,
10, 00), new Date(113, 01, 01, 11, 30),
"Discussion of the floreysoft strategy",
"Telemannstraße 22, 20255 Hamburg"));
events.addEvent(new Event("Dinner", new Date(113, 01, 01,
20, 00), new Date(113, 01, 01, 22, 30),
"Dinner with Le Chef",
"Gaußstraße 3, 22765 Hamburg"));
// use ISO8601 date format for best compatibility
Gson gson = new GsonBuilder().setDateFormat("yyyy-MM-dd'T'HH:mm:ssX").create();
String json = gson.toJson(events);
byte[] bytes = json.getBytes("UTF-8"); // encoding is important when you are outside of ASCII
connection.setRequestProperty("Content-Length", Integer.toString(bytes.length));
OutputStream os = connection.getOutputStream();
os.write(bytes);
os.close();
InputStream inputStream = connection.getInputStream();
FileOutputStream outputStream = new FileOutputStream(new File("processed.pdf"));
transfer(inputStream, outputStream);
// this example requires GSON: http://code.google.com/p/google-gson/
URL url = new URL(
"http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?locale=DE");
URLFetchService urlFetchService = URLFetchServiceFactory.getURLFetchService();
HTTPRequest request = new HTTPRequest(url, HTTPMethod.POST, withDefaults().setDeadline(30.0));
request.setHeader(new HTTPHeader("Content-Type", "application/json"));
Events events = new Events("Olli");
events.addEvent(new Event("Strategy Meeting", new Date(113, 01, 01,
10, 00), new Date(113, 01, 01, 11, 30),
"Discussion of the floreysoft strategy",
"Telemannstraße 22, 20255 Hamburg"));
events.addEvent(new Event("Dinner", new Date(113, 01, 01,
20, 00), new Date(113, 01, 01, 22, 30),
"Dinner with Le Chef",
"Gaußstraße 3, 22765 Hamburg"));
// use ISO8601 date format for best compatibility
Gson gson = new GsonBuilder().setDateFormat("yyyy-MM-dd'T'HH:mm:ssX").create();
String json = gson.toJson(events);
request.setPayload(json.getBytes("UTF-8"));
request.setHeader(new HTTPHeader("Content-Type", "application/json"));
HTTPResponse response = urlFetchService.fetch(request);
byte[] content = response.getContent();Complete examples on GitHub
Running asynchronously
When calling flows that may take longer than 60 seconds you will have to call them asynchronously.
Just replace the /run part of the URL with /runAsync to do so. Your call will immediately return and will trigger Ultradox as a long running task on the server.
You will not get the execution report as a result.
If you want to retrieve a document or any other information once the flow is completed, you will have to call your own app using a webhook and pass the desired information.
Data types
When passing data using JSON or even in GET requests using URL parameters you need to know how to format them, so that Ultradox can make sense out of them.
| |
Booleans can be passed either with or without quotes. If the value passed is the empty string or |
| |
Numbers are always specified as fixed point values. If the decimal point actually is |
| |
Specify them encoded as |
| |
Dates are the most complicated values to pass. The format to be used in JSON is specified in ISO 8601. If you use this format, you are on the safe side. As a quick reference, a date formatted according to ISO 8601 might like that Unfortunately, in some situations you are not free to choose formatting of dates. These situations include using Google Apps Script or JSON libraries that do the formatting of dates for you. To help you with that, Ultradox tries to accept and parse all standard input formats. Let us know if there is a format Ultradox can not parse, but can be considered a standard by any means. |
Questions and Feedback
If you have any comments on this page, feel free to add suggestions right to the Google document that we are using to create this site.
If you are not yet member of the Ultradox community on Google+, please join now to get updates from our end or to provide feedback, bug reports or discuss with other users.
Last Updated: 11/7/17