Create Web Portal Shares¶

Web Portal shares can be created in several ways, either manually through the user interface, via SEAL OP-CLI, or by directly accessing the Operator REST API, for example via DPF. The PLOSSYS 4 Web Portal printer uses SEAL OP-CLI.

A share has the following settings which can be specified during its creation or by editing. For detailed instructions refer to the following sections.

access notifications: optional, if enabled and the email service is configured, notification emails are sent when access to shares is granted or used.

Hint - new notification emails

If you change the expiration date of an expired share with access notifications enabled, new notification emails are sent to its recipients. If you change the expiration date of a not yet expired share, no emails are sent.
description: optional, additional description of the share set by its creator or its owner.
link access: optional, if public access to shares and this option are enabled, users not listed in the OIDC identity provider can access the share via the provided link. For public access, refer to Enable Public Link Access to Shares on Windows or Linux.
owner: optional, user on whose behalf the share has been created via SEAL OP-CLI or REST API. Not usable via user interface.
share name: Title or subject of the share used in the Web Portal panel and notifications.
end date: optional, expiration date of the share. Default is the current date. The share is not deleted instantly afterwards but can get restored by its owner via the user interface.
users: optional, email addresses of users that should get access to the share. These users have to be registered in the OIDC identity provider used with SEAL Operator.

Manually¶

To create a Web Portal Share manually execute the following steps:

Log on to the user interface and open a Web Portal Panel.
In the Owned Shares section click the Add Share button.
Enter a name for the share and adjust the expiration date. Default for the expiration date is the current date.
Leave the Add recipients to this share field empty. Add users only after you have added all files to the share.
If you disable the Access notifications checkbox, neither does the assignee get a notification email about the new share nor do you get one when the share is accessed for the first time.

Hint - how to change the notification emails

The templates for the email notifications can be changed in the configuration settings. For detailed instructions, refer to Set Up Email Service on Linux or Windows.
Click Create to finish.

Hint - add users later

Adding files to a share does not trigger further emails. Therefore, do not add users when you create an empty share. First add all files to the share. Then add the other users. Otherwise, the users receive a notification email while the share is still empty. They do not learn when the files are available.

Via a PLOSSYS 4 Printer¶

In PLOSSYS 4, you can output documents directly to the Web Portal in SEAL Operator. For this, you configure a printer in PLOSSYS 4 via which a Web Portal share is created containing the output documents. You also have to make changes to the Web Portal connector.

The following requirements have to be fulfilled:

In SEAL Operator, Web Portal is configured, refer to Connect the Web Portal on Windows or Linux.
The seal.webportal printer template containing seal.webportal.pl as of version 1.20 is available for installing the printer via easyPRIMA or via PLOSSYS 4 directly.

Configure the Connection to the Web Portal¶

The following settings are configured in the templates in easyPRIMA before distributing the Web Portal printer. When installing the printer in PLOSSYS 4 directly, you have to change the configuration file of the Web Portal printer after the installation.

Edit the seal.webportal.cfg file in the server/edc/templates/seal.operator_webportal.pdf_vr_pdf directory when using easyPRIMA or in the server/plotserv/plotter directory when the printer has been installed in PLOSSYS 4 directly.
Specify the following keys in the [OPERATOR] section:
- OPCLI_AUTH_CLIENT_SECRET: mandatory, secret of the command line client
- USER: mandatory, user name of the technical user who has permission to access the SEAL Operator server's REST API and create Web Portal shares
- PASS: mandatory, password of the technical user. It can be clear text or encrypted via sealencrypt.
- CONFIRM_ACCESS_MAIL: optional, specifies if a notification email is sent when the share is accessed. Default: Y.
- PORTAL_TTL: optional, lifetime of the Web Portal share. Default: 10d, which means 10 days.

Example - operator section of template seal.operator_webportal.pdf_vr_pdf

[OPERATOR]
#OPCLI_AUTH_CLIENT_SECRET = <secret of command line client>
#USER = <name of technical Operator user>
#PASS = <password of technical Operator user>
CONFIRM_ACCESS_MAIL = Y
PORTAL_TTL = 10d

Create and Configure the Web Portal Printer¶

Create a Web Portal printer using the seal.webportal printer template.
With the Web Portal printer, set the QUEUE parameter to OPERATOR/<default_owner>/<operator_server_url> where
- <default_owner> is the user name of the default owner of the Web Portal share. The owner is the user on whose behalf the share is created.
- <operator_server_url> is the URL of the SEAL Operator server's REST API. Normally, this is https://<operator_server_name>:3008.
Example - QUEUE parameter

If the default owner has the user name john.doe, the QUEUE parameter is OPERATOR/john.doe/https://operator.example.com:3008.

Install SEAL OP-CLI¶

The PLOSSYS 4 Web Portal printer uses the Operator command line tool, SEAL OP-CLI, for creating the Web Portal shares. Therefore, you have to install SEAL OP-CLI version 5.13.0 or higher on the PLOSSYS 4 server. For how to do this, refer to Install SEAL OP-CLI on Linux or Windows.

Configure the OIDC Client Permissions¶

Set the required permissions for the OIDC clients seal-print-client, seal-opcli, and seal-webportal:

Hint - generate a template

SEAL Operator CLI can generate a template for ALLOWED_OIDC_CLIENTS. For details, refer to Administrate the System Configuration.

Open a command prompt.
Export the complete configuration of SEAL Operator from Consul to a YAML file. This ensures that you edit the current configuration.
```
operator config export <filename>.yml --insecure
```
Edit the exported file <filename>.yml.
In the env section, specify the key ALLOWED_OIDC_CLIENTS for all services in the any section. Use the value from the first example in Configure Roles - Examples on Linux or Windows. The example enables the creation of documents, tasks, panels, and Web Portal shares by a technical user on behalf of a real user.
Save the <filename>.yml file.

Re-import the file to Consul.

operator config import <filename>.yml --insecure

Check the imported value for ALLOWED_OIDC_CLIENTS:

operator config get ALLOWED_OIDC_CLIENTS --insecure

Literature

For the description of possible keys and values for ALLOWED_OIDC_CLIENTS, refer to Available Keys and Values on Windows or Linux.

Specify PLOSSYS 4 Job Parameters¶

The following job parameters affect the creation of the Web Portal share via the Web Portal printer:

PLS_PLOTID: mandatory, name of the share if it is a single print job.
PLS_RECEIVER: mandatory, email addresses of users the Web Portal share is shared with. The addresses are separated by blanks.
PLS_SENDER: optional, name of the user on whose behalf the Web Portal share is created. Default: the owner specified in the QUEUE parameter.
PLS_SET_NAME: optional, name of the share if the print job is a set collation.
PLS_SUBJECT: optional, description of the Web Portal share.

Expiration date and access notification of a share depend on Web Portal configuration values and cannot be set individually for each job.

Via REST API¶

Workflow¶

You can use the API to create Web Portal shares. When outputting order data from SAP it might be required to automatically create subfolders within the share.

The workflow follows these steps:

Discover the token endpoint from the identity provider (IDP), then request an access token via the password grant. Send the token as Authorization: Bearer <token> header on every following call.
Create the share with a POST to the repo endpoint. The response links.self.href is the share's address for the next steps.
Create a subfolder inside the share with a POST to the share's href, body {"name":"<name>","type":"collection"}.
Create a document inside the subfolder with a POST to the subfolder's href, body {"name":"<name>","type":"document"}.
Upload the file content with a PUT to the document's href plus /content.

Repeat steps 3 to 5 for each subfolder or document to add.

Authenticate via Client Credentials for MFA-Enforced Identity Providers¶

The steps above use the password grant to retrieve the access token. Some identity providers reject the password grant when multi-factor authentication (MFA) is enforced for the whole tenant. Azure AD (Microsoft Entra ID) returns error AADSTS50158: External security challenge not satisfied (error code 50158) in that case.

For such tenants, use the client credentials grant instead of the password grant. Request the token from the same token endpoint, with grant_type=client_credentials, client_id, and client_secret instead of the user name and password.

Caution - client credentials grant has no user identity

The client credentials grant returns an access token for the OIDC client itself, not for a specific user.

Hint - seal-dpf-workingunit-webportal

The DPF working unit seal-dpf-workingunit-webportal implements this flow through its own input parameters WEBPORTAL_AUTH_GRANT_TYPE, WEBPORTAL_X_USER_AUTH, and WEBPORTAL_X_USER_AUTH_FILE. These are parameters of the working unit, not of SEAL Operator. For their exact usage, contact your Technical Project Manager at SEAL Systems.

Literature - API description

For more information about the REST API interface, refer to API Description.