Appian to Appian Web API Integration

Appian Web APIs can be invoked by other systems or users to query or modify data within Appian, start a process, or download documents. For more information how to implement a Web API in which an external system retrieves data from Appian, try the Web API tutorial. For an example in which an external system sends data to Appian, try the other Web API tutorial.

• There are a number of ways to authenticate Appian Web APIs. . API Key authentication is generally the most common, and it is recommended that you set up an API key that is tied to a service account for each system that will be interacting with Web APIs in your environment.  
  • Note: These service accounts will need to be added to the security for each object they interact with, including the Web API itself.
• It is no longer recommended to publish process models as a web service. Instead use a Web API with a!startProcess to start a process from an external system.

There are some scenarios in which developers can design Web APIs in an Appian environment to be called from the same Appian environment. Always use an environment-specific constant when configuring the URL of the Web API in an Integration object. This ensures in Dev you are always referencing Dev, in Test you are always referencing Test, etc.

Overriding Object Security to Run as Administrator

• End users can run queries that would typically require elevated privileges (for example: fetching members of a group, querying process data, getting a list of tasks for a particular user, etc.). Any Appian expression can be executed as a specific user with the use of Web APIs coupled with integration objects.
• Web APIs allow users to gain access to certain information without granting them security over objects they don’t need.

Executing Multiple Smart Services

• For operations in the system that could take more than one second or are noticeably slow for users, it is recommended to use a!startProcess and trigger a new process to run multiple smart services after one saveInto evaluation.
• For operations that won’t take that long, you can make multiple integration calls, within one saveInto evaluation, against different Web APIs to run multiple smart services (e.g. editing document properties, creating a user, adding a user to a group, writing data to a data store entity, etc.). See Process Nodes and Smart Services for more information.
• Utilizing Web APIs instead of starting processes can reduce the load on the process execution engines.
  • Note: When utilizing Web APIs like this, the smart service calls occur as separate transactions. Therefore, you will need to account for errors occurring between smart services. For example, if you call one Web API to write a row of data then another to delete a row of data, and the deletion fails, the write will have already occurred since it's a separate transaction. This is similar to handling for a process erroring between nodes, however in a Web API, you lose the ability to have a process editor debug and restart the process node.

Invoking Javascript within Appian

• To execute Javascript in a user's browser you can configure a Web API which returns HTML as the body of the response and includes a <script> tag. The Javascript in this tag will be executed when the Web API is called.
• The Web API can be called by providing a user an a!safeLink, which, upon clicking, will open a new browser tab and execute the Javascript in this new tab.
  • Note: As of 18.2, you will no longer be able to provide an Appian Web API as the source for a Web Content field, which is why the Javascript can only be executed in a separate tab using a!safeLink.

Viewing Documents Inline within the Browser

• Instead of using a Document Download Link, you can configure a Web API in Appian which returns a document, either as an attachment or inline, and then call this Web API using a Safe Link. This will let users view, in the browser, any documents that the browser can render, rather than automatically downloading them.

Common Issues

• Issue: The Web API works when tested inside Appian. 404 returned when calling from another system.
  • Verify: Make sure that the credentials match that of a use in the Web API's security groups.
• Issue: 500 error returned when calling the web API from another system.
  • Verify: Ensure that the Web API expression definition does not have any errors.