Create microapps

A key component of creating microapps is to plan your workflow with an understanding of the target app’s database schema. With this, you can identify APIs to build your integration, which you need to build a custom integration.

There are countless applications that can be integrated into Citrix Workspace. Select a target application that holds information of interest to Citrix Workspace users. Of particular interest are applications that are regularly used for quick tasks and are not intuitively accessible to users. Actionable applications enabling users to directly interact from within Citrix Workspace have much more value than applications that simply enable notification of users. Examples include approving, creating, and adding items.

Next, identify key use-cases for the selected target business application that you want to integrate into Citrix Workspace. For example:

  • Create PTO/Vacation request
  • Approve PTO/Vacation request
  • Find pending approvals
  • Mark task complete
  • Notify user of created or changed assigned tasks
  • Approve invoice

Once use-cases are known, the next step is to identify the APIs that will allow us to extract relevant information from the target system or inject back into it.

Below we show a scenario of designing a workflow using an invoice approval use-case. For full details, see Sample scenario workflow design.

Important considerations

Review the following considerations and limitations before designing your workflow:

  • You can access data on a page only one relation away. This means that when a page is built you can address only directly related data.
  • All personalizations are made from the context of a user email. This means that if you are creating notifications or creating personalized pages, the user email can be a maximum of one level of relationship away.
  • You can only set Go to Page action links for notifications to a page that is based on the same table as the notification.
  • One change generates one notification. If the recipient is in the related table the relation must be 1:1, 1:N relations are not supported.
  • The database structure must be narrow because of server limitations. This must be taken into account when you are designing your endpoints and creating a database structure.
  • If you configured custom fields that contain highly sensitive data, such as credentials, API keys or secrets, the data is not protected. Such data appear in debug logs and elsewhere.

Note:

All administrators with access to Citrix Workspace microapps have access to data that is in the cache. Administrators do not have access to credentials for data sources.

Building microapps basics

Microapps are made up of pages or event notifications, and usually both.

  • Notifications are event-driven microapps that automatically notify users when something requires their attention, for example as a card in the Workspace activity feed. Such microapps include New Expense Report for Approval and New Course Available for Registration. The following list shows available event trigger types:

    • New records - Sends a notification when a new record is created in the source of record (SoR).
    • Changed records - Sends a notification when an existing record is changed in the SoR.
    • Matching record - Sends a notification when records match a defined query at the specific time in the SoR.
    • Delete records - Sends a notification when a current record is deleted in the SoR.
    • Periodic notification - (user action) Sends non-data driven notifications periodically.
    • Periodic report - Sends periodic notifications with summarized report data (grouping) for a specified time interval.
    • Date reminder - Sends a notification at the specified time before or after the records date column value.
  • Pages are user-initiated microapps that are available as actions in Workspace and make it easy to do initiate actions. For example, Request PTO, Submit a Help Desk Ticket, and Search the Directory. The following list shows page type templates:

    • Detail - Create a page to show static details from an individual record from your SoR.
    • Form - Create an editable page to provide static details in addition to the ability to input user data into your page.
    • Table - Create a page based on the multiple data tables loading from your target application SoR.
    • Static content - Create a page to show static, non-actionable information such as headlines, error messages, or reminders.

Add a new microapp

This procedure is the same for any blank microapp that you want to create.

Follow these steps:

  1. From the Microapp Integrations page, select the menu next to the integration that you want to add the microapp to.
  2. Select Add Microapp.
  3. Select Blank Template to build your own microapp based on your business needs. After you add the blank microapp, it appears under the related integration on the Microapp Integrations page.
  4. Return to the Manage Microapps page and select Blank Microapp from the list under the integration. The Properties page opens.
  5. Give it an appropriate name and description.
  6. Select Microapp Icon and choose an appropriate icon from the menu. There are App Icons, Action and Notification Icons, and Microapps and Data icons from which you can select.

Sample scenario workflow design

You have an invoice approval system, and you need to accommodate the following use-cases into our workflow:

  • Approvers must be notified when there are new approvals.
  • Requestors must be notified when their request is approved or denied.
  • Approvers need information about invoices, including status, total price, requestor details (name/email/phone), and a list of line item details (name/price/quantity).
  • Requestors need information about invoices, including total price, list of approvers details (names/emails/phones), and a list of line item details (name/price/quantity).

Now let’s have a look at our database, and their table relationships: Database schema and their table relationships

Design your microapp

From this you know that you need four notifications and five pages.

You need to build four notifications, two for approvers and two for requestors. The approver and requestor email is in the user table which has a direct relation with approvers andinvoice-detail tables.

You need to build five pages, one for each of these: approvers invoice list, approvers invoice detail, requestors invoice list, requestors invoice detail, and approvers and requestors line item detail.

Build your notifications

Start by creating the notifications. All of the considerations and limitations apply to notifications. Notifications must be sent by the user. The user email needs to be in the table or a maximum of one level of relationship away.

Build the notifications for approvers on the approvers table:

  • notification for new record in the table
  • notification for status change

Build the notifications for requestors on the invoice_detail table:

  • notification for new record in the table
  • notification for status change

Design limitations (approvers)

Data for the approver feed card can only be taken from these tables:

  • approvers (primary table)
  • invoice-detail (invoice_id relation)
  • users (only approver_id relation)

This means that you cannot get any data about the requestor to the feed card because personalizations are made from the context of a user email. For example, if you want to have the requestor name you must change the database schema and add the requestor name to the invoice_detail table.

Design limitations (requestors)

Data for the requestor feed card can only be taken from these tables:

  • invoice-detail (primary table)
  • users (only requestor_id relation)

This means that you cannot get any data from line_items and approvers because the relation is 1:N. For example, feed card text Your request was approved by manager@company.com is not possible. If you need this information, you must change the database schema and add this information to invoice_detail.

Conclusions

From this you can determine that there must be two invoice_detail pages:

  • Invoice Detail Approver that you build on the approvers table
  • Invoice Detail Requestor that you build on the table invoice_detailtable

You can recognize now that you have a limitation here with the Invoice Detail Approver page. You can add all data from the approvers (primary table), invoice-detail (invoice_id relation), and users (only approver_id relation) tables. However, you have the same problem as with the notification. There is missing requestor information and the line_items table is too far away, that is two levels of relation.

Workaround

There is a workaround to get data from a table two levels of relation away.

Option 1 Use GotoPage. You can add a third button, such as See details and move your users from this page to the Invoice Detail Requestor page. You built that page on the invoice-detail table, so the requestor and line_items tables are only one level away.

Option 2 Use the unbound table component: Unselect the Use Records Related to Detail Page toggle and you can select line_items. This creates a table with all items. You need to add a filter to select only items for the particular invoice. line_items invoice_id = approvers invoice_id. You can use a similar approach for the requestor. As the table is over the line_items, you can also add data from a table which has 1:1 or N:1 relation with line_items.

Build your pages

You need to build five pages, one for each of these tables:

  • approvers invoice list
  • approvers invoice detail
  • requestors invoice list
  • requestors invoice detail
  • approvers and requestors line item detail

If you need to allow for detailed permissions based on user assignments, use a separate microapp. For example, your workflow might require only certain users to access a create page. For a complete overview of the page builder UI and its components, see Page builder components. The cookbook below has detailed steps that leverage useful components to build detail and list type pages.

Microapps cookbook

Follow these examples of common types of notifications and pages you can build with a list of ingredients (components) provided.

Notifications

Build a notification to push new or changed items from your workflow to users. Select from the event trigger types, shown below, then customize the event in the builder. For more information, see Build event notifications.

Event triggers:

  • New records - Sends a notification when a new record is created in the source of record (SoR).
  • Changed records - Sends a notification when an existing record is changed in the SoR.
  • Matching record - Sends a notification when records match a defined query at the specific time in the SoR.
  • Delete records - Sends a notification when a current record is deleted in the SoR.
  • Periodic notification - (user action) Sends non-data driven notifications periodically.
  • Periodic report - Sends periodic notifications with summarized report data (grouping) for a specified time interval.
  • Date reminder - Sends a notification at the specified time before or after the records date column value.

List page

Build a list page to show all items available in your workflow. Start by using the following components. For a look at the finished page and step-by-step details to reproduce it, see Build a list page.

Components:

  • Table - Add a table by defining table source, filters, and defining columns. Page link actions can be added. Personalized queries must be set to limit data exposure.
  • Text Input - Define text source by specifying the data table, column, and value to load to the page entered by the user. Component can be marked as optional. Field width can be modified. Validation rules can be configured based on a minimum or maximum length or text pattern to identify user input.

Detail page

Build a list page to view details of one item that is available in your workflow. Start by using the following components. For a look at the finished page and complete steps to reproduce it, see Build a detail page.

Components:

  • Text - Define text source and formatting to load from the cache to the page.
  • Back Button - Allows users to go back to previous page.
  • Static Text - Define static text to appear the page.
  • Flexible Grid - Gives you more control over the positioning of components on your pages. Helpful when you’re designing pages intended for devices with larger screens. Set the label and the total number of cells you want in your grid.
  • Table - Add a table by defining table source, filters, and defining columns. Page link actions can be added. Personalized queries based on users’ emails may be set to limit data exposure.

Create page

Build a create page to add items into your workflow. Start by using the following components. For a look at the finished page and complete steps to reproduce it, see Build a create page.

Components:

  • Static Text - Define static text to appear the page.
  • Flexible Grid - Gives you more control over the positioning of components on your pages. Helpful when you’re designing pages intended for devices with larger screens. Consists of Grid Items. Set the label and the total number of cells you want in your grid.
  • Text Input - Define text source by specifying the data table, column, and value to load to the page entered by the user. Component can be marked as optional. Field width can be modified. Validation rules can be configured based on a minimum or maximum length or text pattern to identify user input.
  • Select - Allows users to choose from a set list of values. Populated by data from the source system or you can enter the list of values manually. Actions can be added.
  • Lookup - Allows users to search though a large quantity of values and allows users to select a value by searching for something else.
  • Button - Add a clickable component on the page with actions and logic.

Other resources

Check out this overview of Citrix Workspace Intelligence and the Microapps service at Video: Microapp Overview.

Learn about creating custom integrations and microapps at Video: Microapp Custom Integrations.

Find out more about getting a test instance at Citrix Workspace Developer Portal.

Here’s a quick guide to setting up an RSS microapp: Get notifications when there is a Citrix security bulletin.

Visit the Microapps Discussions Forum.