The Component Plug-in JavaScript API allows you to interact with the rest of the interface on which your component is placed. This page provides an API reference for people familiar with JavaScript and the use of components in an Appian interface.
Tip: This version of Appian supports component plug-ins that use SDK version 2.0.0. Refer to the Integration SDK compatibility table for version details.
Loading the Component Plug-in JavaScript APICopy link to clipboard
To load the Component Plug-in JavaScript API, use the APPIAN_JS_SDK_URI
token in a script tag in the HTML file used as the html-entry-point of your component. The token will automatically replaced with the proper JavaScript URL when the plug-in is deployed.
1
2
3
4
5
6
7
8
9
<!DOCTYPE html>
<html>
<head>
<!-- This script loads the Component Plug-in JavaScript API -->
<script src='APPIAN_JS_SDK_URI'></script>
</head>
<body>
</body>
</html>
Copy
API referenceCopy link to clipboard
Appian.Component.onNewValue(newValueCallback)Copy link to clipboard
Registers a function to receive updated values when any component parameter values change due to initial interface load or re-evaluation (such as when the user interacts with the interface).
ParametersCopy link to clipboard
newValueCallback
(function): Function to handle receiving new values. All component values will be passed (including the values forrequired
andheight
parameters). These values are passed as a null-prototype Object where object properties correspond to parameters names in the component definition and values correspond to the current parameter value in the interface.
ReturnsCopy link to clipboard
None
ExampleCopy link to clipboard
1
2
3
4
5
6
7
Appian.Component.onNewValue(function(newValues) {
var required = newValues.required;
var height = newValues.height;
var csId = newValues.connectedSystem;
// Initialize component
});
Copy
Appian.Component.saveValue(parameterName, newValue)Copy link to clipboard
Sets a new value for a component parameter, triggering the corresponding saveInto to update the interface.
ParametersCopy link to clipboard
parameterName
(string): Name of parameter in the component definitionnewValue
(Varies): New value for the parameter. The value must match the parameter type in the component definition. See the type conversion table for details.
ReturnsCopy link to clipboard
None
Appian.Component.setValidations(validationMessages)Copy link to clipboard
Sets validation messages for the component. To clear all validations invoke with an empty array.
ParametersCopy link to clipboard
validationMessages
(string[]
): Validation messages to display in the interface
ReturnsCopy link to clipboard
None
Appian.Component.invokeClientApi(connectedSystem, friendlyName, parameters)Copy link to clipboard
Invokes a client API exposed by an associated connected system plug-in. This allows the component to access server-side logic and secure values stored in a connected system.
ParametersCopy link to clipboard
connectedSystem
(object): Reference to the connected system. This should be a value passed in from aConnectedSystem
component parameter.friendlyName
(string): Operation name defined by the connected system plug-in that maps to a specific Java method.parameters
(object): Parameters expected by the client API (as defined in the connected system plug-in code).
ReturnsCopy link to clipboard
Promise
: A promise that will be resolved (request success) or rejected (request failure) with a response object.
When the HTTP status code is between 200 and 299 the success handler is called. The response object passed to the success handler contains a payload
property containing the response defined by the client API implementation correspond to the Map<String,Object> resultMap
returned in the ClientApiResponse
.
When the HTTP status code is outside of that range, the error handler is called. The response object passed to the error handler contains an error
property containing the response defined by the client API implementation correspond to the Map<String,Object> resultMap
returned in the ClientApiResponse
.
If a connection error or other problem occurs, the response object passed to the error handler contains an empty error
property.
See also: Using Promises - MDN
ExampleCopy link to clipboard
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
function getToken(userId) {
const payload = { id: userId };
// Call the connected system client API to retrieve a token
Appian.Component.invokeClientApi(connectedSystem, "getToken", payload)
.then(handleTokenResponse, handleTokenError);
}
function handleTokenResponse(response) {
token = response.payload.token;
// Use the token...
}
function handleTokenError(response) {
if (response.error.errorMessage) {
// Show the error message returned by the connected system
Appian.Component.setValidations([response.error.errorMessage]);
} else {
// Indicate that some other problem happened
Appian.Component.setValidations(["An unspecified error occurred"]);
}
}
Copy
Appian.getLocale()Copy link to clipboard
Gets the user's locale/language code based on their Appian user settings, or the system-wide default if the user hasn't set a preference.
ParametersCopy link to clipboard
None
ReturnsCopy link to clipboard
string
: The user's locale string (For example: en-US
)
Appian.getAccentColor()Copy link to clipboard
Gets the accent color of the current Appian environment in hexadecimal format. Different accent colors can be defined for Tempo, sites, and embedded interfaces.
ParametersCopy link to clipboard
None
ReturnsCopy link to clipboard
string
: The current accent color in hexadecimal format (For example: #1d659c
)