Event Resource Integration
Last updated
Last updated
New work was introduced in Elentra ME 1.22 surrounding the Draft Events feature. These enhancements allow for integration with Box.com. This guide is intended to provide instructions on how to properly configure this integration.
The first step is to navigate to https://app.box.com/ and log in to your account.
From the main sidebar panel on the left of the screen, you should see a button labeled "Dev Console" near the bottom of the panel. Select that button.
This should take you to a page titled "My Apps", where you should see a button to "Create New App". Select that button.
You should now be prompted to select the type of app that you would like to create. Select the "Custom App" option.
You should now be prompted to select the method of authentication. Select the "Server Authentication (with JWT)" option.
Provide a memorable / descriptive name for the "App Name" field (e.g. "Elentra Integration App") then select the "Create App" button to confirm and save.
While viewing your newly created App, on the "Configuration" tab, scroll down until you see a section titled "Application Scopes". Within that section, under a subheading of "Content Actions", you should see a checkbox for a scope option: "Write all files and folders stored in Box". Make sure that this checkbox is enabled / checked, then select the "Save Changes" button.
Please Note: This scope option is required in order for the app to be able to download files. The descriptor could be worded more accurately, but this is a requirement from Box.com, not Elentra. The Draft Events feature will never add or edit any files without your Box.com account.
After you have saved your changes to that newly enabled option, scroll down to the section titled “Add and Manage Public Keys”. Select the button labeled “Generate A Public/Private Keypair”.
Please Note: If you do not have Two Factor Auth (2FA) enabled for your account, Box.com will prompt you to set up 2FA before proceeding to generate the Keypair.
Once you have Two Factor Auth (2FA) enabled, you will be prompted to enter your 2FA generated 6-digit code. After inputting your 6-digit 2FA code, if you are taken to the App Configuration screen, just select the “Generate A Public/Private Keypair” button once again.
You will then be informed that a JSON configuration file has been downloaded, which contains all of your newly created app's settings. Make sure to accept the download, as this contains the only copy of your private key.
Please Note: Store the downloaded file in a secure location such as a password management app like 1Password or BitWarden. Keep a copy on your machine, so that you may use the credentials within to set up your Elentra installation, but be sure to delete the local copy when you’re done going through the process outlined in this walkthrough.
Open up the downloaded JSON config file and map the applicable fields within it to those that match within the Elentra Settings PHP file, located within Elentra ME at elentra-1x-me/www-root/core/config/settings.inc.php. For the field labeled "BOX_AUTH_URL", set the value to the following URL: https://api.box.com/oauth2/token. Make sure to save your settings.inc.php file once you're done.
Return to your Box.com homepage at https://app.box.com/. This time, select the button labeled "Admin Console" (which should appear above the "Dev Console" button we selected last time).
In the Admin Console's sidebar, you should see an option labeled "Apps". Select that option link.
Switch over to the "Custom Apps" tab on this page.
In the upper righthand side of the "Custom Apps" screen, select the plus sign icon button ("+").
You should be presented with a confirmation action dialog, and you will be prompted to enter the "Client ID" of the custom app you would like to authorize. That information is contained within the JSON configuration file downloaded earlier.
Please Note: Ensure that the "Name" field in the confirm dialog matches the name you provided for the custom app created earlier! Under the "Application Scopes" heading, you must also ensure that both Read and Write permissions are included, as indicated in the screenshot below.
Once everything in the dialog is correct, select the dialog's "Authorize" button. Once you do, you should see your custom app listed in the list of authorized apps.
Next, navigate to Elentra ME in the browser and create a new draft. Enter the draft and add a few events (this page is accessible at http://elentra-1x-me.localhost/admin/events/drafts?section=edit&draft_id={your_draft_id}
Select the "Import & Export" button, then select "Import Resources" from the dropdown.
You should now see the following "Import Resources" panel. The righthand section is where Box.com folders will be displayed, however it should be empty at this time (even if you do have folders in your Box.com account). Also, there sould not be a loading animation. If there is, check your error logs and confirm that your configuration settings are accurate. The steps that follow are required to enable the folders' visibility here.
Navigate back to the Box.com "Admin Console" (https://app.box.com/master).
From there, select "Users & Groups".
Select the "Bulk Edit" button.
Select "Download file of current users". Save the file locally.
Open that saved file with a spreadsheet editor such as Microsoft Excel. Locate the row where the value for the "Name" column matches the name you provided for your Box.com Custom App (e.g. "Elentra Integration App" or whatever name you used earlier. From this matching row, copy the value of the "Email" column field. It should look something like AutomationUser_1574988_KGb9IP7ITg@boxdevedition.com. Store this email somewhere safe so it can be easily retrieved later.
Head back to your Box.com homepage at https://app.box.com/
This time, on the main homepage, hover over any folder that you would like to appear and be accessible within Elentra ME's Draft Events. For that folder, click on the ellipsis of three dots ("...") to open a context menu. From this popup menu, select the "Share" option.
Upon selecting that "Share" option, you will be presented with a modal. For the "Invite People" section, paste in the email of the service account that you retrieved from the spreadsheet. After adding the email to that field, select the "Send" button.
After selecting the "Send" button to confirm the share, you can return to your Draft within Elentra ME: http://elentra-1x-me.localhost/admin/events/drafts?section=edit&draft_id={your_draft_id}
The service account email you entered on Box.com in the share modal will automatically accept the invitation, and you will receive an email in your admin account that informs you of this. Next, if you once again navigate to the "Import & Export" option in Elentra's interface, then select "Import Resources", you should again see the "Import Resources" panel, however this time you should see your Box.com folder that you shared, accessible in the righthand side of the panel.
You can repeat each of the steps outlined in this Sharing Folders subsection for any additional folders you would like to have accessibility within Elentra ME. You will only need to perform these steps once for each new folder you add. Once you finish, the folders will be available across all drafts created in Elentra. You will not need to do this again unless you create a new folder in the root directory of your Box.com account.
Please Note: If you create a subfolder within one of the folders that is already shared to Elentra, it will become available automatically, as subfolders inherit from the shared parent folder.
Please Note: The queues functionality needs to be running in the background in order for the files to be imported into Elentra ME. If you try to import files and don’t see the status message updating as files are being uploaded (e.g. “Uploading 1, 2, 3 of N files. You can safely leave this screen.”), the issue is most likely that queues are not configured correctly or running. Please refer to Step 25 of the Application Server doc for details on enabling Laravel queues.
