Internals of a custom application

Last update: June 27, 2024

CREATED FOR:

  • Developer

Use the following illustration to understand the end-to-end workflow when a digital asset is processed using a custom application by a client.

Custom application workflow

Figure: Steps involved when processing an asset using Adobe Asset Compute Service.

Registration

The client must call /register once before the first request to /process so it can set up and retrieve the journal URL for receiving Adobe I/O Events Events for Adobe Asset Compute.

curl -X POST \
  https://asset-compute.adobe.io/register \
  -H "x-ims-org-id: $ORG_ID" \
  -H "x-gw-ims-org-id: $ORG_ID" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "x-api-key: $API_KEY"

The @adobe/asset-compute-client JavaScript library can be used in NodeJS applications to handle all the necessary steps from registration, processing to asynchronous event handling. For more information on the required headers, see Authentication and Authorization.

Processing

The client sends a processing request.

curl -X POST \
  https://asset-compute.adobe.io/process \
  -H "x-ims-org-id: $ORG_ID" \
  -H "x-gw-ims-org-id: $ORG_ID" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "x-api-key: $API_KEY" \
  -d "<RENDITION_JSON>

The client is responsible for correctly formatting the renditions with pre-signed URLs. The @adobe/node-cloud-blobstore-wrapper JavaScript library can be used in NodeJS applications to pre-sign URLs. Currently the library only supports Azure Blob Storage and AWS S3 Containers.

The processing request returns a requestId that can be used for polling Adobe I/O Events.

A sample custom application processing request is below.

{
    "source": "https://www.adobe.com/some-source-file.jpg",
    "renditions" : [
        {
            "worker": "https://my-project-namespace.adobeioruntime.net/api/v1/web/my-namespace-version/my-worker",
            "name": "rendition1.jpg",
            "target": "https://some-presigned-put-url-for-rendition1.jpg",
        }
    ],
    "userData": {
        "my-asset-id": "1234567890"
    }
}

The Asset Compute Service sends the custom application rendition requests to the custom application. It uses an HTTP POST to the provided application URL, which is the secured web action URL from App Builder. All requests use the HTTPS protocol to maximize data security.

The Asset Compute SDK used by a custom application handles the HTTP POST request. It also handles downloading of the source, uploading renditions, sending Adobe I/O Events and error handling.

Application code

Custom code only needs to provide a callback that takes the locally available source file (source.path). The rendition.path is the location to place the final result of an asset processing request. The custom application uses the callback to turn the locally available source files into a rendition file using the name passed in (rendition.path). A custom application must write to rendition.path to create a rendition:

const { worker } = require('@adobe/asset-compute-sdk');
const fs = require('fs').promises;

// worker() is the entry point in the SDK "framework".
// The asynchronous function defined is the rendition callback.
exports.main = worker(async (source, rendition) => {

    // Tip: custom worker parameters are available in rendition.instructions.
    console.log(rendition.instructions.name); // should print out `rendition.jpg`.

    // Simplest example: copy the source file to the rendition file destination so as to transfer the asset as is without processing.
    await fs.copyFile(source.path, rendition.path);
});

Download source files

A custom application only deals with local files. The Asset Compute SDK handles the downloading of the source file.

Rendition creation

The SDK calls an asynchronous rendition callback function for each rendition.

The callback function has access to the source and rendition objects. The source.path already exists and is the path to local copy of source file. The rendition.path is the path where the processed rendition must be stored. Unless the disableSourceDownload flag is set, the application must use exactly the rendition.path. Otherwise, the SDK cannot locate or identify the rendition file and fails.

The over simplification of the example is done to illustrate and focus on the anatomy of a custom application. The application just copies the source file to the rendition destination.

For more information about the rendition callback parameters, see Asset Compute SDK API.