Appian Web APIs Use Case I: Team Calendar

Requirement Analysis

Convedo’s Holiday Management Tool has been released on Appian AppMarket earlier this year. One of the key features is the team calendar, which allows supervisors to view all approved holidays in their teams while reviewing new holiday requests awaiting approval.

In Sprint 0, there were several potential approaches to implement this feature:

1. Use Appian SAIL interfaces to construct the calendar;
2. Develop an Appian plug-in to display a customizable calendar as a SAIL component;
3. Use a web content field to display the calendar from an HTML web page.

For approach 1, all the necessary components of the calendar would be developed as Appian objects, which makes the solution highly reliable. However, due to the lack of flexibility of Appian SAIL components, the calendar would not be fully customizable.

For approach 2, if properly designed, the calendar SAIL component wrapped in the plug-in could be both reliable and flexible. However, the development of a custom plug-in would cost much longer time.

For approach 3, the source of the HTML web page was the major bottleneck. Fortunately, web APIs addressed the issue in a surprisingly easy way.

Create Web API (I): Query Database

All the approved holidays in a specific supervisor’s team are to be displayed in the calendar. Therefore, a GET API with multiple-user authentication is required. The expression to be executed in the API is to query the database, and the body of the response should be in HTML format.

• Step 1: As explained above, a GET API needs to be created for the calendar. Give it a proper name, description and endpoint when creating the object in Appian Designer;
• Step 2: Choose “Query Data Store” as the template to start with. Select the correct constant that refers to the holidays data store entity;
• Step 3: Since multiple-user authentication method is selected for the solution, loggedInUser() function can be used to specify the identity of a supervisor. If the single-user authentication method is preferred, the id or username of supervisors should be used as either a query parameter or a path. However, this method will not provide enough security to the business data because approved holidays will be exposed to anyone who knows about the API endpoint and ids of supervisors;
• Step 4: In the expression editor, update the query logical expressions and filters to retrieve all approved holidays of employees in the loggedInUser()’s team. The employee’s name, leave type, duration, start and end dates need to be returned for constructing the calendar.

Create Web API (II): Send HTML + JavaScript as Response

• Step 1: Develop a calendar in HTML, CSS and JavaScript so that different time periods could be dynamically marked within it. There’re many open source calendars that could be used to shorten the development process, however, necessary customization is still required in this scenario. Besides, locate the JavaScript sections which will be used for marking approved holidays;
• Step 2: Move the HTML source code over to the body of the a!httpResponse() function in Appian web API’s expression editor. Note that quotation marks (“”), which are widely used in HTML, will cause issues in the expression editor. The best practice is to break the HTML source code down and save them in several Appian constants as text values. Update the JavaScript sections identified in Step 1 and make sure that all the approved holidays can be correctly marked in the calendar. Test the appearance of the team calendar by clicking on the link of the URL in the web API designer;
• Step 3: Define several other a!httpResponse() functions to deal with situations such as the loggedInUser() is not a supervisor and so on. Remember to use proper status codes and headers or different types of responses.

Display Calendar in Web Content Field

The web API created in the previous sections can be called in different external systems. Here it is only going to be used within the same Appian environment.

To display the HTML content of an API response, a web content field is required in Appian’s interface designer. The “source” of the web content field needs to be a "SafeURI", which could be casted from a Text string. The best practice here is to use a combination of an environment-specific Text constant (containing the URL of the Appian cloud environment) and a string of the web API end point. Adjust other parameters of the web content field accordingly and test the SAIL interfaces in tempo and sites in the end.