Quickstarts¶

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: The samples download zip contains a private.key file and an adobe-dc-pdf-tools-sdk-java-samples with a preconfigured pdftools-api-credentials.json file.

• Non Personalized Download: The samples download zip contains the private.key file and a pdftools-api-credentials.json file.

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

Example pdftools-api-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.

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 the .jar.sha1 file.

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

3. Find and open PDF Tools sha1 file. Note: if you’re using Maven, look in the .m2 directory.

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

6825fdc31fca1fae8b1bec3f6592ad543a332c59

Logging¶

Refer to the API docs for error and exception details.

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

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

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

log4js.properties file

       name=PropertiesConfig
       appenders = console

       # A sample console appender configuration, Clients can change as per their logging implementation
       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 = pdftoolssdk,validator,apache

       # Change the logging levels as per need. INFO is recommended for pdftools-sdk
       logger.pdftoolssdk.name = com.adobe.platform.operation
       logger.pdftoolssdk.level = INFO
       logger.pdftoolssdk.additivity = false
       logger.pdftoolssdk.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.

Custom projects¶

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

To build a custom project:

1. Access the .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 pdftools-api-credentials.json downloaded when you created your crediential.

4. Add the Authentication details as described above.

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: The samples download zip contains a private.key file and an adobe-DC.PDFTools.SDK.NET.Samples directory. Each sample directory contains the sample code as well as a preconfigured pdftools-api-credentials.json file.

• Non Personalized Download: The samples download zip contains the private.key file and unconfigured pdftools-api-credentials.json file.

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

Example pdftools-api-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.

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 the .sha512 file.

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

4eMv0Sd8kjvgQSCNpKIZBphFmaRscX/HK5gcuomqjI+DfIMxgAqmunPHbOLY4jc6jELosMfjXgfs90a8dh4yEw==

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.

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.adobe.com/go/pdftoolsapi_net_nuget.

2. Download the latest package.

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: The samples download.zip contains a private.key file and an adobe-dc-pdf-tools-sdk-node-samples directory. Each sample directory contains the sample code as well as a preconfigured pdftools-api-credentials.json file.

• Non Personalized Download: The samples download zip contains the private.key file and unconfigured pdftools-api-credentials.json file.

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

Example pdftools-api-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.13.0 or higher.

npm install --save @adobe/documentservices-pdftools-node-sdk

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-mMWLR5LsDsTRLjbZgNtXDPs0y9VDGurZ+67QnMaGpOsZiR8iR7WujoHm2P3b7B8sDOFVNwly+/LUdrjBpqZi1A==

Logging¶

Refer to the API docs for error and exception details.

The SDK uses the log4js API for logging. During execution, the SDK searches for config/pdftools-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.

log4js.properties file

 {
   "appenders": {
     "consoleAppender": {
             "_comment": "A sample console appender configuration, Clients can change as per their logging implementation",
       "type": "console",
       "layout": {
         "type": "pattern",
         "pattern": "%d:[%p]: %m"
       }
     }
   },
   "categories": {
     "default": {
       "appenders": [
         "consoleAppender"
             ],
             "_comment": "Change the logging levels as per need. info is recommended for documentservices-pdftools-node-sdk",
       "level": "info"
     }
   }
 }

Test files¶

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

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/documentservices-pdftools-node-sdk

2. Download the latest package.