Clerk

This add-on is operated by TRIX MOBI

Pragmatic printout functionality for active PDF forms.

Clerk

Last Updated: 04 August 2014

The Clerk add-on is currently in beta.

Table of Contents

Clerk is an add-on that enables you programatically fill in field-values for an active PDF form, letting you easily generate a new PDF based on those field-values, which can then be printed or stored.

Adding the functionality to an application allows you to prepare documents, such as invoices or offers, easier and more convenient.

Clerk is accessible via an API and has supported client libraries for Ruby.

Provisioning the add-on

Clerk can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:add clerk
-----> Adding clerk to sharp-mountain-4005... done, v18 (free)

Once Clerk has been added a CLERK_URL setting will be available in the app configuration and will contain the canonical URL used to access the newly provisioned Clerk service instance. This can be confirmed using the heroku config:get command.

$ heroku config:get CLERK_URL
http://user:pass@instance.ip/resourceid

After installing Clerk the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export CLERK_URL=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the CLERK_URL values retrieved from heroku config to .env.

$ heroku config -s | grep CLERK_URL >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Using with Rails

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Clerk client library.

gem 'clerkapp', require: 'clerk'

Update application dependencies with bundler.

$ bundle install

Let’s make few assumptions:

  • you have form uploaded with identifier test.pdf (how to upload a PDF form).
  • your form has fields named name, gender, newsletter.

You can print your first form with just a few lines of code:

File.open("test_printout.pdf", "wb") do |f|
  pdf_content = Clerk::Form.print(
    "test.pdf",
    fields: {
      name: "Johm Mayer",
      gender: "0",
      newsletter: "Y"
    },
    { file: true }
  )
  f.write pdf_content.read
end

Dashboard

For more information on the features available within the Clerk dashboard please see the docs at mysite.com/docs.

The Clerk dashboard allows you to manage your PDF forms.

The dashboard can be accessed via the CLI:

$ heroku addons:open clerk
Opening clerk for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting the application in question. Select Clerk from the Add-ons menu.

Uploading PDF forms

To upload a PDF form, open the dashboard:

$ heroku addons:open clerk

No click Upload, and select the file from your drive or paste a URL. In no time your first form will be uploaded with an identifier set to the filename. That’s all, you can now print your first document.

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade clerk:premium
-----> Upgrading clerk:premium to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: clerk:premium

Removing the add-on

Clerk can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:remove clerk
-----> Removing clerk from sharp-mountain-4005... done, v20 (free)

Support

All Clerk support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome at support@clerkapp.io