JavaScript API

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.

Loading the Component Plug-in JavaScript API

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 be 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>

API reference

Appian.Component.onNewValue(newValueCallback)

Registers a function to receive updated values when component parameter values change due to initial interface load or re-evaluation (such as when the user interacts with the interface).

Parameters

• newValueCallback(function): Function to handle receiving new values. All custom parameter values will be passed, along with the required, height, disabled, instructions, and validations common 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.

Returns

None

Appian.Component.onNewValue() Example

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
});

Appian.Component.saveValue(parameterName, newValue)

Sets a new value for a component parameter, triggering the corresponding saveInto to update the interface.

Parameters

• parameterName (string): Name of parameter in the component definition
• newValue (Varies): New value for the parameter. The value must match the parameter type in the component definition. See the type conversion table for details.

Returns

None

Appian.Component.setValidations(validationMessages)

Sets validation messages for the component. To clear all validations invoke with an empty array.

Parameters

• validationMessages (string[]): Validation messages to display in the interface

Returns

None

Appian.Component.invokeClientApi(connectedSystem, friendlyName, payload, securedPayload)

Invokes a client API exposed by an associated connected system plug-in. This allows the component to access server-side logic and consume sensitive values defined in a connected system or provided as secured parameters in the request.

Parameters

• connectedSystem (object): Reference to the connected system. This should be a value passed in from a ConnectedSystem component parameter.
• friendlyName (string): Operation name defined by the connected system plug-in that maps to a specific Java method.
• payload (object): The payload sent to the client API (as defined in the connected system plug-in code). This is accessible within the client API using simpleClientApiRequest.getPayload().
• securedPayload (array): A list of secured parameter names whose developer-configured values are securely included in the Client API request and accessible within the client API using simpleClientApiRequest.getSecuredPayload().

If you update an existing plug-in to use secured parameters, set <application-version min="26.1.0"> in the appian-plugin.xml file and update the client API to the current Integration SDK version. This will prevent plug-in deployment to earlier versions of Appian that don't support this feature.

Returns

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

Appian.Component.invokeClientApi() Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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"]);
  }
}

Appian.Component.getAriaLabelledBy()

Gets the label ID for the component. Use this to set the aria-labelledby attribute so screen readers announce the label when the component receives focus.

For an example implementation, see the Appian.Component.getAriaDescribedBy() example.

Parameters

None

Returns

string: The ID of the component label.

Appian.Component.getAriaDescribedBy()

Gets the instruction and validation IDs for the component. Use this to set the aria-describedby attribute so screen readers announce instructions and validations when the component receives focus.

Parameters

None

Returns

string: A space-separated list that starts with the instruction ID and is followed by all validation IDs present at the time Appian.Component.getAriaDescribedBy() is called.

Appian.Component.getAriaDescribedBy() Example

Appian.Component.getAriaDescribedBy() returns a dynamic value that needs to be called inside Appian.Component.onNewValue().Appian.Component.getAriaLabelledBy() returns a static value, so it doesn't have this restriction. Because these APIs are usually used together, it is simpler to call them both inside Appian.Component.onNewValue().

1
2
3
4
5
6
7
8
9
10
Appian.Component.onNewValue(function(newValues) {
  // Initialize component

  // Set accessibility attributes on the focusable element
  const ariaLabelledBy = Appian.Component.getAriaLabelledBy();
  const ariaDescribedBy = Appian.Component.getAriaDescribedBy();
  const textAreaElement = document.getElementById('my-component-input');
  textAreaElement.setAttribute('aria-labelledby', ariaLabelledBy);
  textAreaElement.setAttribute('aria-describedby', ariaDescribedBy);
});

If your component conditionally renders the focusable element (for example, removing it when the component is read-only), check that the element exists before setting the attributes. In the following example, the accessibility attributes aren't set if getElementById returns null, which avoids an error if the element doesn't exist.

1
2
3
4
5
6
7
8
9
10
11
12
Appian.Component.onNewValue(function(newValues) {
  // Initialize component

  // Set accessibility attributes on the focusable element
  const focusableElement = document.getElementById('my-component-input');
  if (focusableElement) {
    const ariaLabelledBy = Appian.Component.getAriaLabelledBy();
    const ariaDescribedBy = Appian.Component.getAriaDescribedBy();
    focusableElement.setAttribute('aria-labelledby', ariaLabelledBy);
    focusableElement.setAttribute('aria-describedby', ariaDescribedBy);
  }
});

Appian.Component.getAriaLabelledBy() and Appian.Component.getAriaDescribedBy() are available starting in Appian 26.4. If your plug-in also needs to support earlier versions, check that these functions exist before calling them. In the following example, the accessibility attributes aren't set if the functions don't exist, which avoids an error on versions earlier than Appian 26.4.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Appian.Component.onNewValue(function(newValues) {
  // Initialize component

  // Set accessibility attributes if the APIs are available
  const focusableElement = document.getElementById('my-component-input');
  if (focusableElement
    && typeof Appian.Component.getAriaLabelledBy === "function"
    && typeof Appian.Component.getAriaDescribedBy === "function") {
    const ariaLabelledBy = Appian.Component.getAriaLabelledBy();
    const ariaDescribedBy = Appian.Component.getAriaDescribedBy();
    focusableElement.setAttribute('aria-labelledby', ariaLabelledBy);
    focusableElement.setAttribute('aria-describedby', ariaDescribedBy);
  }
});

Appian.getLocale()

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.

Parameters

None

Returns

string: The user's locale string (For example: en-US)

Appian.getAccentColor()

Gets the accent color of the current Appian environment in hexadecimal format. Different accent colors can be defined for Tempo, sites, and embedded interfaces.

Parameters

None

Returns

string: The current accent color in hexadecimal format (For example: #1d659c)

Feedback