Skip to content

Publishing the workflow as an app

You can make your workflow available to other pSeven Enterprise users by publishing it as a web app in the AppsHub repository. To publish a workflow, select its folder in the Explorer panel, and then use the Publish to AppsHub... command from the panel menu. To open the published app in AppsHub, hover over its thumbnail and click the icon in the upper right corner of the thumbnail.

Understanding the app UI

Access to the workflow from AppsHub is provided by the web app user interface (app UI). The app UI is a part of the workflow; its implementation files are located in the UI folder in the workflow. Every new workflow contains a stock app UI, which provides for entering parameters, uploading input files, running the app, viewing and downloading the app run log, viewing the results and downloading output files. You can replace the stock app UI with your custom app UI - upload the custom app UI files to the UI folder inside your workflow before you publish it.

You can preview the app UI by opening index.html from the UI folder

While preparing to publish a workflow, you can get a preview of its app UI by opening the index.html file from the UI folder:

  1. In the Explorer panel, go to your workflow folder. From there, open the UI folder.
  2. In the UI folder, double-click the index.html file.

The stock app UI is a web page containing several areas:

  • Page header - at the top of the page, the page header displays the name of the workflow. An app user can start the workflow by clicking the Calculate button on the right side of the page header.
  • App description - below the page header, you can place explanatory text describing the app, as well as instructions on how to use this app.
  • Parameters - the Parameters area displays all the workflow input parameters specified in the workflow setup. Each parameter has a field under its name for viewing, entering and editing the parameter value.
  • Parameters description - under the Parameters heading, you can place explanatory text describing the parameters and their intended purposes, as well as instructions on how to set the parameters.
  • Results - the Results area displays all the workflow results that should be shown according to the workflow setup. Each result has a field under its name for viewing the result value.
  • Results description - under the Results heading, you can place explanatory text to help understand the results output by the app workflow.
  • Report - the Report area displays a web page loaded from the file named REPORT.html that is located in the run directory root of this app's workflow. The UI periodically reloads REPORT.html and refreshes the Report area, which enables the report to dynamically present intermediate results of the workflow. The Report area is hidden if the REPORT.html file is empty or missing. See Displaying reports in the stock app UI.

Adding descriptions to the stock app UI

The stock app UI can display the app description, the parameters description, and the results description. These descriptions are stored in the text file README.md located in the root of the workflow folder. To add descriptions:

  1. Prepare a text file with your descriptions. The file name must be README.md. The file should be saved with the UTF-8 encoding.

    New workflows contain a default README.md file, which you can download and use as a template.

  2. In the Explorer panel, go to your workflow folder and upload your README.md file to that folder.

The text in the README.md file consists of three parts delimited by HTML comment labels:

  • App description
    • <!-- APPLICATION DESCRIPTION BEGIN --> - marks the beginning of the app description.
    • <!-- APPLICATION DESCRIPTION END --> - marks the end of the app description.
  • Parameters description
    • <!-- PARAMETERS DESCRIPTION BEGIN --> - marks the beginning of the parameters description.
    • <!-- PARAMETERS DESCRIPTION END --> - marks the end of the parameters description.
  • Results description
    • <!-- RESULTS DESCRIPTION BEGIN --> - marks the beginning of the results description.
    • <!-- RESULTS DESCRIPTION END --> - marks the end of the results description.

Thus, the text in the README.md file should be organized as follows:

<!-- APPLICATION DESCRIPTION BEGIN -->

Your app description goes here.

<!-- APPLICATION DESCRIPTION END -->

<!-- PARAMETERS DESCRIPTION BEGIN -->

Your parameters description goes here.

<!-- PARAMETERS DESCRIPTION END -->

<!-- RESULTS DESCRIPTION BEGIN -->

Your results description goes here.

<!-- RESULTS DESCRIPTION END -->

If you do not need all the descriptions, remove the unnecessary parts of the text along with their <!-- ... BEGIN --> and <!-- ... END --> labels.

To format your descriptions, use Markdown - a lightweight markup language that allows you to create rich text by adding markup tags to plain text. In this way, you can markup headings, lists and tables, add links and so on. For more information on the version of Markdown used in pSeven Enterprise, visit the CommonMark website.

Displaying reports in the stock app UI

The stock app UI can display a dynamic report on the workflow execution. To implement such a report, the workflow must periodically update the REPORT.html file in the run directory root. You can use this HTML file, for example, to enhance your app with auto-updating tables or plots, which present intermediate results of the workflow.

When you create a new workflow, an empty REPORT.html template is automatically created in workflow files. Since that template is empty, the stock app UI does not display the Report area by default. If you want to display a report in your app, your workflow must update REPORT.html while running.

To update the REPORT.html file, you can use a Python script block. In your script, use api.rundir to compose the file path:

# Work with REPORT.html in the current run directory root.
import api
report = api.rundir / 'REPORT.html'

# Generate the report contents.
report_data = """<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
  </head>
  <body>
    <p>Report text and other contents.</p>
  </body>
</html>
"""

# Write the report to REPORT.html.
report.write_text(report_data, encoding='utf-8')

For an example of plotting intermediate results, you can see the Intermediate result and evaluation history section of the Design space exploration block guide.

Working with app versions

The AppsHub repository allows multiple versions of a workflow to be published within a single app. Accordingly, each app in AppsHub can have one or more versions, with a separate workflow for each version. It is also possible to modify a previously published version by replacing its workflow with an updated one - to track such updates, each app version also has a revision number. For example: "ToySolver v2r5" is the fifth revision of the second version of the ToySolver app.

When using your app from the AppsHub web interface or through the REST API, app users can specify the desired app version. This is not required - if they do not specify an app version, they are going to use its default version. You select which version of your app is the default. You can change this selection at any time in your app's settings, or when you publish an update for your app.

AppsHub does not ensure the backward compatibility of your apps

As app developer, you should bear in mind that pSeven Enterprise does not check in any way the compatibility of your app updates with the existing REST clients.

If you designate a different default version, all clients that do not specify the app version get switched automatically to the version you have designated. Such a switch may cause failures in client operation due to incompatibility with the workflow of that app version. When you change the default version selection, you must ensure compatibility with existing app clients.

The same applies to the situation where you publish a new revision of an existing version: you must ensure that the new revision is compatible with the REST clients that specify the version you are updating.

Some typical cases of using app versions:

  • You want to update the app with a new workflow but some of its users (REST clients) can only work with a previously published workflow. In this case, publish the new workflow as a new version of your app. The clients that specify the app version will continue to use that version of the app.
  • You want to update the app and to direct all users and clients to this update by default. In this case, publish the update as a new app version and make the new version default. If the update breaks app compatibility with REST clients, you will be able to revert the default version setting. If you find that the update did not create compatibility issues, and you no longer the backup of the previously default app version, you can delete that version in your app's settings.
  • You want to update a certain version of your app, and you are sure that the update does not break compatibility with the existing REST clients - for example, it contains only bugfixes, or updates the app UI only. In this case, publish the workflow with the existing version number. That version's revision number will be automatically incremented by one.

The workflow publish dialog also allows you to publish the workflow as a previously deleted version of the app, thus restoring that app version. In this case, the revision numbering does not reset - for example, if you delete app v2r5 and restore afterwards, it becomes v2r6.

On the app info page, which opens by clicking the app thumbnail in AppsHub, app users can work with different app versions:

  • Select the app version. Most commands on the page work with the currently selected version.
  • Open the selected app version.
  • View run results of the selected version.
  • Get the workflow of the selected app version, if you have allowed this when publishing the workflow.
  • Get the default API URL, which points to the final revision of the app version that you have designated as the default version.
  • Get the API URL of the selected version, which always points to the final revision of this specific version.

You, as app developer, have access to a few additional version control options:

  • Designate the selected app version as the default.
  • Delete the selected app version.
  • Delete the app completely, with all its versions.

App URL parameters

Each published app has a unique URL: {sign-in URL}/appshub/.app/{app ID}/, where {sign-in URL} is the pSeven Enterprise sign-in URL and {app ID} is a unique identifier assigned to an app upon publishing. A user signed in to AppsHub can open an app directly by its URL.

If you link to an app from another web page or application, you can add a query string to the app URL. The stock app UI recognizes query string parameters as app arguments and automatically sets parameter values in the UI. Parameter names in the query string are app (workflow) parameter names with the added arg- prefix. For example, if your app has a numeric parameter named some value and a string parameter named some label, an URL like the following sets them to 42 and case #N respectively:

{sign-in URL}/appshub/.app/{app ID}/?arg-some%20value=42&arg-some%20label=case%20%23N

Note that parameter names and values must be URL-encoded as shown in the example above, and the arg- prefix is required in each parameter name.

The app URL is not the same as the app API URL

The app URL described here is the URL that opens the app page with its end user interface. You can use query string parameters in the app URL to preset parameter values on the app page displayed to the user who follows that URL.

The app API URL referenced in the REST API guide section is the programming interface URL used to run an app and process its results. The app API URL exposes the app REST API endpoints and does not open the app UI.