Assets Proxy Development

Last update: May 3, 2023

CREATED FOR:

  • Admin
  • Developer
CAUTION
AEM 6.4 has reached the end of extended support and this documentation is no longer updated. For further details, see our technical support periods. Find the supported versions here.

Adobe Experience Manager Assets uses a proxy to distribute processing for certain tasks.

A proxy is a specific (and sometimes separate) Experience Manager instance that uses proxy workers as processors responsible for handling a job and creating a result. A proxy worker can be used for a wide variety of tasks. In the case of an Experience Manager Assets proxy this can be used for loading assets for rendering within Experience Manager Assets. For example, the IDS proxy worker uses an InDesign Server to process files for use in Experience Manager Assets.

When the proxy is a separate Experience Manager instance this helps reduce the load on the Experience Manager authoring instance(s). By default, Experience Manager Assets executes the asset processing tasks in the same JVM (externalized via Proxy) to reduce the load on the Experience Manager authoring instance.

Proxy (HTTP Access)

A proxy is available via the HTTP Servlet when it is configured to accept processing jobs at: /libs/dam/cloud/proxy. This servlet creates a sling job from the posted parameters. This is then added to the proxy job queue and connected to the appropriate proxy worker.

Supported Operations

  • job

    Requirements: the parameter jobevent must be set as a serialized value map. This is used to create an Event for a job processor.

    Result: Adds a new job. If successful, a unique job id is returned.

curl -u admin:admin -F":operation=job" -F"someproperty=xxxxxxxxxxxx"
    -F"jobevent=serialized value map" http://localhost:4502/libs/dam/cloud/proxy

  • result

    Requirements: the parameter jobid must be set.

    Result: Returns a JSON representation of the result Node as created by the job processor.

curl -u admin:admin -F":operation=result" -F"jobid=xxxxxxxxxxxx"
    http://localhost:4502   /libs/dam/cloud/proxy

  • resource

    Requirements: the parameter jobid must be set.

    Result: Returns a resource associated with the given job.

curl -u admin:admin -F":operation=resource" -F"jobid=xxxxxxxxxxxx"
    -F"resourcePath=something.pdf" http://localhost:4502/libs/dam/cloud/proxy

  • remove

    Requirements: the parameter jobid must be set.

    Results: Removes a job if found.

curl -u admin:admin -F":operation=remove" -F"jobid=xxxxxxxxxxxx"
    http://localhost:4502/libs/dam/cloud/proxy

Proxy Worker

A proxy worker is a processor responsible for handling a job and creating a result. Workers reside on the proxy instance and must implement sling JobProcessor to be recognized as a proxy worker.

NOTE
The worker must implement sling JobProcessor to be recognized as a proxy worker.

Client API

JobService is available as an OSGi service that provides methods to create jobs, remove jobs and to get results from those jobs. The default implementation of this service (JobServiceImpl) uses the HTTP client to communicate with the remote proxy servlet.

The following is an example of API usage:

@Reference
 JobService proxyJobService;

 // to create a new job
 final Hashtable props = new Hashtable();
 props.put("someproperty", "some value");
 props.put(JobUtil.PROPERTY_JOB_TOPIC, "myworker/job"); // this is an identifier of the worker
 final String jobId = proxyJobService.addJob(props, new Asset[]{asset});

 // to check status (returns JobService.STATUS_FINISHED or JobService.STATUS_INPROGRESS)
 int status = proxyJobService.getStatus(jobId)

 // to get the result
 final String jsonString = proxyJobService.getResult(jobId);

 // to remove job and cleanup
 proxyJobService.removeJob(jobId);

Cloud Service Configurations

NOTE
Reference documentation for the proxy API is available under com.day.cq.dam.api.proxy.

Both proxy and proxy worker configurations are available via cloud services configurations as accessible from the Experience Manager Assets Tools console or under /etc/cloudservices/proxy. Each proxy worker is expected to add a node under /etc/cloudservices/proxy for worker specific configuration details (for example, /etc/cloudservices/proxy/workername).

NOTE

The following is an example of API usage:

@Reference(policy = ReferencePolicy.STATIC)
 ProxyConfig proxyConfig;

 // to get proxy config
 Configuration cloudConfig = proxyConfig.getConfiguration();
 final String value = cloudConfig.get("someProperty", "defaultValue");

 // to get worker config
 Configuration cloudConfig = proxyConfig.getConfiguration("workername");
 final String value = cloudConfig.get("someProperty", "defaultValue");

Developing a Customized Proxy Worker

The IDS proxy worker is an example of a Experience Manager Assets proxy worker that is already provided out-of-the-box to outsource the processing of Indesign assets.

You can also develop and configure your own Experience Manager Assets proxy worker to create a specialized worker to dispatch and outsource your Experience Manager Assets processing tasks.

Setting up your own custom proxy worker requires you to:

  • Set up and implement (using Sling eventing):

    • a custom job topic
    • a custom job event handler

  • Then use the JobService API to:

    • dispatch your custom job to the proxy
    • manage your job

  • If you want to use the proxy from a workflow, you must implement a custom external step using the WorkflowExternalProcess API and the JobService API.

The following diagram and steps detail how to proceed:

chlimage_1-249

NOTE
In the following steps, Indesign equivalents are indicated as reference examples.

  1. A Sling job is used, so you need to define a job topic for your use case.

    As an example, see IDSJob.IDS_EXTENDSCRIPT_JOB for the IDS proxy worker.

  2. The external step is used to trigger the event and then wait until that is finished; this is done by polling on the id. You must develop your own step to implement new functionality.

    Implement a WorkflowExternalProcess, then use the JobService API and your job topic to prepare a job event and dispatch it to the JobService (an OSGi service).

    As an example, see INDDMediaExtractProcess.java for the IDS proxy worker.

  3. Implement a job handler for your topic. This handler requires development so that it performs your specific action and is considered to be the worker implementation.

    As an example, see IDSJobProcessor.java for the IDS proxy worker.

  4. Make use of ProxyUtil.java in dam-commons. This allows you to dispatch jobs to workers using the dam proxy.

NOTE
What the Experience Manager Assets proxy framework does not provide out-of-the-box is the pool mechanism.
The InDesign integration allows the access of a pool of indesign servers (IDSPool). This pooling is specific to Indesign integration and not part of the Experience Manager Assets proxy framework.
NOTE
Synchronization of Results:
With n instances using the same proxy, the processing result stays with the proxy. It is the job of the client (Experience Manager Author) to request the result using the same unique job id as given to the client on job creation. The proxy simply gets the job done and keeps the result ready to be requested.
Previous page
Next page

Experience Manager


The Perfect Blend: A New Era of Collaboration with AEM and Workfront

Adobe Customer Success Webinars

Wednesday, Apr 2, 5:00 PM UTC

Explore how Adobe Experience Manager and Workfront integrate to help teams move from ideation to delivery without the usual bottlenecks, ensuring content is organized, on-brand, and ready to go live faster.

Register

Connect with Experience League at Summit!

Get front-row access to top sessions, hands-on activities, and networking—wherever you are!

Learn more

Register now