How to Embed Appian Task Reports & Tasks

Overview

Embedded interfaces can provide solutions for Appian customers for a variety of reasons. One such use case involves a customer that has an existing external facing portal with branding and legacy functionality that they currently direct their customers to, and want to enhance with Appian’s low-code capabilities.

Embedded Appian interfaces provide a broad array of functionality, and can require JavaScript coding to achieve the desired end user experience. Specifically, JavaScript events need to be implemented and handled in order to replicate a typical Tempo/Sites user experience where the user clicks a task link and does not navigate away from the page. This playbook play will center around getting an embedded task report with this Tempo/Sites behavior up and running as quickly as possible, and provide functionality similar to that of a Tempo/Sites Appian application.

After successfully implementing this playbook play, you will be able to:

Embed a task report
Interact with the task report to invoke a task in the same webpage
Write JavaScript to handle different user events

Before you can embed any Appian interfaces, there are a few considerations to keep in mind:

Review How Should You Use Embedded Interfaces
Authentication
- SAML for Single Sign-On (Recommended)
  - With single sign-on you negate the need to log in to Appian in addition to any customer portal that provides access to the embedded interface.
Cross Origin Resource Sharing (CORS)
- Required to be setup in your Appian environment via Admin console.
- For more information on the above please refer to the prerequisites noted in the embedded interfaces documentation.

Import an Appian application that contains a task report object and a process model that creates Tasks.
1. Be sure to give the task report a descriptive name as this will be the name that shows up in the embedded interface.
Set up a hosting environment that hosts your public web page, which will contain the embedded Appian content.
Setup the admin console settings.
Customize the HTML/JavaScript snippets provided below to show/hide the tasks and task report

The following sections explain how to implement your first embedded interface into your own webpage. An example application can be downloaded and is available on Appian Forum. (Note: this Playbook play assumes the user has advanced Appian designer knowledge and basic web developer skills. If any concepts or terms are unclear, please complete the “Designer” trainings available in Appian Academy. Also, please keep in mind that we would only recommend completing this exercise in a development environment. We don't recommend this exercise be done in a customer portal.)

Appian Setup

Import the attached “Embedded UI Demo” application into an Appian environment version 17.4 or greater.
Add user(s) that you want to allow access to the task report to the “EMBEDPOC All Users” group.
Instantiate process instances/tasks with the Action, Kick Off Basic Workflow Task, to populate tasks in the task report.
1. To demonstrate that the task report filters according to the logged in user, have multiple users of the “Embedded UI Demo” application kick off tasks via this action.
Set up CORS for the embedded Appian interface. This is done via the Appian Admin Console under the “Embedded Interfaces” section. Click “+ Add Allowed Origin” and enter the URL where the index.html file will be hosted, and click “Save Changes”. In this case, “localhost:4200” was added as an allowed origin.

Hosting and Embedding the Appian task report and task

Deploy the file "index.html" in the web server. If the file is deployed under a nested folder/path, you will need to use the full path to this file in the following steps.

This can be done via localhost, and/or any web development framework should work.
IIS (pre-installed on Windows machines) or Apache Web Server can be used to host the website.
If you would like to test this functionality without having to setup a web server, you may choose to leverage a free third-party service.(https://en.wikipedia.org/wiki/Comparison_of_free_web_hosting_services)
- For developers with GitHub accounts, an easy option to recommend is to use GitHub.io to host the basic web page for sandbox purposes.
- Instructions to host a basic website can be found on https://pages.github.com/
- Follow the instructions and have the index.html hosted publically in less then a few minutes.

The remainder of this playbook will reference “localhost:4200”.

Once CORS is set up correctly, accessing the site with the embedded interface can be done via a web browser using the same address specified in the CORS settings. If you are not currently logged into Appian, you will be presented with the Appian login screen.

After logging in, you will see the task report hosted, and ready to interact with (provided you kicked off tasks in step 3 of the Appian Setup section):

Note that clicking a task will make it appear underneath the “My Tasks” task report. Submitting the task will make it disappear from the “My Tasks” report.

If it would be preferred that the task report disappears and is replaced by the task instead, simply comment out the lines mentioned in step 3 of the HTML/JavaScript Code section.

HTML & JavaScript Code

The HTML below utilizes the Embedded UI Demo application to embed an Appian report. The functionality allows users to click on a task link which will open the task below the task report.

<!doctype html>
<html lang="en">
  <head>
    <!-- Web browser auto-refresh functionality (every 30 seconds)
    <meta http-equiv="refresh" content="30">-->
    <meta charset="utf-8">
    <title>Embedded SAIL Playbook Demo</title>
    <base href="/">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="icon" type="image/x-icon" href="favicon.ico">
    <!---Required embeddedBootstrap tag--->
    <script src="https://ps-sandbox1.appiancloud.com/suite/tempo/ui/sail-client/embeddedBootstrap.nocache.js"
            id="appianEmbedded"></script>
    <script>
      //Replace with relevant task report URL stub
      const reportURLStub = '-OmqXw';

      window.onload = function () {
        var reportInsertDiv = document.getElementById('reportInsertPoint');
        var newReport = document.createElement("appian-report");
        newReport.setAttribute("reportUrlStub", reportURLStub);
        newReport.setAttribute("id", "embeddedTaskReport");
        reportInsertDiv.appendChild(newReport);
        // Event listener for links clicked on task report
        document.getElementById("embeddedTaskReport")
          .addEventListener(
            "open-task-link",
            (event) => {taskLinkClicked(event);},
            false
          );
      }
      // This function handles the behavior of the task when the task link is selected from the task report.
      function taskLinkClicked(event) {
        event.preventDefault();
        console.log("The task link has been clicked! "
          + event.detail.taskId
        );
        //Uncommenting lines 41-44 will provide the behavior of replacing the task report with the task itself. 
        //On completion of the task it will re-display the task report.

        // var reportInsertDiv = document.getElementById('reportInsertPoint');
        // var reportChild = document.getElementById('reportInsertPoint').children[0];
        // var newReport = document.createElement("p");
        // reportInsertDiv.replaceChild(newReport, reportChild);

        var taskInsertDiv = document.getElementById('taskInsertPoint');
        var taskChild = document.getElementById('taskInsertPoint').children[0];
        var newTask = document.createElement('appian-task');
        newTask.setAttribute("taskId", event.detail.taskId);
        newTask.addEventListener("submit", handleSubmit, false);
        taskInsertDiv.replaceChild(newTask, taskChild);
      }

      function handleSubmit() {
        var insertDiv = document.getElementById('taskInsertPoint');
        var child = document.getElementById('taskInsertPoint').children[0];
        var paragraph = document.createElement("p");
        insertDiv.replaceChild(paragraph, child);

        var reportInsertDiv = document.getElementById('reportInsertPoint');
        var reportChild = document.getElementById('reportInsertPoint').children[0];
        var newReport = document.createElement("appian-report");
        newReport.setAttribute("reportUrlStub", reportURLStub);
        newReport.setAttribute("id", "embeddedTaskReport");
        reportInsertDiv.replaceChild(newReport, reportChild);

        document.getElementById("embeddedTaskReport")
          .addEventListener(
            "open-task-link",
            (event) => {taskLinkClicked(event);},
            false
          );
      }
    </script>
  </head>

  <body>
    <div id="reportInsertPoint"></div>
    <div id="taskInsertPoint">
      <div id="taskInsertPointChild"/>
    </div>
  </body>
</html>

Note that if you would prefer to embed a Task Report from a different application, the only thing that needs to be changed is the constant on line 17. This value should be changed to report URL stub specific to your application. This stub can be found after the last “/” of the task report URL. This task report URL can be found by clicking on the task report object in design view.
If you would like to hide the task report when a task is shown, you will also have to uncomment lines 41-44. Note, this design pattern suggests having site navigation functionality allowing the user to return back to the task report grid. Otherwise, users will not be able to navigate back to the task report until they have submitted the task.

Sample Application and Index

6431.Embedded UI Demo.zip

8863.index.zip

Topics