Quickstarts

The Document Cloud Services SDK (DC SDK) provides APIs for creating, combining, exporting PDFs as well as text recognition (OCR). The SDK’s simple cloud-based APIs help you get up and running quickly. Once you’ve received your developer credential, download and set up one of the sample projects. After you’re familiar with the APIs, leverage the samples in your own server-side code.

Note

The DC Service’s SDK only supports server-based use cases where credentials are saved securely in a safe environment. Services SDK credentials should not be sent to untrusted environments or end user devices.

Trial vs paid program

The DC Services SDK provides a trial program so that you can take a deep dive into its cool features at zero cost. Trial users get free credentials that enable processing of 5000 pages-worth of PDF actions for 6 months.

Processing is calculated based on the number of PDF actions applied to each page of a document.

Example 1:

  • Converting a ten-page Word document into PDF consumes 10 pages of the trial quota.

  • 1 (Action: convert) x 10 (pages) = 10 pages of quota.

Example 2:

  • Running OCR on 20 pages and then combining those pages into a single PDF consumes 40 pages of the trial quota.

  • 1 (Action: OCR) x 20 (pages) + 1 (Action: Combine) x 20 (pages) = 40 pages of quota.

This generous allowance of processing power should allow you to get up and running with the easy-to-use APIs with little investment.

Paid credentials enable a greater processing quota and require entering into a separate written agreement. To learn more, Contact Us.

Getting credentials

Developing with the DC Service SDK requires an Adobe-provided credential. To get one, click HERE, and complete the workflow. Be sure to copy and save the credential values to a secure location.

Validity term: The certificate associated with your credential is valid for one year. However, you can simply regenerate a new credential or apply a new certificate to the current credentials from the Document Cloud developer console.

Note

During the credential creation process you’ll be asked to whether you’d like a Personalized Code Sample Download. Choosing Personalized preconfigures the samples with your credential and removes a few steps from your development setup process.

Java

Jump start your development by bookmarking or downloading the following key resources:

Authentication

Once you complete the Getting credentials workflow, a zip file automatically downloads that contains content whose structure varies based on whether you opted to download personalized code samples. The zip file structures are as follows:

  • Personalized Download: A PDFServicesSDK-JavaSamples.zip contains a private.key file and an adobe-dc-services-sdk-java-samples with a preconfigured dc-services-sdk-credentials.json file.

  • Non Personalized Download: A PDFServicesSDK-Credentials.zip contains the private.key file and a dc-services-sdk-credentials.json file.

After downloading the zip, you can either run the samples in the zip directly, or you can replace the dc-services-sdk-credentials.json and private.key files in the sample code with those in the zip.

Example dc-services-sdk-credentials.json file

{
 "client_credentials": {
   "client_id": "<YOUR_CLIENT_ID>",
   "client_secret": "<YOUR_CLIENT_SECRET>"
 },
 "service_account_credentials": {
   "organization_id": "<YOUR_ORGANIZATION_ID>",
   "account_id": "<YOUR_TECHNICAL_ACCOUNT_ID>",
   "private_key_file": "<PRIVATE_KEY_FILE_PATH>"
 }
}

Setup a Java environment

  1. Install Java 8 or above.

  2. Run javac -version to verify your install.

  3. Verify the JDK bin folder is included in the PATH variable (method varies by OS).

  4. Install Maven. You may use your preferred tool; for example:

  • Windows: Example: Chocolatey.

  • Macintosh: Example: brew install maven.

Note

Maven uses pom.xml to fetch dc-services-sdk from the public Maven repository when running the project. The .jar automatically downloads when you build the sample project. Alternatively, you can download the dc-services-sdk.jar file, and configure your own environment.

Option 1: Personalized samples setup

The quickest way to get up and running is to download the personalized code samples during the Getting Credentials workflow. These samples provide everything from ready-to-run sample code, an embedded credential json file, and pre-configured connections to dependencies.

  1. Download the sample project.

  2. Build the sample project with Maven: mvn clean install.

  3. Test the sample code on the command line. Refer to the How Tos for details about running samples. Additional details also reside in the Javadoc.

Option 2: Generic samples setup

If you did not choose Personalized Code Sample Download during the credential setup process:

  1. Download the sample project.

  2. Find and replace dc-services-sdk-credentials.json with the one present in the downloaded zip file.

  3. Find and replace private.key with the one present in the downloaded zip file.

  4. Build the sample project with Maven: mvn clean install.

  5. Test the sample code on the command line. Refer to the How Tos for details about running samples. Additional details also reside in the Javadoc.

Tip

Command line execution is not mandatory. You can import the samples Maven project into your preferred IDE (e.g. IntelliJ/Eclipse) and run the samples from there.

Verifying download authenticity

For security reasons you may wish to confirm the installer’s authenticity. To do so,

  1. After installing the package, navigate to dc-services-sdk-1.0.0.jar.sha1.

  2. Calculate the hash with any 3rd party utility.

  3. Find and open dc-services-sdk-1.0.0.jar.sha1. Note: if you’re using Maven, look in the .m2 directory.

  4. Verify the hash you generated matches the value in the .sha1 file.

5dbcfcef8c5480263331e528e5a800891453e1bf

Logging

Refer to the API docs for error and exception details.

  • For logging, use the slf4j API with a log4j2-slf4j binding.

  • Logging configurations are provided in src/main/resources/log4j2.properties.

  • Specify alternate bindings, if required, in pom.xml.

log4j2.properties file

name=PropertiesConfig
appenders = console

# A sample console appender configuration which clients can change as needed.
rootLogger.level = WARN
rootLogger.appenderRefs = stdout
rootLogger.appenderRef.stdout.ref = STDOUT

appender.console.type = Console
appender.console.name = STDOUT
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = [%-5level] %d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %c{1} - %msg%n

loggers = dcservicessdk,validator,apache

# Change the logging levels as desired. INFO is recommended.
logger.dcservicessdk.name = com.adobe.platform.operation
logger.dcservicessdk.level = INFO
logger.dcservicessdk.additivity = false
logger.dcservicessdk.appenderRef.console.ref = STDOUT

logger.validator.name=org.hibernate
logger.validator.level=WARN

logger.apache.name=org.apache
logger.apache.level=WARN

Test files

The sample files reference input and output files located in the sample project’s /resources/ directory. You can of course modify the files and paths or use your own files.

_images/samplefilesjava.png

Custom projects

While the samples use Maven, you can use your own tools and process.

To build a custom project:

  1. Access the dc-services-sdk.jar in the central Maven repository.

  2. Use your preferred dependency management tool (Ivy, Gradle, Maven), to include the SDK .jar dependency.

  3. Open the dc-services-sdk-credentials.json downloaded when you created your crediential.

  4. Add the Authentication details as described above.

_images/maven.png

.NET

Jumpstart your development by bookmarking or downloading the following key resources:

Prerequisites

The samples project requires the following:

  • .NET Core: version 2.1 or above

  • A build Tool: Either Visual Studio or .NET Core CLI.

Authentication

Once you complete the Getting credentials workflow, you will receive a zip file with content whose structure varies based on whether you opted to download personalized code samples. The zip file structures are as follows:

  • Personalized Download: A PDFServicesSdk-NetSamples.zip contains a private.key file and an Adobe-DC.Services.SDK.NET.Samples directory. Each sample directory contains the sample code as well as a preconfigured dc-services-sdk-credentials.json file.

  • Non Personalized Download: A PDFServicesSdk-Credentials.zip contains the private.key file and unconfigured dc-services-sdk-credentials.json file.

After downloading the zip, you can either run the samples in the zip directly, or you can replace the dc-services-sdk-credentials.json and private.key files in the sample code with those in the zip.

Example dc-services-sdk-credentials.json file

{
 "client_credentials": {
   "client_id": "<YOUR_CLIENT_ID>",
   "client_secret": "<YOUR_CLIENT_SECRET>"
 },
 "service_account_credentials": {
   "organization_id": "<YOUR_ORGANIZATION_ID>",
   "account_id": "<YOUR_TECHNICAL_ACCOUNT_ID>",
   "private_key_file": "<PRIVATE_KEY_FILE_PATH>"
 }
}

Set up a NET environment

Running any sample or custom code requires the following:

  1. Download and install the .NET SDK.

Note

The Adobe.DocumentCloud.Services Nuget package automatically downloads when you build the sample project.

Option 1: Personalized samples setup

The quickest way to get up and running is to download the personalized code samples during the Getting Credentials workflow. These samples provide everything from ready-to-run sample code, an embedded credential json file, and pre-configured connections to dependencies.

  1. Extract the downloaded PDFServicesSdk-NetSamples.zip.

  2. From the samples directory, build the sample project: dotnet build.

  3. Test the sample code on the command line. Refer to the How Tos for details about running samples. Additional details also reside in the .NET API docs.

Option 2: Generic samples setup

If you did not choose Personalized Code Sample Download during the credential setup process:

  1. Clone or download the samples project.

  2. Find and replace all occurrences of dc-services-sdk-credentials.json and private.key files with the ones present in your PDFServicesSDK-Credentials.zip file.

  3. From the samples directory, build the sample project: dotnet build.

  4. Test the sample code on the command line. Refer to the How Tos for details about running samples. Additional details also reside in the .NET API docs.

Verifying download authenticity

For security reasons you may wish to confirm the installer’s authenticity. To do so,

  1. After installing the Nuget package, navigate to the .nuget directory.

  2. Find and open adobe.documentcloud.services.1.0.0.nupkg.sha512.

  3. Verify the hash in the downloaded file matches the value published here.

sKUFj/Q6yHtpYxhDMq5aQVYuCb7j7N5SGSogHtW3QvlvOZKhlwgw00I28MYFelFu9wYfhxizLuldTg24HSYukw==

Logging

Refer to the API docs for error and exception details.

The .NET SDK uses LibLog as a bridge between different logging frameworks. Log4net is used as a logging provider in the sample projects and the logging configurations are provided in log4net.config. Add the configuration for your preferred provider and set up the necessary appender as required to enable logging.

log4net.config file

<log4net>
 <root>
   <level value="INFO" />
   <appender-ref ref="console" />
 </root>
 <appender name="console" type="log4net.Appender.ConsoleAppender">
   <layout type="log4net.Layout.PatternLayout">
     <conversionPattern value="%date %level %logger - %message%newline" />
   </layout>
 </appender>
</log4net>

Test files

Refer to each sample directory for the requisite input/output files.

_images/samplefilesnet.png

Custom projects

While building the sample project automatically downloads the Nuget package, you can do it manually if you wish to use your own tools and process.

  1. Go to https://www.nuget.org/packages/Adobe.DocumentCloud.Services/1.0.0

  2. Download the latest package.

_images/nuget.png

Node.js

Jumpstart your development by bookmarking or downloading the following key resources:

Authentication

Once you complete the Getting credentials workflow, you will receive a zip file with content whose structure varies based on whether you opted to download personalized code samples. The zip file structures are as follows:

  • Personalized Download: A PDFServicesSdk-Node.jsSamples.zip contains a private.key file and an adobe-dc-services-sdk-node-samples directory. Each sample directory contains the sample code as well as a preconfigured dc-services-sdk-credentials.json file.

  • Non Personalized Download: A PDFServicesSdk-Credentials.zip contains the private.key file and unconfigured dc-services-sdk-credentials.json file.

After downloading the zip, you can either run the samples in the zip directly, or you can replace the dc-services-sdk-credentials.json and private.key files in the sample code with those in the zip.

Example dc-services-sdk-credentials.json file

{
 "client_credentials": {
   "client_id": "<YOUR_CLIENT_ID>",
   "client_secret": "<YOUR_CLIENT_SECRET>"
 },
 "service_account_credentials": {
   "organization_id": "<YOUR_ORGANIZATION_ID>",
   "account_id": "<YOUR_TECHNICAL_ACCOUNT_ID>",
   "private_key_file": "<PRIVATE_KEY_FILE_PATH>"
 }
}

Set up a Node.js environment

Running any sample or custom code requires the following steps:

  1. Install Node.js 10.0 or higher.

Note

The @adobe/dc-services-node-sdk npm package automatically downloads when you build the sample project.

npm install --save @adobe/dc-services-node-sdk

Option 1: Personalized samples setup

  1. Extract the downloaded PDFServicesSdk-Node.jsSamples.zip.

  2. From the samples root directory, run npm install.

Option 2: Generic samples setup

If you did not choose Personalized Code Sample Download during the credential setup process:

  1. Download the sample project.

  2. Find and replace all occurrences of dc-services-sdk-credentials.json and private.key files with the ones present in your PDFServicesSDK-Credentials.zip file.

  3. From the samples root directory, run npm install.

  4. Test the sample code on the command line. Refer to the How Tos for details about running samples. Additional details also reside in the node.js API docs.

Verifying download authenticity

For security reasons you may wish to confirm the installer’s authenticity. To do so,

  1. After installing the package, find and open package.json.

  2. Find the “_integrity” key.

  3. Verify the hash in the downloaded file matches the value published here.

sha512-9s/DNCiRrIBGRUyR2/daICFjgJmGw/faZynEUKmjJf3DddECNtqevLU26i/1xN9fX4KVKH4Tlh/b8XuhBOdwrg==

Logging

Refer to the API docs for error and exception details.

The SDK uses the use the log4js API for logging. During execution, the SDK searches for config/dc-sdk-log4js-config.json in the working directory and reads the logging properties from there. If you do not provide a configuration file, the default logging logs INFO to the console. Customize the logging settings as needed.

log4j2.properties file

{
 "appenders": {
   "consoleAppender": {
           "_comment": "A sample console appender configuration. Customize the logging implementation as needed.",
     "type": "console",
     "layout": {
       "type": "pattern",
       "pattern": "%d:[%p]: %m"
     }
   }
 },
 "categories": {
   "default": {
     "appenders": [
       "consoleAppender"
           ],
           "_comment": "INFO is the minimum recommended log level for the DC SDK.",
     "level": "info"
   }
 }
}

Test files

Refer to each sample project’s resource directory for the requisite input/output files.

_images/nodetestfiles.png

Custom projects

While building the sample project automatically downloads the Node package, you can do it manually if you wish to use your own tools and process.

  1. Go to https://www.npmjs.com/package/@adobe/dc-services-node-sdk

  2. Download the latest package.

_images/node.png