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:
- Use Appian SAIL interfaces to construct the calendar;
- Develop an Appian plug-in to display a customizable calendar as a SAIL component;
- 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.
- 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.