Starting Out with OutSystems and Adobe Acrobat Services
Welcome to this tutorial, where you’ll learn how to use the Adobe Acrobat Services API in OutSystems. This tutorial walks you through a simple application that utilizes a Light BPT process to chain several Adobe Acrobat Services operations. Specifically, we’ll cover converting a Microsoft Word document to a PDF format, optimizing the PDF for web viewing (Linearization), and finally securing the PDF with a password.
We will be using my Adobe Acrobat Services Forge Component, which will allow us to easily interact with the Adobe Acrobat cloud service and perform these operations on our documents.
By the end of this tutorial, you should have a good understanding of how to use the Adobe Acrobat Services API with OutSystems, and how to integrate this functionality into your own applications.
Adobe Acrobat Services
The Adobe Acrobat Services API is a collection of cloud-based services that provide a wide range of document automation capabilities. These include features such as document creation, editing, conversion, and content extraction. Adobe’s main offerings within the Document Services API are as follows:
- Adobe PDF Services — This service allows for the conversion of various file formats to PDF, as well as PDF manipulation and transformation (including protection).
- Adobe PDF Embed — This powerful PDF web viewer provides annotation support and can be integrated into other applications.
- Adobe Document Generation — With this service, Word and PDF documents can be generated based on dynamic data. Data and Word templates, including markup and placeholders, are merged to create the final document.
- Adobe PDF Extract — This service leverages Adobe Sensei AI technology to automatically extract content and structural information from PDF documents.
Preparations
Before we can start, there are several preparatory tasks that we need to complete.
Adobe Acrobat Services Trial
Acrobat Services by Adobe provides a trial version that permits either one thousand document operations or a 6-month duration, whichever concludes first.
To proceed, you must sign up for a developer account and generate an API project using the Adobe Developer console.
Follow the link above then click on the Sign In button in the top right corner. Either login with an existing Adobe account or register a new one.
After you have successfully logged in or registered an account you should get redirected to your Adobe Developer projects space. Perform the following steps:
- Click on Create Project.
- In the project detail screen click on Add API.
- From the list of available APIs select PDF Services API.
- Select OAuth Server-to-Server authentication type in the Credentials screen and provide a name for your credentials.
- In the Product profiles screen select Acrobat Services: PDF Services API (should be the only one you can select).
- Back in the project detail screen in the Connected credentials section click on your created credentials.
- Copy Client Id, Client Secret and Scopes as we will need them later
With the trial project created we can proceed with the next step.
OutSystems Forge Components for Adobe Acrobat Services
Download the following components from OutSystems Forge
Adobe IMS Token Exchange is a component that exchanges your credentials — Client Id, Client Secret and Scopes — for an access token. The access token is used for all Adobe Acrobat Services operations to authorize your requests.
Adobe Acrobat Services component implements the various document automation operations of Adobe Acrobat Services. The Adobe Acrobat Services component has a demo application associated. Please download this as well, as we will use it to walk through the implementation details.
With all components downloaded we proceed with the final preparatory tasks.
Configure Adobe Acrobat Services REST API
Adobe Acrobat Services hosts two different environments. One for Europe (which is set as default) and one for North America. To change the base URL of the component open Service Center and open the Adobe_PDFServices_IS module.
Click the Integrations tab and under Consumed REST APIs change the base URL to your needs
- https://pdf-services-ew1.adobe.io — For Europe
- https://pdf-services-ue1.adobe.io — For North America
Configure Demo Application
The demo application that comes with the Adobe Acrobat Services has three site properties you need to configure before you can run the application.
Navigate to Service Center and choose the AdobeAcrobatServicesDemo module. Once you’re on the detail screen, click on Site Properties and enter the values for Client Id, Client Secret, and Scopes that you previously copied from the Adobe Developer console.
The information known as “Client Secret” is considered confidential and requires appropriate security measures to protect it. To enhance its security, it is recommended to store this sensitive data in a more secure environment such as HashiCorp Vault Key Value Store. You will find a connector for Vault on OutSystems Forge.
Now that all the necessary tasks have been finished, it’s time to test it out.
Begin by opening the demo application and choosing a Microsoft Word document from your local file system.
Next, select the document’s language from the dropdown menu and provide both a user password and an owner password. The user password will be required every time you attempt to open the resulting PDF document, while the owner password will be necessary if you want to remove the document’s protection or alter any of its permissions.
Click the Upload and Process button to initiate a processing task. Refresh the JobQueue until the process is finished. If processed successfully you can download the resulting PDF document.
Overview of Document Processing
The demonstration application utilizes a series of Adobe Acrobat Services operations that are executed in a sequence. To better illustrate the document processing flow across these operations, please refer to the following image.
In the demo application, when you select the Upload and Process button, the original source document is uploaded to Adobe Document Cloud, which then generates a unique identifier known as the AssetId. This AssetId is then used as input for the initial Adobe Acrobat Services operation, Adobe_DocumentCreate, which converts the Microsoft Word Document to a PDF document.
To accomplish this conversion, the API endpoint utilized by Adobe_DocumentCreate retrieves the asset from Adobe Document Cloud by the given AssetId. Once retrieved, the document is transformed into a PDF format and saved as a new asset within Adobe Document Cloud. Finally, the new AssetId of the PDF document is returned to your application.
By using this new AssetId as the parameter for the subsequent processing operations, there is no longer a requirement to download the outcome of each operation and upload it again for the next one.
If you’ve used the previous version of the Adobe Acrobat Services component (formerly known as Adobe PDF-Services), you’ll notice significant changes. You no longer need to upload the source document for every individual operation; instead, you can link several operations using the resulting AssetIds. This significantly speeds up operations and decreases the memory load on your front-end servers.
Previously, you had to monitor operation results on your own, such as in a Business Process. However, the OutSystems component now encapsulates polling of operation results. To accomplish this, I added the Polly library, a C# library that provides thread-safe and resilient HTTP Requests, to the component. If you’re interested in learning more about Polly, check out the link below.
Demo Application Walkthrough
Let’s examine the significant implementation details of the demo application by launching it in Service Studio.
Access Token Utility action
Open the GetAccessToken server action in the IMS folder.
This utility server action retrieves an access token using Adobe_ClientCredentials from the Adobe IMS Token Exchange component. The configured site properties for Client Id, Client Secret and Scopes are used to exchange them for an access token. On success the action returns the Client Id and the access token to be used in all Adobe Acrobat Services operations that require authorization.
Document Upload and Process
Next is the Document_UploadAndProcess server action in the Document folder. This action is executed when you click the Upload and Process button in the demo application.
The action takes all form elements as input parameters. It uploads the source document to Adobe Document Cloud and creates a job queue entry which then triggers the actual processing.
First the action retrieves an access token using the utility action GetAccessToken. It then tries to upload the document to Adobe Document Cloud using the Adobe_DocumentUpload server action. Upon success that server action returns an AssetId which is, including some other input parameters written to the Job Queue entity using the Job_Create entity wrapper action.
Every created job queue entry triggers a Light BPT process instance of Process Document.
Document Processing
The chain of Adobe Acrobat Services operations is executed in an instance of ProcessDocument asynchronously, which is triggered by the CreateJob entity event.
Being a Light BPT process this process has a single Automatic Activity ProcessJobQueueEntry.
The flow is quite large, so the below image only shows a part of it.
- GetJob retrieves the current job queue details.
- GetAccessToken retrieves an access token which is used for all subsequent operation requests to Adobe Acrobat Services.
- Job_SetStatusXXX sets to Job status to the next following operation. The first one is Converting.
- Adobe_DocumentCreate triggers the PDF conversion of the source AssetId retrieved from the job queue details.
- If unsuccessful an AdobeOperationException with the resulting error message is thrown and handled by setting the job status to Error and the error message.
- If successful, the next job status is set, and the resulting Asset Id of the previous step is used as new source Asset Id for the next step.
At the end of the flow and every operation was processed successfully the last Asset Id is used to download the final document from Adobe Document Cloud using Adobe_DocumentDownload action and stored in the JobResult entity.
That’s all there is to it. By utilizing Adobe Acrobat Services, you can integrate powerful document automation capabilities directly into your application. Offloading document operations to an external service is an obvious choice, as these operations are typically resource-intensive and may negatively impact overall server performance if handled directly on the front-end servers.
With the information provided in this guide, you should now have the knowledge necessary to construct your own document automation workflows. In addition to the three operations demonstrated in the demo, the component also contains numerous other operations for you to explore independently.
The official REST API documentation for Adobe Acrobat Services is an excellent resource to investigate the various configuration options of operations.
Thank you for reading. I hope you liked it and that i have explained the important parts well. Let me know if not 😊
If you have difficulties in getting up and running, please use the OutSystems Forum to get help. Suggestions on how to improve this article are very welcome. Send me a message via my OutSystems Profile or respond directly here on medium.
If you like my articles, please leave some claps. Follow me and subscribe to receive a notification whenever I publish a new article. Happy Low Coding!
