当前位置：文江博客知识库 citrix en-us citrix-microapps create-microapps

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.
A record based detail page (that is a page using a recordID) cannot be set as an action page. Make sure that no component is mapped to a record value. For example, a Detail page should not be set as an action page, unless it’s a pure input form, such as Add a Task.
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 primary table is the table upon which you build the notification event.
We expect that there is at most one recipient. If the recipient is not in the primary table, make sure that there is only one matching record in the non-primary table for each record of the primary table. For example, if you create a notification over the table pto_approval, but there can be two different approvers who can approve that request in the table pto_approver (so called one-to-many relationship) and you want to notify them both, it is not possible. The notification engine picks up only one approver randomly. If there are many such cases, the notification event is not evaluated at all.
The expected relationship between the primary table and other tables is 1:1. This means that for each record in the primary table there will be at most one record in the other table. Thus, the notification event can never produce more notification messages than the number of rows of the primary table. If this condition is violated and you have more than one record for some records of the primary table, duplication in the underlying data will appear. The notification engine will pick randomly only the first record and ignore the duplicates.
If any value in the primary key column is missing or has an invalid type, the record is skipped during synchronization and a log warning is generated.
There are some hard limits to protect the infrastructure and also the admin users from defining wrong notification events. The maximum ratio of the number of rows returned by the notification query compared to the number of rows of the primary table is 1.6:1. For example, let’s say a primary table contains 130 rows, but the notification query returns 416 rows for some reason. This would be 3.2 times more than expected and exceed this limit. In this case, the notification event is not evaluated at all and a warning is printed to the log instead.
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.
Notification messages are generated after all the conditions are evaluated. The maximum number of notification messages produced by one notification run is 100,000.
The maximum number of records a notification query can return is 1,000,000.
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:

From the Microapp Integrations page or in the integration view (opened by selecting the integration), select the menu next to the integration that you want to add the microapp to.
Select Add Microapp.
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.
Return to the Manage Microapps page and select Blank Microapp from the list under the integration. The Properties page opens.
Give it an appropriate name and description.
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.

Clone a microapp

You can also clone an existing microapp to create a new microapp. This microapp exists in the same integration. You must give the new microapp a unique name as no two microapps in the same integration can have the same name.

From the Microapp Integrations page or in the integration view (opened by selecting the integration), select the menu next to the microapp that you want to copy, and then select Clone.
Enter a New microapp name in the field, and select Clone.
The new microapp is added to the list of microapps.

Note:
You can also export and import a new version of the microapp from the same menu. For more information on these capabilities, see Export and import integrations and microapps.

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.

Embed

The Embed page template renders an iframe for embedding custom webpages. The size of the iframe is adjusted automatically to the available space on the page. The Embed page has no components, and is not bound to a database table, similarly to the Static Content page. This also means that the URL for the Embed page cannot make use of template variables as there is no connected database table. For information on the embed component see Embed component.