Develop a custom application

Before you begin to develop a custom application:

Create a custom application

Make sure to have the Adobe I/O CLI installed locally.

See example custom applications for examples and ideas for custom applications.

Add credentials

As you log in when creating the application, most of the App Builder credentials get collected in your ENV file. However, using the developer tool requires additional credentials.

Developer tool storage credentials

The developer tool used to test custom applications with the actual Asset Compute service requires a cloud storage container for hosting test files and for receiving and displaying renditions generated by applications.

Make sure to have access to a supported cloud storage container. This container can be shared by multiple developers across different projects as needed.

Add credentials to ENV file

Add the following credentials for the developer tool to the ENV file in the root of your App Builder project:

Execute the application

Before executing the application with the Asset Compute Developer Tool, properly configure the credentials.

To run the application in the developer tool, use aio app run command. It deploys the action to Adobe I/O Runtime and start the development tool on your local machine. This tool is used to test application requests during development. Here is an example rendition request:

"renditions": [
    {
        "worker": "https://1234_my_namespace.adobeioruntime.net/api/v1/web/example-custom-worker-master/worker",
        "name": "image.jpg"
    }
]

See here how to test and debug your application. When you are finished developing your custom application, deploy your custom application.

Try the sample application provided by Adobe

The following are example custom applications:

Template custom application

The worker-basic is a template application. It generates a rendition by simply copying the source file. The content of this application is the template received when choosing Adobe Asset Compute in the creation of the aio app.

The application file, worker-basic.js uses the asset-compute-sdk to download the source file, orchestrate each rendition processing, and upload the resulting renditions back to cloud storage.

The renditionCallback defined inside the application code, is where to perform all the application processing logic. The rendition callback in worker-basic simply copies the source file contents to the rendition file.

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

exports.main = worker(async (source, rendition) => {
    // copy source to rendition to transfer 1:1
    await fs.copyFile(source.path, rendition.path);
});

Call an external API

In the application code, you can make external API calls to help with application processing. An example application file invoking external API is below.

exports.main = worker(async function (source, rendition) {

    const response = await fetch('https://adobe.com', {
        method: 'GET',
        Authorization: params.AUTH_KEY
    })
});

For example, the worker-animal-pictures makes a fetch request to a static URL from Wikimedia using the node-httptransfer library.

Pass custom parameters

You can pass custom defined parameters through the rendition objects. They can be referenced inside the application in rendition instructions. An example of a rendition object is:

"renditions": [
    {
        "worker": "https://1234_my_namespace.adobeioruntime.net/api/v1/web/example-custom-worker-master/worker",
        "name": "image.jpg",
        "my-custom-parameter": "my-custom-parameter-value"
    }
]

An example of a application file accessing custom parameter is:

exports.main = worker(async function (source, rendition) {

    const customParam = rendition.instructions['my-custom-parameter'];
    console.log('Custom paramter:', customParam);
    // should print out `Custom parameter: "my-custom-parameter-value"`
});

The example-worker-animal-pictures passes a custom parameter animal to determine which file to fetch from Wikimedia.

Authentication and authorization support

By default, Asset Compute custom applications come with Authorization and Authentication checks for App Builder project. This is enabled by setting the require-adobe-auth annotation to true in the manifest.yml.

Access other Adobe APIs

Add the API services to the Asset Compute Console workspace created in setup. These services are part of the JWT access token generated by Asset Compute Service. The token and other credentials are accessible inside the application action params object.

const accessToken = params.auth.accessToken; // JWT token for Technical Account with entitlements from the console workspace to the API service
const clientId = params.auth.clientId; // Technical Account client Id
const orgId = params.auth.orgId; // Experience Cloud Organization

Pass credentials for third-party systems

To handle credentials for other external services, pass these as default parameters on the actions. These are automatically encrypted in transit. For more information, see creating actions in Runtime developer guide. Then set them using environment variables during deployment. These parameters can be accessed in the params object inside the action.

Set the default parameters inside the inputs in the manifest.yml:

packages:
  __APP_PACKAGE__:
    actions:
      worker:
        function: 'index.js'
        runtime: 'nodejs:10'
        web: true
        inputs:
           secretKey: $SECRET_KEY
        annotations:
          require-adobe-auth: true

The $VAR expression reads the value from an environment variable named VAR.

During development, the value can be set in the local ENV file as aio automatically reads environment variables from ENV files in addition to the variables set from the invoking shell. In this example, the ENV file looks like:

#...
SECRET_KEY=secret-value

For production deployment one might set the environment variables in the CI system, for example using secrets in GitHub Actions. Lastly, access the default parameters inside the application as such:

const key = params.secretKey;

Sizing applications

An application executes in a container in Adobe I/O Runtime with limits that can be configured through the manifest.yml:

    actions:
      myworker:
        function: /actions/myworker/index.js
        limits:
          timeout: 300000
          memorySize: 512
          concurrency: 1

Due to the more extensive processing typically done by Asset Compute applications, it is more likely one has to adjust these limits for optimal performance (large enough to handle binary assets) and efficiency (not wasting resources due to unused container memory).

The default timeout for actions in Runtime is a minute but it can be increased by setting the timeout limit (in milliseconds). If you expect to process larger files, increase this time. Consider the total time it takes to download the source, process the file and upload the rendition. If an action times out, i.e. does not return the activation before the specified timeout limit, Runtime discards the container and not reuse it.

Asset compute applications by nature tend to be network and disk Input or output bound. The source file has to be downloaded first, processing is often resource-intensive and then the resulting renditions are uploaded again.

The memory available to an action container is specified by memorySize in MB. Currently this also defines how much CPU access the container gets, and most importantly it is a key element of the cost of using Runtime (larger containers cost more). Use a larger value here when your processing requires more memory or CPU but be careful to not waste resources as the larger the containers are, the lower the overall throughput is.

Furthermore, it is possible to control action concurrency within a container using the concurrency setting. This is the number of concurrent activations a single container (of the same action) gets. In this model, the action container is like a Node.js server receiving multiple concurrent requests, up to that limit. If not set, the default in Runtime is 200, which is great for smaller App Builder actions, but usually too large for Asset Compute applications given their more intensive local processing and disk activity. Some applications, depending on their implementation, might also not work well with concurrent activity. The Asset Compute SDK ensures activations are separated by writing files to different unique folders.

Test applications to find the optimal numbers for concurrency and memorySize. Larger containers = higher memory limit could allow for more concurrency but could also be wasteful for lower traffic.