Extending the functionality of Elvis 6 using extension points

The default features and functionality of Elvis 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 Elvis being an open system, the basic functionality of Elvis 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 Elvis 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 Elvis data from a plug-in or external application.	REST APIs
5	Extending the Elvis 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 Elvis API with custom functionality.

Client plug-ins

Client plug-ins make it possible to provide end users with additional (custom) functionality in the Elvis client applications: the Pro client 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 Elvis 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 Elvis 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 (see AI powered image recognition). 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 Elvis, 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 the Pro client or the Brand portal), typically because of security considerations. Opening such Web sites from within Elvis makes sure that users are aware of these sites and can easily access them.

• Panel plug-ins are added as regular panels in the Pro client 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 Elvis 6 functionality with plug-ins
• Adding custom functionality to Elvis 6 by using Action plug-ins
• Elvis 6 sample plug-ins
• Adding custom functionality to the Pro client of Elvis 6 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 Elvis 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 Elvis. 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 Elvis 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 Elvis REST API to update Elvis. This will perform better than frequently polling for changes through a scheduled plug-in.

For more information see Scheduling tasks in Elvis 6 with Schedule plug-ins.

API (proxy) plugins

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

API plug-ins are particularly useful when creating an Elvis client plug-in and want to obtain information from both Elvis 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 Elvis 6 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

Elvis 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 Elvis provides and are used in Elvis plug-ins, Web sites, mobile apps, and background jobs.

Elvis 6.35 introduced a new set of REST APIs that better follow REST standards in using HTTP methods and using correct HTTP status codes. These new APIs are also documented and testable by using the Elvis Management Console. The new endpoints currently do not cover all the functionality of the traditional endpoints. Depending on your needs, use either the traditional endpoints, the new endpoints, or both.

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 Elvis REST API calls.)

For more information, see the Elvis 6 REST API documentation.

Webhooks

REST APIs retrieve information from or change information in Elvis but are not able to inform users on changes made in Elvis 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 Elvis 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 Elvis 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 Elvis need to be directly acted upon. However, take note of the following points:

• Your integration can receive a high number of events on an Elvis 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 Elvis.

• 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 Elvis. 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 allows 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 Elvis SOAP API was the first API flavor that was shipped with Elvis 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 to allow existing third-party applications or integrations stay compatible with newer Elvis 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 Elvis?
• What Elvis 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 Elvis?

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 Elvis 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 Elvis clients, scheduled plug-ins running jobs, or other integrations connecting to Elvis. they all trigger Elvis API calls that result in a combined Elvis 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 Elvis. This allows you to easily scale up or down the number of Elvis 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 Elvis extension points and how to match it with a viable hardware setup.

• Verify the hardware requirements and recommendations for Elvis Server 6.

Notes

Note that Elvis 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 Elvis system becomes too high, its performance will decrease (longer response times) and at some point Elvis 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 Elvis platform.