Send your request Join Sii

For one of our Sii clients, handling documents is one of the primary functions used by users. Every day they review and create hundreds – if not thousands – of files. Some of them are in the form of scanned fax documents, while others are digitally signed using the Adobe Sign solution.

In this article, we will focus on using Heroku to fill already existing documents in .pdf format with data provided by a Salesforce user. I’m not going to cover here how all the functionality is done and what code goes underneath – but all the necessary steps to create a connection with the Heroku application from the Salesforce Org and the basic idea of how it works here.

Heroku

In our project, we are using the application hosted on Heroku to process the documents in a few different ways:

  • filling them with data,
  • rotating pages upside down,
  • splitting pages into smaller documents.

Here we will focus on filling documents with provided data – but Heroku itself doesn’t provide such functionality, so we will have to create it.

But first things first: what is Heroku?

The Salesforce platform combines multiple tools and services into one coherent environment, and Heroku is a cloud-based solution using the Platform as a Service (PaaS) model that is a part of that toolset. Its purpose is to allow users to host a web application in a serverless model. Heroku provides tools to easily build and manage applications without having to worry about the server and its configuration. Created applications (in one of the example programming languages: Java, Ruby, Python, PHP, JavaScript, and Go) can be managed by one of the common tools like Git Hub. Heroku has an easy-to-understand interface that allows you to monitor the performance and contains all the necessary instructions on how to use available functionalities.

Heroku – how to start?

To start our work, we will need to create an account on the Heroku Platform. We can have one for personal use, or create an account hosting multiple applications for the entire organization.

For the purpose of this article, we will create a single Heroku app called pdftools:

Create new App in Heroku
Fig. 1 Create new App in Heroku

For this newly created app we will need certain plugins, without which we will not be able to implement some of the necessary functionalities. The most important one is Heroku Postgres, which will allow us to create a Heroku database to store the files.

Heroku Postgres function
Fig. 2 Heroku Postgres function

The files are stored in a ‘raw’ form. You can call them a template on which we will apply our changes. These .pdf documents are basic, empty, and have a specific configuration containing merge fields (more about them in the next chapter). The versions of these documents that have been filled with provided data are temporary – they are deleted after they are filled and returned, so we will not keep any sensitive data there.

Adding plugins is not enough for all of this to work – we also need to connect with the new database with a help of a specific tool like pgAdmin. Using this connection, we can enter our database and prepare the structure of our data with the necessary tables.

In addition to the database plugin, we also have access to many others, such as CloudAMQP or New Relic APM, which could help us with data flow, error monitoring, or preparing a visualization of specific information. The Heroku app itself provides access to certain graphs, but using additional plugins can extend this functionality:

Graphs provided by Heroku
Fig. 3 Graphs provided by Heroku

We cannot forget that the most important step is to code the app itself (here we use Java programming language) that will handle the requests sent from the Salesforce Platform. I am not able to include parts of the code used in our app here, but all the necessary information needed to deploy our code is listed in the form of easy-to-follow steps under the Deploy tab:

Deploy tab
Fig. 4 Deploy tab

Even without the code itself, I can describe the general workflow of our app: it takes input data in the form of a map of all the values we want to use to assign under specific merge fields in the specific document, and sends back a completed .pdf file. To do this, we will need the document configured in a specific way.

Document

At the very beginning, we need to prepare a .pdf file structure that consists of labels and merge fields, to which we apply specific values (we can create any data structures we want, be it a table or a complicated questionnaire).

For example, let’s assume that our document will contain user data from our system. For this, we have to prepare merge fields to store this information:

Merge fields for storing information
Fig. 5 Merge fields for storing information

The above example shows that each of our merge fields is assigned to a specific value, and the name of each field will be used to assign the desired value.

As I mentioned before, in order to fill in these fields, we need to provide certain data in our request. To do this, we need at least two pieces of information:

  1. Name of the template file we want to fill.
  2. Value map, where the key is the field Name, and the assigned value is the information we want to assign to that field.

The request with these two arguments must be handled by our Heroku app by selecting the mentioned document template from the database and by assigning values from the Map to the fields with the corresponding Names.

Here is an example of a request in the JSON format:

{
   "documentName": "UserDataDocument",
   "userData": [        
      {"FirstName": "TestFN"},
      {"LastName": "TestLN"},
      { "Birthday": "01/01/1999"},
      {"Birthday": "01/01/1999"},
      {"GenderMale": "true"},
      ...
   ]
}	

Connecting the Heroku app from the Salesforce Org

The first step is to create all the necessary classes and methods in the system. These will be used to send requests to our Heroku app. Here we will need few methods: to upload new .pdf template file of our document to the Heroku Postgres database, and other separate methods, like the one used to send information to fill the uploaded document.

We store all the URL addresses to which we send requests under a Metadata entry, where we have a separate configuration for different environments (e.g. DEV, SQA, UAT):

Metadata do przechowywania adresów URL
Fig. 6 PDF Tools Configuration

We can also, as the example above shows, set up backup applications to which we will redirect our requests if a specified number of errors occurs at a given time.

The second step is to choose a right User from our Org that will be used to authenticate our connection. For this, we can create a new User, to whom we will assign a specific Profile and Permissions so it has access only to the necessary data needed for our functionality.

Profil użytkownika
Fig. 7 User details

The next step is to create a new Connected App, which allows us to link Salesforce to our new Heroku app.

Nowa Connected App
Fig. 8 New Connected App

After creating the PDF Tools App, we have access to the data we use to configure our connection with Heroku. To do this, we need Consumer Key and Consumer Secret:

PDF Tools App
Fig. 9 PDF Tools App

We use the information stored here, and the previously created User, to create a configuration file on the Heroku side, which is used to authenticate our connection. Below is an example of an entry from that file – containing all necessary information for one of the Salesforce environments:

[ENV_NAME][email protected].[ENV_NAME]
[ENV_NAME].sfPassword=[ENCRYPTED_PASSWORD_TOKEN]
[ENV_NAME].sfServerurl=https://test.salesforce.com
[ENV_NAME].authEndpoint=https://test.salesforce.com/services/Soap/u/35.0

[ENV_NAME][email protected].[ENV_NAME]
[ENV_NAME].oauthPassword=[ENCRYPTED_PASSWORD_TOKEN]
[ENV_NAME].oauthEndpoint=https://test.salesforce.com/services/oauth2/token
[ENV_NAME].oauth_client_id=[CONSUMER_KEY]
[ENV_NAME].oauth_client_secret=[ENCRYPTED_CONSUMER_SECRET]
[ENV_NAME].sessionTtl=5
[ENV_NAME].domainPart=[ENV_NAME]

The file prepared in this way, containing configuration data for all Users from different Salesforce environments connecting to that application, is placed in the code of our Heroku app, where it is used to validate the connecting Users.

Summary

Having all this in the database, you can create a Heroku application connected to Salesforce Org, which should fill the provided documents with the requested data. Basic steps and descriptions for creating applications like this one can also be found on the Trailhead platform, which stores a lot of training materials that can introduce anyone to the inner workings of the Salesforce platform.

I hope that this article will be at least a little helpful in the process of creating a similar solution.

***

And if you are interested in Salesforce solutions, be sure to also take a look at other articles by our authors.

5/5 ( vote: 1)
Rating:
5/5 ( vote: 1)
Author
Avatar
Maciej Gajewy

Salesforce Developer focused on programming and deployment process. His favorite part of IT work is solving issues and feeling relief after a long debugging session. Privately he likes being lost in the fantasy worlds of books and video games.

Leave a comment

Your email address will not be published. Required fields are marked *

You might also like

More articles

Don't miss out

Subscribe to our blog and receive information about the latest posts.

Get an offer

If you have any questions or would like to learn more about our offer, feel free to contact us.

Send your request Send your request

Natalia Competency Center Director

Get an offer

Join Sii

Find the job that's right for you. Check out open positions and apply.

Apply Apply

Paweł Process Owner

Join Sii

SUBMIT

Ta treść jest dostępna tylko w jednej wersji językowej.
Nastąpi przekierowanie do strony głównej.

Czy chcesz opuścić tę stronę?