14 - Adding documents to the workspace

Documents can be created in the workspace and made accessible to app users.

This is done via the Documents module. Documents can include PDFs, spreadsheets, slides, audio and video files, as well as any online content that can be associated with the workspace via a URL.

Once a document is created in the workspace, it can be made accessible to app users via pages, sessions, feeds, the app menu, or a webcast, and configuration settings can be used to manage who can access the files and when.

To create a document in the workspace, Backstage users need to:

1. Create the document shell in the workspace.
2. Configure the document's settings in the workspace.
3. Upload the file (or add the URL) that will be associated to the document in the workspace.
4. Associate the uploaded file (or URL) to the created document.

In this section we will take you through the above steps in more detail, to allow you to create documents in the workspace and make them available to app users.

You can access the Documents module through the Content category in the Backstage main menu.

More advanced information on the Documents module is also available in the following articles:

• Documents
• Document file sizes and recommendations articles
• Sharing videos via the workspace

Creating a document in the workspace

Please follow the below steps to create a document in your workspace:

1. Go to the Content category in the workspace main menu, and select Documents.
2. Click on the New document button. Here you can enter the below information for the document you are creating:
   
3. Enter the title of the document in the Name field.
   
   
4. Upload and select the file associated to the document, using the File field.
   If the file is already uploaded to the workspace, simply select it in the dropdown list.
   If the file is not yet uploaded, simply click on UPLOAD, and select the file to be uploaded.
   
   Once the file is uploaded, you can select it in the dropdown list to associate it to the document you are creating:
   
   Using the Availability options, you can select whether the document will be available to the app user only when they have internet access, or all the time (offline included).
   
   Using the Unique identifier field, you can enter an identifier for the document, which will become the file's name in Backstage. If you leave this field blank the identifier will be created automatically by the system, using the file name.
   
   For more information on uploading document(s) please refer to the Uploading and downloading documents section below.
   
   
5. Select the type of document you are creating, in the Document type field, based on the file the document will be associated to:

• If the file is a PDFs, select PDF.
• When associating the document to an external online source, select Website.
• For audio files, select Audio.
• For video files, select Video.
• For longer videos that require embedding, use Webcast, inserting the embed URL from Vimeo or YouTube, in the following format:
 https://player.youtube.com/emboded/xxxx
• For Excel files, Word files or PowerPoint presentations, select Other.

Important: Videos with embedded URLs such as youtube.com/emboded/xxxx will always play directly in the web app, however when played in the mobile app the video will not play directly in the app, but instead will play in the mobile device's browser. If the embed URL ends in .mp4 or .m3u8, then the video will play directly in the mobile app player and in the web app.

You can also use any of the below options for the document, depending on the type document you are creating and how you want it to be used:

Icon
Select an icon that will be displayed for the document, for example when the document is added as a button in the app menu.

Autoplay media
Select this if you'd like the uploaded media to autoplay. This is applicable only for uploaded audio and video files. Webcast documents will only autoplay based on what the URL dictates (i.e. if an autoplay parameter is set-up).

Enable sharing (PDF only)
Select this to allow documents to be shared by app users externally. A share button appears when app users view the PDF.

Description
Enter the description of the document, visible in Backstage only.

Block viewing until
Here you configure the time and a date at which the document can be viewed by app users.
Before this time and date, the document will not be available to be viewed, and the Error message (see below) will appear instead. The default message is "No content to show here".

Error message
This message will appear when app users try to view a blocked document, when using the Block viewing until option (see above) for the document.

URL
For online documents or websites, paste the URL to the online content.

Open URL on devices default browser?

By default, documents are opened using the in-app browser. Here you can enable this option to open documents or websites in the app user's device's default browser.

Note: All websites or webpages (http or https) are always opened in the in-app browser, even if this option is selected for the document.

For web app users, when opening a PDF documents, the PDF will either be open directly in the app (if this option is not selected), or in a new page if the option is checked.

Enable annotations
Select this to allow app users to make notes on documents. A button appears when app users view the document, allowing them to add notes.

Disable on device caching
By default, documents viewed in the app are stored in the cache, so that they are only downloaded once but can be viewed multiple times. Using this option will no longer save downloaded documents in the cache. It can be useful when referring to live documents that are updated in real-time, or larger files such as videos.

Enable bookmarks
Selecting this allows the document to be bookmarked in the app. This adds the document to the Bookmarks section of the app for easy future reference

Enable landscape mode on phones
Select this to allow documents to be displayed in landscape on phones, when rotation is enabled on the device.

Once you have added all the necessary information and settings for the document, click on Save to finish creating the document in the workspace.

The document will now appear in the Documents tab, like in the example below:

By clicking on this document you can access the above entered information and make any changes needed, including changing the file associated to the document.

Giving app users access to the document in the app

Now that you have created the document following the steps above, you will need to make the document accessible to the app users.

This can be done by adding a button to the app menu that will take the user directly to the document when tapped, or by associating the document to another element in the app such as a user or speaker profile, a feed, a session, a page, etc.

Adding the document as a button in the app menu

Items, including links to documents, can be added to the app menu using the app menu editor.

1. Go to the Design category in the workspace main menu, and select App menu.
2. In the Add an item field, select Generic item launcher.
3. In the Label field, click on the drop down list, and then click on Add a new shared translation.
4. In the pop-up enter a label name. Here we have entered app_menu.my_document.
5. Add the text for the app menu button. Here we have entered Welcome to our event!.
6. Select an icon.
7. In the Item to open field, select Document in the dropdown list, and then select the document to be linked to the app menu button. Here we have selected our Welcome to our event document, created above.
8. Click on Save.

Once added, the new button for accessing the document is available in the list to the left, at the bottom where it can be moved to the appropriate position in the app menu:

Below you can see how the app menu will look in Backstage, and how it will look in the app:

App menu in Backstage:

App menu in the app:

For more information on managing the app menu, please refer to the next article in this Getting started series called Building the app menu.

Adding the document as a link in a page or a form

To link a document to a page or a form, simply go to the page or form display template, and add a link list or text component, where you can add a link to the document.

More information on adding content to a page or a form is available here.

Uploading and downloading assets

Files can be uploaded and associated to documents in Backstage directly when creating a document, as explained above in the Creating a document in the workspace, but you can also go to the Assets tab where other functionalities are available, such as:

• Uploading individual or multiple documents, using the Upload button.
  To upload multiple documents, simply place the documents into a compressed (.zip) file, and upload the .zip file using the Upload button. The documents contained in the .zip file will be uploaded individually and appear in the assets tab.
• Downloading all documents from the workspace, using the Download button. The documents will be downloaded as part of a .zip file.
• Downloading a list of the documents in the workspace, using the Export XLS file button.
• Uploading lists of documents in the workspace, using the Import XLS file button.

To perform the above actions, simply use the available buttons:

File formats and recommendations when uploading files

It is important that the files uploaded to the workspace via the Assets tab in the Documents module follow the below requirements, otherwise errors may occur:

• The file name must include the file extension (.pdf / .xls / etc.) in order to be uploaded.
  When compressing files using a Mac, the file name may be removed. Please check before uploading a file that the extension is present in the file name.
  
  
• Please ensure that the file name does not contain any special characters at all, including any periods ".", otherwise the file will not be uploaded.
  
  
• When creating a .zip file containing multiple documents, using a Mac, in view of uploading the zip file as a bulk upload of documents, please check that no additional superfluous files were created automatically in the resulting .zip file. If there are some superfluous files there, please delete them as otherwise they will be uploaded to your workspace. This only happens with Mac, not with Windows.

For more information on file sizes and recommendations, please refer to the File size recommendation article.

Batch linking uploaded assets to documents 

Creating individual documents and linking them one by one to their assets may take a while if you have a lot of documents to create in the workspace.

Thankfully, you can save time by doing a batch upload of assets, and then using an XLS upload to create the necessary documents in the workspace and link them to their corresponding assets.

1. Start by uploading all the files you need for your documents as assets, using a .zip file, via the Assets tab. Remember to take note of the File formats and recommendations when doing this, to avoid any errors.
   
   
2. Next, in the Documents tab, export the document list as an XLS file, by clicking on the Export XLS button:
   
   Note: If no documents are created already here, please create a single document manually before doing the export. This will ensure that you can use the export properly in the next steps.
   
   
3. Open the exported XLS file on your computer. We will start to populate this file with all the document and asset information needed in the next steps.
4. Copy the data from the second line of the XLS file, and paste it into the following lines in the report. Do this so that you create a new line of data for each document you wish to add to the workspace. Next, delete all the data from column A in the new lines you add (which we will replace in step 5 below):
   
   
   
5. For each new line (i.e. each new document you are creating in the workspace), do the following:
   In the A column - fp_ext_id: Give unique IDs to (or just number) the new documents that you are adding. For example 1 - 50, etc. Make sure that each document (line) in the report has a unique fp_ext_id number.
   In the B column - name: Enter the name of the document that you wish to create.
   In the F column - hosted_doc: You need to edit the existing path in the XLS (copied previously), by adding the name of the new asset that is already uploaded to Backstage, and that you wish to link to this new document:
   For example, replace the text in red in the can_asset.Engagement-maturity-curve/file.pdf path.
   You may also need to change the file extension (.pdf) so that it matches the new assets file type.
   
   Note: You can easily find and copy the new asset name from the Assets tab in Backstage, in the fp_ext_id column (in the example below, the asset name was Engagement-maturity-curve):
   
   
   
6. Do the above changes for each new line in the XLS file, so that each line has the document name (name) and the asset path (hosted_doc) columns populated properly.
   Do not make any other changes to the other columns in the XLS file.
   
   
7. Save your changes in the XLS file. Then in the Documents tab in Backstage, click on Import XLS, and select the XLS file to import. All the documents should now be created in the list and linked to their corresponding assets, per the changes made to the XLS file that you uploaded.

 

NEXT STEP
For the next steps in this Getting started series, please continue to the Building the app menu article.