Extending the functionality of Assets Server using extension points

The default features and functionality of Assets Server and its client applications make it possible to perform a multitude of tasks.

However, each working environment is different and requires specific features to be available and specific tasks to be performed.

With Assets Server being an open system, the basic functionality of Assets Server and its clients can be extended through the use of extension points such as plug-ins and APIs. This way, repetitive tasks can be automated, external systems can be integrated, and workflows can be customized.

Choosing the right implementation for a particular scenario can be challenging though.

This article explains the available integration options and advises on what to use in the various integration scenarios.

Discussed are:

• Plug-ins
• APIs
• Performance considerations

Example scenarios

The following table shows some example scenarios and the extension point type that can best be used for it.

#	Scenario	Extension point type
1	Integrating a process that requires user interaction.	Client application plug-ins
2	Triggering a background process when Assets Server data is changed such as when importing an asset or changing metadata.	API Webhooks
3	Automating background jobs at a scheduled interval.	Scheduled plug-ins
4	Making modifications to Assets Server data from a plug-in or external application.	REST APIs
5	Extending the Assets Server API with custom APIs.	API plug-ins

Plug-ins

The following types of plug-ins are available:

• Client plug-ins extend the functionality of client applications by adding custom UI elements.
• Scheduled plug-ins periodically run background jobs.
• API (proxy) plug-ins extend the Assets Server API with custom functionality.

Client plug-ins

Client plug-ins make it possible to provide end users with additional (custom) functionality in the client applications Assets and the Brand portal.

The aim of adding such functionality is to improve the workflow and increase efficiency, resulting in a better (more standardized) working environment in which the user can perform tasks quicker with less risk of making errors.

Examples: Managing copyright information of images can be easily and efficiently managed by using a plug-in which stamps multiple files with a predefined set of metadata in one action. This way, the user does not have to repeatedly add metadata to each file with the risk of making mistakes. In a scenario where Assets Server is part of a bigger ecosystem where it needs to interact with other systems, plug-ins can help users with exporting assets to an external system such as a Web CMS or a video streaming platform.

Client plug-in types

A client plug-in is basically a small Web application consisting of HTML, JavaScript, and CSS files.

It can be hosted in Assets Server itself or on an external Web server. Configuration options are available for defining how it is triggered and how it is displayed.

A distinction is made between the following types of client plug-ins:

• Action plug-ins trigger a specific action. They are displayed in one of the following ways:
• As a dialog
• As a fullscreen overlay
• In a new Web browser tab

• Panel plug-ins appear as a panel in the application.

Choosing the plug-in type to use

Which plug-in type to use depends on the action that needs to be performed and how users need to interact with that action.

• Dialogs are best used for quick actions such as simple export actions or custom steps when importing assets. Because the rest of the application is not accessible as long as the dialog window is open, users do not lose the context of their current work (such as files that are selected, the scroll position in a window, and so on).

• Fullscreen overlays are useful when all available screen space is needed while not leaving the context of Assets Server, such as when creating an image contact sheet.

• Plug-ins that open in a new Web browser tab can be useful for loading external Web sites that do not allow to be embedded in another Web site (such as Assets or the Brand portal), typically because of security considerations. Opening such Web sites from within Assets or the Brand portal makes sure that users are aware of these sites and can easily access them.

• Panel plug-ins are added as regular panels in Assets and can be accessed any time the user needs them. They are used by first selecting one or more assets and subsequently performing some kind of action in the panel.

Examples: Updating metadata (see the Metadata stamp panel). Showing contextual information based on the currently selected assets such as product information from an external PIM system.

Usage

Client plug-ins work best for processes where user interaction is required. Such processes should typically be short so that users are not blocked from doing their work.

Long-running jobs can best be offloaded as an asynchronous background process, or run periodically by using a scheduled plug-in (see next section) which performs the job as a background process.

For more information, see:

• Extending the Assets Server functionality with plug-ins
• Adding custom functionality to Assets Server by using Action plug-ins
• Assets Server sample plug-ins
• Adding custom functionality to Assets by using Panel plug-ins

Scheduled plug-ins

Scheduled plug-ins are used for automating background jobs such as importing assets from a feed or hot folder, automatically removing images when they exceed the license use date, and so on.

Scheduled plug-ins can be executed manually but are typically scheduled at an hourly or daily interval. You can make use of the sample plug-ins that are bundled with Assets Server or develop your own scheduled plug-in.

Usage

Scheduled plug-ins are useful for jobs that run at a low interval such as automatically removing assets for which the license date has expired. In this specific case, the plug-in needs to remove all assets which have their licenseEndDate metadata field set to a date in the past. Processes like these are typically run once a day such as shortly after midnight.

Scheduled plug-ins are perfect for executing tasks like these (unlike for example API Webhooks which are triggered based on an action in the system).

Scheduled plug-ins are not suited to act quickly on data changes, either inside or outside Assets Server. Immediately importing files from an external source or directly acting on asset metadata changes by using a scheduled plug-in would require that the task is scheduled very frequently (for example every 1 to 5 minutes). With each job execution the plug-in typically either polls Assets Server or an external system for "changes". If such changes are not present, the process creates an unnecessary API load on executions. For such scenarios API Webhooks are a better choice because these are triggered based on an action in the system.

The same applies when obtaining info from external systems, such as a wire feed import. If the external system supports an event system such as Webhooks then use that in combination with the Assets Server REST API to update Assets Server. This will perform better than frequently polling for changes through a scheduled plug-in.

For more information see Scheduling tasks in Assets Server with Schedule plug-ins.

API (proxy) plugins

API (proxy) plug-ins extend the Assets Server API with custom functionality, thereby enabling you to create additional REST services for Assets Server.

API plug-ins are particularly useful when creating a client plug-in and want to obtain information from both Assets Server and from an external source. In this case, the API plug-in provides a single REST API endpoint to your client code from which you can retrieve information. This is helpful as it prevents CORS issues and simplifies authentication. For more information, see Routing API requests through Assets Server using API plug-ins . For an example about how to use the plug-in, see the image recognition integration.

APIs

The following API types are available:

• REST APIs
• Webhooks
• SOAP APIs

REST APIs

Assets Server provides a large set of REST API endpoints for retrieving, creating, modifying, and deleting information. Supported actions include searching for assets, updating asset metadata, importing assets, sharing assets, copying folders, and much more.

The REST APIs are the core of the open platform that Assets Server provides and are used in Assets Server plug-ins, Web sites, mobile apps, and background jobs.

Note: Using the REST API in the ANT-based scheduled plug-ins does not work well because ANT does not provide a HTTP client library. To work around this, use cUrl from an ANT exec command or use other scheduling options. (Example: AWS Lambda can be easily used for writing a scheduled script that performs Assets Server REST API calls.)

For more information, see the REST API documentation.

Webhooks

REST APIs retrieve information from or change information in Assets Server but are not able to inform users on changes made in Assets Server so that they can be acted upon.

This is where Webhooks come in. Using Webhooks, an integration can listen for changes on assets, folders, and Collections and perform any custom action.

How it works

An Assets Server Webhook requires an endpoint (URL) to be configured where events are sent to. This endpoint is traditionally your backend Web server (PHP, Node.js, Java, and so on) that handles the request. For example: when the metadata of an asset changes, you receive a small payload containing the ID of the asset and the metadata that has changed. With this information the integration can immediately take action such as sending a notification e-mail to a user or exporting the asset to another system. See the Webhooks sample integration project which shows how Assets Server Webhook events can be consumed.

Tip: Serverless technology such as AWS Lambda (combined with AWS API Gateway) is a great scalable alternative to a back-end Web server for handling Webhook events.

Usage

Webhooks are great when data changes in Assets Server need to be directly acted upon. However, take note of the following points:

• Your integration can receive a high number of events on an Assets Server system that could already be heavily used (for instance when many modifications to assets are being made). To cope with this, make sure that your endpoint scales with traffic coming from Assets Server.

• Verify if the event is really relevant to your integration. To ensure this check is quick, it should be based on the information in the event payload and not involve any additional API calls, so ensure you configure all relevant metadata with the Webhook event.

• When your endpoint is not available for a long time period, events are not queued in Assets Server. Make sure therefore that your endpoint is always up and running so that all events can be received, for example by using a persistent message queue such as RabbitMQ or AWS SQS. Using a queue also makes it possible for your Webhook endpoint to always respond quickly (it only adds the event to the queue) and perform its real processing by reading from that queue.

SOAP APIs

The Assets Server SOAP API was the first API flavor that was shipped many years ago. It provides a limited set of endpoints for creating and modifying assets and is mainly used in the scheduled plug-in examples described earlier in this article.

New features for the SOAP API are not developed anymore, making it effectively deprecated. It remains however available so that existing third-party applications or integrations can stay compatible with newer Assets Server versions.

Note: When implementing new developments, always use the REST API; the SOAP API may at some point in the future no longer be available.

Performance considerations

The following questions typically appear during an investigation phase, during development, or during an integration:

• How many scheduled plug-ins can be run simultaneously?
• How many API calls can be performed against Assets Server?
• What Assets Server cluster setup is needed to handle the API load of my integration?
• How do I ensure the API load of my integration does not affect the performance for users of Assets Server?

While these questions are valid, they are not easy to answer. The answers depend namely on several factors:

• The number of cluster nodes that are running. An Assets Server cluster with 5 nodes will be able to handle more search requests than a single machine.

• The hardware specifications of the individual nodes and the network setup. More requests can be handled by high-end system nodes and on a faster network.

• The type of API calls that are performed. A 'read' operation such as an asset search is faster and less resource intensive than a 'write' operation such as an asset metadata update. Also, an operation that affects multiple assets such as a bulk metadata update or when copying a folder containing many assets can be exponentially heavier to perform.

• The frequency of the API calls. Is a peak load expected at specific times? Or is the load more predictable and constant?

Whether it is users using the clients, scheduled plug-ins running jobs, or other integrations connecting to Assets Server. they all trigger API calls that result in a combined system load. To have a system that is reliable and performs well, make sure that the combined API load is in line with the hardware setup that is in place.

Tips

Additional tips:

• Use a cloud provider such as AWS to host Assets Server. This makes it possible to easily scale up or down the number of Assets Server cluster nodes depending on the required performance. It can be quite hard to predict the required hardware, especially at the start of a new project. With cloud hosting, an exact and correct decision does not have to be made at the start of a project and therefore does not require high initial investments.

• Measure API response times and machine activity (I/O, memory, CPU, network) on your production environment and scale it up or down depending on this.

• Review your integration code on API effectiveness: can the same result be achievd with fewer API calls? Is the right extension point used for the right job (as described in the usage sections of this article)?

• Reach out to WoodWing partners who have experience in building and deploying integrations for their customers (both big and small). Learn from their experience in relation to working with the Assets Server extension points and how to match it with a viable hardware setup.

• Verify the hardware requirements and recommendations for Assets Server.

Notes

Note that Assets Server does not provide any mechanism to protect itself from being overloaded with too many API requests. There is for example no rate-limiting in the API. When the API load that is put onto an Assets Server system becomes too high, its performance will decrease (longer response times) and at some point Assets Server nodes may no longer be able to handle requests and might even crash.

However, by writing smart code and by making smart implementation decisions, amazing results can be achieved with the extensibility options of the Assets Server platform.