On this page

The SubApps tab

Integrating existing apps as subordinate apps can be a smart way to reduce development time while forming relationships and structuring data between your app and others. In this guide, we will go through the steps required to add Instant, Remote, and Standard Apps as subordinate apps to your app.

Add an existing App as SubApp

When you want to add an existing app as a SubApp, you must ensure you have the correct name for that app first. Apps are often displayed by their labels which may or may not the same as the app name. The app name can be seen in the URL of the app's main page, it is the last part of the URL i.e: if the URL is https://w1.sitegui.app/siteadmin/100/app/feature_request, the app name is Feature_Request.

When you have the correct name of the app, just enter the name into the App field and optionally set an Alias for that app to replace the app name (in your app only). You can choose whether your App's record accepts multiple or just single subapp entry from each Client. For instance, if Comment is a SubApp, for each app record, we expect to receive multiple comments from a Client but for Like SubApp, we expect just one Like from that Client. If entries for the SubApp should not be created through the main App, choose Client ReadOnly or (Staff) ReadOnly for the Entry/User to just display SubApp entries and hide the button and input fields for creating a new entry.

Finally, choose how all SubApp's entries are displayed with our app record:

  • Table: display each SubApp's entry as a row in a table
  • Grid: display each SubApp's entry as a card in a grid
  • Kanban: group entries by a property (e.g: status) and display them in kanban columns
  • Flat Discussion: display entries as a flat discussion thread (e.g: comment thread)
  • Single Entry: display as a single entry
  • Client Hidden: hidden for Client, default SubApp's display for Staff. Note that Client can be under-privileged employees in the case of company internal app.
  • Linked Records only: (special case) list records that linked back to the main record (not really sub-records)

Your app may have as many SubApps as it needs, however please note that SubApps must be activated or bought by Site Managers before they can be used with your app. Site Managers having Developer license are also able to add more SubApps to your app or override the settings for existing SubApps when they configure your app.

Hidden App is visible when it is added as a Subapp

Hidden App are hidden from view for both Client and Staff, this is because they are often designed to be SubApps, complementing other apps. When they are added as SubApps, they become visible within the app to which they are added. For example, Like app is not really useful when it is used alone (so it is hidden by default) but when it is added as a SubApp, it helps provide Like for other apps' records (and thus its entries are visible when other apps' records are displayed)

App Visibility does apply in other cases, except when your app set the SubApp to be Client Hidden which will hide the SubApp for the Client group.

Relationship between Main App's record and SubApp's record

When a SubApp's record is created through the Main App, a parent-child relationship is established automatically between the Main App's record and the SubApp's record but this relationship is not visible to the Automated Action. App Developers should consider using a lookup field to create a direct relationship from the SubApp's record to the Main App's record and utilize the Automated Action to update the Main App's record when needed. App Developers may use a lookup field with name exactly as the Main App's name to silently assign the Main App's record ID as the field value when creating a SubApp's record through the Main App.

When a parent-child relationship is established between a main app record and a subapp record, if the main app record is also a child record in another parent-child relationship, a root-child relationship between the main app record's root (could be its parent or its parent's parent ...) and the subapp record is also established. Then the root record will be able to list all child-records and grandchild-records through its SubApps. For the subapp record, it is also recommended to use a lookup field with name exactly as the Root App's name to silently assign the Root App's record ID as the field value when creating a SubApp's record through the Main App. Then the subapp record may refer to the root record's ID during the automation process.

This root-parent-child (or root-child-grandchild) relationship is very useful feature where the root record can list all child (parent) and grandchild records while the child record can also list the grandchild records through its SubApps. For example in a CRM system, a Contacts app may contain Deals and Activities as its SubApps to list all the deals and activities for a contact person. In the Deals app, it also use Activities as a SubApp to list all activities related to a deal. When you create an activity for a deal in the Deals app, that deal becomes parent record for the activity and the activity can be seen inside that deal. If that deal is a child record of a Contacts record (with no parent record), that contacts record will become the root record for the activity and the Contacts record will list the activity as one of its activities. Please note both Contacts (root) and Deals (parent) should have Activities (child) as a SubApp.

Now if we have a Companies app and want to make a company record as the parent record for the above Contacts record, what will happen? First, all the Deals and Activities record will change the root record from the Contacts record to the Companies record. The Companies record will see all the Deals and Activities records (through its SubApps) because it is their root record. The Contacts record still see all the Deals records because it is their direct parent but will lose the Activities records created through Deals because it is not their direct parent nor their root. It may have some Activities though if they were created directly through the Contacts app (direct parent).

What can we do for the case above? As we know, the platform works best for 3 level root-parent-child relationship, we should try to keep it that way. If there is another level (as the Companies app), the platform provides another useful feature (Linked Records only) that helps Apps to list all records that link back to it (list it as the foreign key). Those records will be listed through a SubApp with entry set to "Linked Records only", please do note that those records are not sub-records but linked records (contain a lookup field with value is the current app record's ID but do not assign a parent record to keep itself as the root record). For the example above we will add Contacts as a SubApp with "Linked Records only" to the Companies app and Contacts will have to lookup field to choose a Companies record. Choosing which app is the root app is important, it is where you can see all the records created at lower levels. Keep the root app and used Linked Records to link it to other Apps if needed.