DC SDK for JavaScript (NodeJS)

Overview

The samples are nodejs scripts that will:

  • Upload a file
  • Perform conversions or other PDF actions
  • Download the result

Configuration

nodejs must be up to date. Version 4.4 LTS or higher is recommended. To check the version, run the command:

node -v

To get started, navigate to the nodejs samples directory, js/samples/. Install/update nodejs (and npm) from: https://nodejs.org To install dependencies for the NodeJS samples, run:

npm install

To install the adobe-dcapi package in other contexts, run:

npm install adobe-dcapi.tgz

The skeleton configuration to run the sample is defined in ../../config/default.json. Users will need to update this file with their own registration details including a default-key.pem file.

The samples

exportpdf

Upload a PDF file and convert it to another file format. This sample also demonstrates how to upload a file by streaming content. It also takes advantage of export's OCR capability while converting to docx format.

node exportpdf [config-file] [pdf-file-to-convert]

createpdf

Upload a file and convert it to PDF. This sample converts from an in-memory text representation or from a file provided on the command line. A 'do_ocr' option will perform OCR upon conversion.

node createpdf [config-file] [file-to-convert] [do_ocr]

createpdf_from_html

Upload a ZIP file of HTML collateral and convert to PDF. This sample also:

  • demonstrates how to use the getSchema() API
  • for upload, reads files into memory and transmits them in base64 format
    node createpdf_from_html [config-file] [zip-file-to-convert]
    

add_password

This sample uploads a PDF file and encrypts with password encryption.

node add_password config-file pdf-file password

do_ocr

This sample uploads a PDF file and performs OCR on it.

node do_ocr config-file [pdf-file-to-ocr]

organize_pages

This is the most complex sample. It accepts a list of files. It uploads each file and if not a PDF, will convert to PDF. Then for the set of uploaded/converted files will interleave their first 10 pages, rotating at various angles.

node organize_pages  [input-file [input-file...]]

Running the samples

The default config file relative to samples is ../../config/default.json. Test files used as input to the samples can be found in ../../test-files.

When each sample has run to completion, it will open an HTML page with a log of all the http/API requests and responses. This log is useful both in understanding how DCAPI works, and for debugging issues if the sample fails.

Sample Details:

The overall sequence of requests in the sample:

  1. Retrieve an authentication token.
  2. Call /discovery to get API URI details.
  3. Retrieve options for this operation if applicable.
  4. Upload a file.
  5. Start a job. e.g. Export from PDF, Create PDF, add password, organize pages
  6. Poll for job completion.
  7. When complete, request a URI for downloading the result.
  8. Download the result.

This is easily seen by looking at the sequence of calls at the bottom of the samples/createpdf.js:

new API(config).promise()
    .then(getOptions)
    .then(step1upload)
    .then(step2create)
    .then(step3status)
    .then(step4downloadUri)
    .then(step5downloadFile)
    .done(step6final, fail);

Every step will return a promise object (most of them as a result of an XHR request). The sequence above chains the requests and executes them sequentially.

The sample makes use of the require('adobe-dcapi').API module that factors out some common operations.

Every DCAPI application must begin by retrieving an authentication token. This is handled internally by an IdentityAccess handler using the related config/default.json or similar file. The require('adobe-dcapi').IdentityAccess token can be replaced if necessary before constructing a new API() object. The authentication token is needed for every subsequent API call.

The entry point to the API is /discovery. A GET on /discovery will return a list of all available resources and operations. This GET operation is performed automatically by the API() constructor. The results of /discovery are added as properties to the resulting api object.

API Functions/Members

api.call(operation, parameters)

api.call() accepts a map of parameters to control the HTTP request. Most of the parameters are keys into the /discovery result to select operation details. Look at the code comments inside callApi() in adobe-dc-api.js for details. The return value is a promise object that will be resolved with a result map:

{
    status: http status value
    headers: http response headers
    content: result data
}

api.getFinalURI(operation, options)

api.getFinalURI() prepares a final URI based on input parameters. Applications will normally use this method to generate URIs that can be used as a src attribute on HTML elements such as img or iframe. Look at the code comments inside getFinalUri() in adobe-dc-api.js for details.

The return value is a string containing the final URI.

api.formDataPart(operation, options)

For API requests that upload multipart data, this is a convenience method to format the parts of the package, using the form_data parameters from the /discovery result. Look at the code comments inside formDataPart() in adobe-dc-api.js for details.

The return value is a string with the formatted data.

api.getSchema(schemaName)

api.getSchema() will retrieve the JSON schema specified in the schemaName parameter. Pass in the schema-name index used in the "accept" or "content_type" objects for the specific resource entry in discovery, e.g. api.getSchema(“new_asset_job_v1.json”). The return value is a promise object that will be resolved with a map of the JSON schema.

api.promise()

The return value is a promise object that will be resolved once the API object has completed its startup requests.

api.closeHttpLog()

If logging is enabled, api.closeHttpLog() must be called at the end of a session in order to complete the logging session.

api.openHttpLog(filename[, loggerImplementation])

If logging is enabled, it's normally done with the API constructor. But it can also be started later with a call to api.openHttpLog(). If a loggerImplementation is not supplied, the default html-based logging will be used.

Occasionally a client may need to call AdobeDC.http.call() directly. The parameters are also documented internally.