Using cover pages in Faxolution for Applications
About this document
This tutorial provides information on using cover pages for Faxolution for Applications. A cover page can not only hide the first page of your fax for data privacy reasons. It can also be used to individualize the fax for different recipients. Read the article to learn more about these and further use cases.
Hiding information behind a cover page
Let’s suppose you want to hide the first page of your fax document behind a cover page for data privacy reasons. To do so, follow these steps:
- Log into the EAS portal and make sure the cover page ‘coverpage-default.ftl.html’ is selected in your Faxolution for Applications account. To do so, click on “Administration” in the menu on the left side of the EAS. Then click “Fax services” and next “Faxolution for applications”. Select your login ID and select coverpage-default.ftl.html as cover page template in the fax settings if it is not yet activated:
- Include pairs of keys and values in the recipients part of your fax job request. The keys are the variable names, the values contain data that should be written onto the cover page. These variables can be used as keys in the default cover page:
- FromName
- FromCompanyName
- FromTelNum
- ToName
- ToCompanyName
- ToFaxNum
- SubjectTitle
- SubjectText
In the screenshots below, you will see how a request could look like with some of the available variables.
Are you in the middle of embedding our API into your application? We have created SDKs for different programming languages on our GitHub presence that facilitate the task.
Example for a REST request:
"recipients": [
{
"number": "+4989123456789",
"properties": [
{
"key": "FromName",
"value": "Jon Doe"
},
{
"key": "FromCompanyName",
"value": "retarus GmbH"
},
{
"key": "FromTelNum",
"value": "123456789"
},
{
"key": "ToName",
"value": "Jane Doe"
},
{
"key": "ToCompanyName",
"value": "ACME Corp"
},
{
"key": "ToFaxNum",
"value": "987654321"
}
]
}
]
While the properties for a SOAP request would look like this:
<faxRecipient>
<number>+49123456789</number>
<property>
<key>FromName</key>
<value>Jon Doe</value>
</property>
<property>
<key>FromCompanyName</key>
<value>retarus GmbH</value>
</property>
<property>
<key>FromTelNum</key>
<value>123456789</value>
</property>
<property>
<key>ToName</key>
<value>Jane Doe</value>
</property>
<property>
<key>ToCompanyName</key>
<value>ACME Corp</value>
</property>
<property>
<key>ToFaxNum</key>
<value>987654321</value>
</property>
</faxRecipient>
C) Send your fax job request. Regardless of whether you use SOAP or REST, the result on the cover page of the transmitted fax should look like this with the values from above:
Adressing different recipients individually
Now let’s amend our first example and send fax messages with cover pages to several recipients. As the properties are part of the recipients object, you set the individual values for every recipient (REST) or faxRecipient (SOAP) in your fax job request. This is a simplified example for REST:
"recipients": [
{
"number": "+4989123456789",
"properties": [
{
"key": "FromName",
"value": "Jon Doe"
},
{
"key": "ToName",
"value": "Jane Doe"
}
]
},
{
"number": "+4989987654321",
"properties": [
{
"key": "FromName",
"value": "Jon Doe"
},
{
"key": "ToName",
"value": "Frank Doe"
}
]
}
]
Customize a cover page with your company logo
Would you like to harmonize the cover page a little with the look of your company’s documents? To integrate a company logo, get in touch with your contact at retarus and order a customized cover page. A technical consultant or an implementation engineer will then design the cover page according to your input. Please note that the maximum size of the image is 32 kilobytes. If the logo is bigger, only the first 32 kilobytes will be displayed in the fax. We therefore recommend using a simple black and white version of your company logo, this will also look better in the fax document. This is how a company logo could be integrated in a cover page:
Automate your processes with barcodes or QR codes
Think about the following scenario: You are sending a lot of forms for different business processes and expect the recipients to provide a response via fax. Now you have to classify them so that the return faxes are forwarded to the right department for further processing. By including barcodes or QR codes into a cover page, you can easily assign incoming faxes to existing business transactions. This is how it works:
Currently, we support the following code types:
- AZTEC
- CODABAR
- CODE_39
- CODE_93
- CODE_128
- DATA_MATRIX
- EAN_8
- EAN_13
- ITF
- MAXICODE
- PDF_417
- QR_CODE
- RSS_14
- RSS_EXPANDED
- UPC_A
- UPC_E
- UPC_EAN_EXTENSION
For using graphical codes, please get in touch with your contact at retarus and order an individual cover page. He or she will guide you through the next steps. Graphical codes are set within the recipient properties section with the term ‘barcodeValue’ as key and the value that shall be depicted graphically. This is an example for a SOAP request:
<property>
<key>barcodeValue</key>
<value>123456789</value>
</property>
And this is how a form with an integrated graphical code could look like:
Use Faxolution for Applications to create documents
You want to send faxes, but your application cannot create documents on its own? Transform information into documents with Faxolution for Applications by using a multi-page cover page! This is a cover page that contains so much content in one or more variables that additional pages are created during the job processing. In fact, the cover page would then be the fax document itself, while no additional documents would be needed.
To use this feature, please inform our staff that you would like to include content that exceeds one page. Like in the case of including a company logo or a graphical code, a technical consultant or implementation engineer will design the page for you according to your wishes. For example, we could integrate a table with three rows, separated by dividing lines:
<tr><td colspan="2">${SubjectText1!}</td></tr>
<tr><td colspan="2"><hr></td></tr>
<tr><td colspan="2">${SubjectText2!}</td></tr>
<tr><td colspan="2"><hr></td></tr>
<tr><td colspan="2">${SubjectText3!}</td></tr>
As the document (SOAP) or documents (REST) element in the request is optional (see API documentation ), you can leave it away and just populate the target number and the key / value pairs for the properties. The resulting fax will only contain the cover page. Enriched with a lorem ipsum text, the result would look like in the image below. Please note that both pages were depicted side by side only for layout reasons. The fax document itself uses individual pages to depict the content.
Questions and answers on cover pages
What happens if I do not fill every variable in my request?
The visible result on the fax page depends on the layout of the page, but in general, not filled variables are left empty. For example, if we do not include the company names in the example from above, we will get this result:
How do I choose one out of several cover pages?
You can either log into the EAS portal like described above and select a cover page via the dropdown menu for cover page templates. Or you reference to a cover page in your fax job request. In REST, the element coverpageTemplate is part of the element renderingOptions, while in SOAP, the element coverpageTemplateName is part of the options. For further details, please see the particular guidelines.
Please note: If settings for a cover page both exist in the EAS portal and the fax job request, the ones from the latter will be used.
What happens if I reference a cover page that does not exist in the EAS portal?
The fax job will not be processed, failing with the status “RENDERING_ERROR / Failed to process/upload coverpage”. Whether and where you can see this error depends on your status report settings, please see the general guideline for Faxolution for Applications for further details.
Can I use different cover pages in one fax job request?
No, you can only use one cover page per fax job request at the moment. However, you could send several fax job requests and reference to different cover pages in each request as long as the cover pages have been setup in the EAS portal before.