App reference¶

The App reference block lets you embed any app from AppsHub into your workflows. The embedded app runs receiving its input parameters and files from the workflow, and the app's results and output files become available in the workflow so other blocks can read them. This effectively enables using AppsHub as an extension of the block library: you can compose workflows reusable as blocks and share them to your team in your workspace on AppsHub.

App reference is a beta block

The App reference block is in beta. Future pSeven Enterprise updates will keep compatibility with the current version of the block, but this beta version may still have some features missing or not yet working as intended.

Getting started¶

General steps to set up an App reference block are:

In the block window, select the app and its version you want to embed. Save the block.
Select the block in the workflow and review its ports in the Block properties pane.
- Set the input port values or link the input ports to the blocks providing these values.
- Link output ports to the blocks that process the app's results.
Set up the app's input files:
- If the app doesn't require any input files: assign an empty list ([]) to the block's Input files input port. This is an additional port found in the File management group in Inputs in the Block properties pane.
  
  By default, the block uploads all files from its working directory to the app run. An empty list of input files explicitly disables the upload.
- If the app requires input files to run, check if the block provides input ports for those files. If there are no such ports, set up file upload to the app.
Set up the output files:
- If you don't need the app's result files: assign an empty list ([]) to the Output files port of the File management group in Block properties - Inputs.
  
  By default, the block downloads all result files from the app run to its working directory. An empty list of input files explicitly disables the download.
- Check if the block provides output ports for the app's result files. If not, set up file download from the app.

The input and output ports that appear on the block once you select the app are actually the inputs and outputs of the app's workflow. The app UI might hide some of those, or its parameters and results might have names that do not match the names in the workflow exactly. If you are unsure how do the App reference block ports correspond to the app parameters and results, export the workflow from the app and review the inputs and outputs of that workflow.

Export the app's workflow for review

Go to AppsHub and find the app you want to embed.
Hover your cursor over this app and click the button that appears at the top right.
In the Get workflow dialog that opens, choose the folder where you want to save the app's worfklow.
Go to Studio and open the exported workflow.

App developers can choose to disable the workflow export for their apps. If you cannot export the workflow, contact the user who published the app to get help.

When the App reference block runs, it actually deploys and launches a new app run in AppsHub. These runs work the same as normal app runs: you can open them in AppsHub, review their results and logs, and so on.

File management¶

Depending on the embedded app, file exchange between the App reference block and other blocks is set up in different ways:

If the ports for input and output files appear on the App reference block once you select an app to embed, connect links to these ports to transfer files. In this case no additional setup is required. Such ports only appear if the app's workflow supports file inputs and outputs - these are ports of a special type used for files.
If no file ports appear, it means the app requires that you set up file uploads and downloads as described in this section, and set up the same working directory for App reference and the blocks that prepare or process the files required or generated by the app.

Uploading input files¶

To upload files to the embedded app, set up your workflow so that all files required by the app are found in the App reference block's working directory when it starts. By default, before launching an app run, the App reference block uploads all files from its working directory to that run's directory.

To avoid unnecessary uploads when the block's working directory contains files that the app doesn't need, use the Input files folder and Input files ports to set up upload rules. These ports are found in the File management group in the Inputs section of the Block properties pane.

Input files folder (string): specify a subfolder within the block's working directory. The block will upload only the files from this subfolder. This can be a folder name or a path relative to the working directory, such as subfolder/nested folder.
Input files (list of strings): provide the names of files or folders to upload. These names can contain wildcards, such as * or ?.
- To disable all upload, specify an empty list here.
- If you don't assign any value to this port, the block uploads all files from its working directory or from the folder specified to the Input files folder port.

Downloading result files¶

By default, the block downloads all app's result files to its working directory once the app run is complete.

To avoid unnecessary downloads when you don't need some of the result files, use the Output files folder and Output files ports to set up download rules. These ports are found in the File management group in the Inputs section of the Block properties pane.

Output files folder (string): specify a subfolder within the block's working directory. The block will download files to this subfolder. This can be a folder name or a path relative to the working directory, such as subfolder/nested folder.
Output files (list of strings): provide the names of files or folders to download. These names can contain wildcards, such as * or ?.
- To disable all download, specify an empty list here.
- If you don't assign any value to this port, the block downloads all new files created by the app run - that is, by default excludes the input files it has uploaded while preparing the app run.

Notes¶

The App reference block actually launches normal app runs, and these runs are saved in your personal file storage in pSeven Enterprise. This means you can view their results and logs in AppsHub just like when you run the app manually. However due to this, these runs also consume your storage space. To reclaim that space, delete the app runs you no longer need using the Runs sidebar in AppsHub.
If an app has a custom UI, it may have inputs, outputs, or settings that do not appear as ports of the App reference block embedding that app. This is not a block error: the developers are free to modify the app UI - for instance, adding custom settings that the App reference block cannot access. To fix this, the app developer should update the app's workflow, adding workflow inputs and outputs (root ports) for the settings you need. Then those settings will be available as App reference block ports when you embed the updated app version.