Develop a custom application develop

Before you begin to develop a custom application:

Create a custom application create-custom-application

Make sure to have Adobe aio-cli installed locally.

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

Add credentials 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 developer-tool-credentials

The tool for developers to evaluate custom apps using the Asset Compute service necessitates the use of a cloud storage container. This container is essential to store test files and for the reception and presentation of renditions produced by the apps.

Make sure to have access to a supported cloud storage container. This container is used collectively by various developers for different projects whenever necessary.

Add credentials to ENV file add-credentials-env-file

Insert the subsequent credentials for the development tool into the .env file. The file is located at the root of your App Builder project:

Execute the application run-custom-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 starts the development tool on your local computer. 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 try-sample

The following are example custom applications:

Template custom application 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 call-external-api

In the application code, you can make external API calls to help with application processing. An example application file that invokes an 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 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 an application file accessing a custom parameter is the following:

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 authentication-authorization-support

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

Access other Adobe APIs access-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 pass-credentials-for-tp

To handle credentials for other external services, pass them as default parameters on the actions. They are automatically encrypted in transit. For more information, see creating actions in the Adobe I/O 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.

While developing, you can assign the value in the local .env file. The reason is because aio automatically imports environment variables from .env files, along with those variables set by the initiating shell. In this example, the .env file looks like the following:

#...
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 sizing-workers

An application runs 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 extensive processing done by Asset Compute applications, you must 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 that it takes to download the source, process the file and upload the rendition. If an action times out, that is, it 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 must be downloaded first. Processing is often resource-intensive and then the resulting renditions are uploaded again.

You can specify the memory allocated to an action container in megabytes using the memorySize parameter. Currently, this parameter 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 not to 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 setting 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. The default memorySize in the runtime is set to 200 MB, ideal for smaller App Builder actions. For Asset Compute applications, this default may be excessive due to their heavier local processing and disk usage. Some applications, depending on their implementation, might also not work well with concurrent activity. The Asset Compute SDK ensures that 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.