Liferay Apps
Child pages
  • External repository for Box
Skip to end of metadata
Go to start of metadata

Summary

The External repository for Box allows your Liferay's portal users to access their Box's files and folders directly from Liferay's document and media library. For your Liferay's users that have a Box account the app will automatically make the connection so they can access their assigned Box account's files and folder. If you want, you can disable this automatic association of Box accounts to Liferay's users and do it manually. The app will keep an audit log of when, whom and how this association of accounts were made. For your Liferay's users that don't have assigned a Box account, the app can assign them a special proxy user that will allow them to access and interact with files and folders previously shared by other Box users.

To minimize the number of API calls, and improve the response time, the app has an intelligent cache of previously accessed Box's files, folders and search results. This cache can be tuned in to adapt it to your Liferay's users usage conditions.

From Liferay your portal users will be able to: create new Box folders, erase folders, preview Box files (videos, pictures, pdfs, office files, etc), move, update and erase files, all of that in accordance with the permissions set in Box.

Overview of features

  • Access to Box's files and folders directly from Liferay's document and media widget.
  • Automatic or manual assignment of Box accounts to your Liferay's users.
  • For your Liferay's users that don't have assigned a Box account, through a proxy user, they still can access and interact with Box's files and folders previously shared by other Box users.
  • Tune-able intelligent cache to minimize the number of API calls and improve performance and response time.
  • Create / erase Box's folders, preview (videos, pictures, pdfs, office files, etc), move, update and erase Box's files directly from Liferay all of that in accordance with the permissions set in Box.


Installation

There are two ways to install an app to Liferay Portal: via the Control Panel on your local portal installation and through the Marketplace on Liferay.com.

Installation through the Control Panel

This is the easiest and most efficient way to deploy apps to Liferay Portal. Using the Marketplace menu items in the Control Panel, you can search for, purchase/download, and hot-deploy apps directly to your local Liferay installation. Utilizing the Control Panel to manage your apps will also allow you to receive update notifications and easily apply updates.

Installation through Liferay.com

Using Liferay.com to download apps is especially useful in situations where you do not wish to deploy the app directly to your production environment, or in cases where the target Liferay installation is behind a corporate firewall or otherwise does not have direct online access to the Marketplace. You can browse for and purchase apps through liferay.com/marketplace and then use your App Manager to download them. The downloaded file can then be hot-deployed to Liferay by copying it to Liferay's hot deploy directory.

If you are trying to install the Marketplace portlet or any other Marketplace app in a controlled environment with restricted Internet and/or database access, you can find detailed instructions in the Liferay Marketplace tutorial: 

https://help.liferay.com/hc/en-us/articles/360017903012-Liferay-Marketplace-?notice=1


Configuration

Before your Liferay server can access your Box files and folders, first you need to grant permission to it by configuring some Box custom applications. To do that, go to your Box developer portal: https://account.box.com/login. After logging in, go to the Dev Console


Once in the Dev Console, you will need to configure two types of applications: 

  • One application that will allow your Liferay users to access their assigned Box account files and folders.
  • One or many applications that will allow your Liferay users that don't have been assigned a Box account, to access Box files and folders through a proxy user. These proxy users will be to access the Box files and folders that were shared with them by other Box users.


Setup of the app that allows portal users to access their assigned Box account files and folders

To configure the app that will allow your Liferay users to access their assigned Box account files and folders select Create New App:


Then select Custom App and click Next


Then select Server Authentication(with JWT) as your authentication method and a unique name for your app, like LRIntegration regular users access. Then click Create App.


Now, in the Configuration section of the app, select the following for Application Access, Application Scopes and Advanced Features:


Now click in Generate a Public/Private Keypair. Save this file to use later to finish the configuration in Liferay as defined in Access Credentials section.


Now, go to the General Settings section and click Review and Submit


 Give it a description like: App that allows Liferay's portal users to access their assigned Box account files and folders, and click Submit.


Now the app will have the App Authorization status: Pending Authorization


The final step is for you Box Admin user to authorize this application. As a Box Admin user click Back to My Account.


Then select Admin Console


Then in the left menu select Apps, and it the top menu select Custom Apps. Look for the app you defined in the previous steps that has the status Pending Authorization, and click the 3 dots button, and select Authorize App


Finally click Authorize.


You will see that now the app Authorization status has changed to Authorized. Now Liferay will be able to use this Box custom app to access the files and folders and show those to the portal users that have been assigned a box account.


As mentioned in this link: https://developer.box.com/guides/authentication/jwt/user-access-tokens/, this kind of app makes API requests as if they were made by the actual Box users. That is why we only need to define one app of this type, because even though many Liferay users may be accessing Box through this app, for Box it is as if several users were making independent API calls and that makes it difficult to hit the API rate limits as described in section Box Limitations of this document.


Setup of an app that will allow your Liferay users that don't have been assigned a Box account, to access Box through a proxy user

To configure an application that will allow your Liferay users that don't have been assigned a Box account, to access Box files and folders through a proxy user, select Create New App:


Then select Custom App and click Next


Then select Server Authentication(with JWT) as your authentication method and a unique name for your app, like LRIntegration proxy user access 01. Then click Create App.


Now, in the Configuration section of the app, select the following for Application Access, Application Scopes and Advanced Features:


Now click in Generate a Public/Private Keypair. Save this file to use later to finish the configuration in Liferay as defined in Access Credentials section.


Now, go to the General Settings section and click Review and Submit


 Give it a description like: App that will allow your Liferay users that don't have been assigned a Box account, to access Box through a proxy user, and click Submit.


Now the app will have the App Authorization status: Pending Authorization


The final step is for you Box Admin user to authorize this application. As a Box Admin user click Back to My Account.


Then select Admin Console


Then in the left menu select Apps, and it the top menu select Custom Apps. Look for the app you defined in the previous steps that has the status Pending Authorization, and click the 3 dots button, and select Authorize App


Finally click Authorize.


You will see that now the app Authorization status has changed to Authorized. Now Liferay will be able to use this Box custom app to allow your Liferay users that don't have been assigned a Box account, to access Box files and folders through a proxy user. These proxy users will be to access the Box files and folders that were shared with them by other Box users.


Important note

As mentioned in this link: https://developer.box.com/guides/authentication/jwt/with-sdk/, this kind of app makes API requests as if it was an independent Box user. That is why you may need to define several apps of this type, because you will probably have many Liferay users that don't have been assigned a Box account and they will be accessing Box through these proxy users. If you only have one proxy user (one app of this type) you will likely hit the API rate limits as described in section Box Limitations of this document. To create several proxy users just repeat the previous steps and assign  different names to the apps like: LRIntegration proxy user access 02, LRIntegration proxy user access 03 and so on. The number of proxy users that you will need will depend on the usage conditions of your Liferay users and the cache configuration you use as defined in section Cache Tuning but as a general rule of thumb you may need a proxy user for every 1000 Liferay users in your portal.


Liferay Configuration to access Box accounts

As an Admin user, in the Control Panel there is a new option called External Repository for Box with different sections. We will explain every section below.

Access Credentials

Here we will make use of the files downloaded when configuring the Custom Apps in Box, and this will be one of the final step to finalize the integration between Liferay and Box.

In the Individual access credential (required) field copy and paste the content of the file you download when following the steps Setup of the app that allows portal users to access their assigned Box account files and folders

In the Generic access credential field copy and paste the content of the file(s) you download when following the steps Setup of an app that will allow your Liferay users that don't have been assigned a Box account, to access Box through a proxy user. If you have configure more than 1 proxy user, click the + sign and enter the additional file contents.

In the section Access Box repository from Liferay we explain the final step in order to access the Box files and folders from Liferay.


Audit Log

This section is a read only section that keeps track of which Box users have been assigned to the Liferay's portal users. Remember that once a Liferay user is assigned a Box user then that Liferay user is going to be able to access the files and folders of that Box account. The log displays the email address of the Liferay user that assigned (Executor) another portal user (Receiver) a Box user. When Box User ID field is empty, that means the Receiver has been unassigned a Box User ID.


Box User Assignment

Checkbox Enable Automatic Assignment

If you check this option, you don't have to worry about manually assigning your Liferay users their corresponding Box user. If you enable this feature, each time your Liferay user logs in, it will check if there is a corresponding Box users that matches the email address of the Liferay user, if it does and the Liferay user has no been assigned it, it will assign it and your Liferay will be able to access the files and folders of that Box user. Also each time your Liferay user logs in, it will check if it currently has been assigned a Box user, if it has, then if will check if the email address of the Box user matches the one of the Liferay user, if it doesn´t match then it will remove that assignment and your Liferay user won´t be able to continue accessing the Box files and folders of that user.


Manual assignments

Here you can manually assign Box user to the Liferay user. After doing that the Liferay user will be able to access the files and folders of that Box user. Be aware that if you have Enable Automatic Assignment, this automatic assignments logic could overwrite your manual assignments. For that reason we don´t recommend to have Enable Automatic Assignment and do manual assignments.

To do manual assignments, first you need to locate the Liferay user to which you want to assign (or remove) a Box user.


If the user has not been assigned a Box user then you will see the Add Box ID button. Click that button and now you will be able to enter the ID of the Box user you want to assign to your Liferay user. BE AWARE THAT after you confirm this assignment by clicking the Save button your Liferay user is going to be able to access the files or folders of that Box user even if they correspond to a different person so be VERY CAREFUL WHEN DOING THIS MANUAL ASSIGNMENT.


If you don't know how to find the Box user ID of a Box user, you can find it in Box by clicking the Account Settings option after you login to Box.


Then scroll down to the section Account Details, the Account ID value is what you are looking for.


If your Liferay user has already been assigned a Box user, you can remove or edit that assignment.


Cache Tuning 

Cache tuning is very important to minimize the number of API calls needed to access the Box data and present it to the Liferay users. Also it will minimize the response time to the Liferay's users, because if Liferay finds the data in the cache then it won't need to make a request to Box to get it.


For each cache option you can configure the max number of entries in the cache and the time of live of those entries in the cache (in seconds). For the time to live value you can enter a special value of 0, which means your cache entries will live for ever in the cache (or until the cache is shutdown or manually removed), if you specify a value higher than 0 then your cache entries will be removed automatically from the cache after that number of seconds.

Here you can configure:

  • Folders info cache: what is stored in the cache is the metadata of the Box folders (id, name, size, etc)
  • Files info cache: what is stored in the cache is the metadata of the Box files (id, name, size, extension, etc)
  • Folder children cache: what is stored in the cache is the list of the direct children metadata (files and folders) of a folder.
  • Search results cache: what is stored in the cache is the metadata of the files and folders that were found after certain keyword was used.

To avoid keeping invalid data in the cache (ie. after a file was removed or renamed) the application invalidate the cache entries when it detects that those actions have happened in Liferay. Those inconsistencies are more difficult to detect when those changes were made directly in Box and not through Liferay. But the application is prepared to gracefully handle those situations.


Accessing Box repository from Liferay

Go to Documents and Media and click in the plus icon and select the Repository option. Think about this repository like a virtual disk that allows you to access Box files and folder from Liferay.


Give a name to this repository, something like Box Repository and select Box Repository in the Repository Type combo box. You can also set the permissions to control which portal users can access this repository. Click Save button. Now you have a Box Repository and the application automatically uses the Box credentials previously configured in the section Access credentials.


After you do that you will see something like this:


The final step is to enable the actions menu, which allows your portal users to delete and move Box files and folders directly from Liferay. To do that click the Configuration option of the Documents and Media widget.


Then make sure the Show Action option is enabled.


Finally in the Documents and Media widget you can click the icon that represents your Box Repository and you should be able to work with the Box files and folders directly from Liferay. If you get an error like this:

That is because:

  1. You haven't enter the credentials required to access Box from Liferay, see section: Access Credentials of this document.
  2. After following the steps described in Access Credentials you have only entered the Individual access credential and your Liferay user hasn't been assigned a Box user, see section: Box User Assignment of this document.


Example use cases

In this section we will explain how you can configure your Box account to meet certain use cases. But before we proceed with that, it is important to explain how you give access to Box files and folders to your Box proxy user(s) (see section Setup of an app that will allow your Liferay users that don't have been assigned a Box account, to access Box through a proxy user that explains how to create and configure these proxy users).

For you to give access to Box files and folders to these proxy user apps, first you need find out which email address was assigned to each proxy user. To to do that, in Box as an admin user go to the Content section and located your proxy user in the right list. Then with your mouse right click on it, and click Log in to user's account.


Now you are presented a screen that shows what this proxy user can access in Box. Select the Account Settings option.


Scroll down to the section Login and Email Addresses, take note of that email address, that is the email address you will need to use whenever you are sharing a file or folder in Box.


Like this


Remember that they are different type of permission that be given when sharing files and folders in Box as explained here:

https://support.box.com/hc/en-us/articles/360044196413-Understanding-Collaborator-Permission-Levels


We don't recommend to share files and folders directly with proxy users, what we recommend is to have all your proxy users in a Box group and then share your files and folders with that group. That is because you will probably need more than one proxy user see Important note about proxy users. You can create Box groups as an admin user in Users & Groups section, and the go to Groups tab


Remember that if you want to allow your regular Box users to share files and folders with a Box group like this you need to make this group accessible to them by choosing the right Permission Setting when creating the group.

For the following use cases we will assume the following:

  • All full time employees have been assigned a Box account.
  • Contractors don't have been assigned Box accounts, but they should be able to access some Box's files and folders.


Use case 1: A manager wants to share files (read-only access) with full-time employees but not with contractors

Steps to follow:

  • The Box admin user should create a Box group (with Group Members Permission Setting) and add all full-time employees to that group.
  • In Box, the the manager should share the folder with the full-time employees group (Viewer permission)
  • For your Liferay's users to be able to access the Box files you can do automatic or manual assignments see section Box User Assignment, then your Liferay's full-time employees users should be able to access those Box files through the Document and media widget.


Use case 2: A manager wants to share files (read-only access) with all employees (including contractors)

Steps to follow:

  • In Box, the manager should share the folder with the all employees group (Viewer permission)
  • For your Liferay's users to be able to access the Box files you can do automatic or manual assignments see section Box User Assignment, then all of your Liferay's users (full time employees or contractors) should be able to access those Box files through the Document and media widget.

Use case 3: A manager wants to be able to receive files from all employees (including contractors)

Steps to follow:

  • The Box admin user should create a Box group (with Company Permission Setting) and add all full-time employees to that group, and also should add the proxy user(s) that contractors will need to access Box from Liferay see section: Setup of an app that will allow your Liferay users that don't have been assigned a Box account, to access Box through a proxy user. Also see at the begining of the section: Example use cases how you get the email address of the proxy user(s) you can add them as a part of this Box group.
  • In Box, the manager should share the folder with the all employees group (Previewer Uploader permission)
  • For your Liferay's users to be able to access the Box files you can do automatic or manual assignments see section Box User Assignment, then all of your Liferay's users (full time employees or contractors) should be able to access those Box files through the Document and media widget.


Use case 4: an employee want to share files (read-only access) with all employees (including contractors)

Steps to follow:

  • The Box admin user should create a Box group (with Company Permission Setting) and add all full-time employees to that group, and also should add the proxy user(s) that contractors will need to access Box from Liferay see section: Setup of an app that will allow your Liferay users that don't have been assigned a Box account, to access Box through a proxy user. Also see at the begining of the section: Example use cases how you get the email address of the proxy user(s) you can add them as a part of this Box group.
  • In Box, the user should share the folder with the all employees group (Viewer permission)
  • For your Liferay's users to be able to access the Box files you can do automatic or manual assignments see section Box User Assignment, then all of your Liferay's users (full time employees or contractors) should be able to access those Box files through the Document and media widget.


Important Information

Box Limitations 

API rate limits

See document: https://developer.box.com/guides/api-calls/permissions-and-errors/rate-limits/

Maximum file size

See document: https://support.box.com/hc/en-us/articles/360043697314-Understand-the-Maximum-File-Size-You-Can-Upload-to-Box


Configure Liferay to generate preview of videos

PENDING


Configure Liferay to generate preview of office documents

PENDING


  • No labels