Before you create a component plug-in make sure you've considered the design guidance on this page.
Note: Before you invest time developing a custom component plug-in, review the interface components available in the Appian platform to see if an existing component meets your requirements. Be sure to explore the SAIL Design System as well for inspiration and design guidance.
The web content component can display content from a URL in an Appian interface. Component plug-ins can also display content like HTML and JavaScript in an interface. So when do you use web content and when do you use a component plug-in?
Short answer: Always use web content unless you have a good reason not to!
Why should web content be your first choice?
By contrast, component plug-ins:
* Applies only to components you plan to list on the Appian AppMarket.
When should you use component plug-ins?
To help speed up development, all plug-in components inherit a set of parameters for common attributes like the label, instructions, and tooltip. Avoid adding these parameters to your component so you don't end up with duplicate parameters.
The inherited parameters are:
Only the required and height parameters are included in the values passed to your component in the function registered using Appian.Component.onNewValue.
The following table lists the Appian data types supported by component plug-ins and their corresponding parameter and JavaScript types. Parameter types are defined in the plug-in manifest file. Conversion between Appian data types and JavaScript types is done automatically.
Appian Data Type | Parameter Type | JavaScript Type |
---|---|---|
Boolean | Boolean |
Boolean primitive |
Number (Decimal) | Decimal |
Number primitive |
Number (Integer) | Integer |
Number primitive |
Text | Text |
String primitive |
Dictionary | Dictionary |
Untyped object |
Variant | Variant |
Untyped object |
Connected System | ConnectedSystem |
Untyped object |
ConnectedSystem
parameters should only be used to call Appian.Component.invokeClientApi. Don't attempt to modify the value.
Tip: Date, Time, and Date and Time Appian types are not supported by component plug-ins. Use a pre-formatted date/time Text
parameter or an epoch-formatted Integer
parameter instead.
Component plug-ins can call client APIs exposed by connected system plug-ins to run logic on the server using the Appian.Component.invokeClientApi method. The component's client-side code (running in the user's browser) can pass in request parameters and then use values in the client API response to update what's shown to the user, call out to a third-party system, etc.
The primary reason for using client APIs is to execute logic that depends on sensitive values like third-party system credentials. For example:
Often the credentials needed to make system-to-system calls using integrations are the same values used to generate client-side tokens. Storing these credentials securely in a connected system makes them available to both integrations and component plug-ins.
Caution: Never directly expose connected system credentials using a client API! Always return a calculated value based on the credentials. If you're using a client library or integrating with a system that doesn't support this pattern, contact the developer or vendor to ask about how to securely integrate from JavaScript running in a user's browser.
Not all values stored in a connected system need to be sensitive. You might find it useful to have a connected system hold settings that control how to communicate with another system. In addition to using those values across backend integrations, you can expose them with a client API and use them in your component as well. If the value changes you can update the connected system once and all the related integrations and components adjust automatically. For example:
https://**account**.docusign.com
versus https://**account-d**.docusign.com
).In this case because the values aren't sensitive, there's no risk in exposing them directly using the client API.
Note: Don't use servlet plug-ins or web APIs to perform server-side logic. Both are harder to use from your component than a connected system (which can be accessed with a build-in API). Servlets don't have the ability to store credentials and other values securely. Web APIs are a design object and can't be packaged with your plug-in, so your component would depend on a designer to correctly configure a web API before it worked properly.
Sometimes you're connecting to a third-party system that provides a Java library but no JavaScript library, or the JavaScript library lacks certain features. In these cases you can use client APIs to expose capabilities from the Java library to your component's JavaScript code.
In traditional web applications, developers can use browser cookies or local storage to save data between user's visits.
In component plug-ins, you should always use Appian to save data instead by returning any information that needs to be persisted to the interface using the Appian.Component.saveValue method. This lets the Appian designer decide how and where to store data related to their application.
Design Considerations