3.6 - 3.8 - Web Entry

Overview

Web Entry allows anonymous or external users to start new cases from an external web page where logging into ProcessMaker is optional. Web Entry provides a web link of a Dynaform or multiple steps in the first task of a process. The user completes this Dynaform or multiple steps and submits the data back to ProcessMaker. Web Entry can only be used to start cases.

Web Entry is useful when offering services directly to clients through your organization's web page. For example, a school could use Web Entry to allow prospective students to apply by filling out a ProcessMaker Dynaform embedded in its web page. Likewise, a company could use Web Entry to provide its clients with an order form for its services.

Web Entry provides the "PHP pages with web services" option to generate an external web link to a Dynaform in the initial step of a process. This link can be used in an HTML <a href> tag in an external web page or can be embedded inside an external web page through HTML <frame> or <iframe> tags.

Before Using Web Entries

Before using Web Entries, take into account the following:

• Avoid modifying auto-generated PHP files. It is bad practice to modify these files, because they will regenerate after saving the Web Entry configuration or when the Dynaform involved in the Web Entry is saved from Designer. All modified information will be lost.
• The time to complete a web entry lasts the same time as the session expiration time.
• Print Dynaform and Multiple File Uploader work as if there is a previous existing case.
• The Documents feature does not display, download or upload web entry files. This feature does not allow downloading and uploading files related to a web entry.

Configure a Web Entry

Follow the next steps to configure a Web Entry:

1. Drag and drop an empty start event onto the BPMN designer canvas.

2. Right click the start event and select Web Entry from the context menu.

   

   A new window displays containing the following tabs:

   • Forms
   • Properties
   • Link

   

   The description of each field displays when hovering over the question mark next to the field.

Forms

The Forms option allows to add one or more steps to the Web Entry. A step can be a Dynaform, an Input Document, an Output Document, a trigger, or an external step. After accessing the Web Entry link, it redirects the process to the first step, then to the second and so on.

The Forms tab displays different options to configure the process such as Dynaform(s) or the steps that can be accessed via the link. All the steps configured in this tab must be completed to start a case.

A case is created every time the multiple steps are completed. Web entries that were not completed remain without case number. The case number is created after submitting the Web Entry.

Properties

The Properties tab has the following fields:

• Web Entry Title: Enter a title to be displayed when the Web Entry's windows open.

• Authentication: Select the method of authentication, which can be “Anonymous” or “Require user login”.

  • Anonymous: Select this option to create cases through the "Guest" user available in the ProcessMaker installation by default. In the Anonymous section, the User field remains, but it will be marked as "read-only".

    Note: If upgrading the ProcessMaker installation to PM 3.2.2 and later or creating a new ProcessMaker installation, the Guest user is automatically created with the role PM_GUEST_CASE, which only includes the permission to create cases. The Guest user cannot be edited or deleted by other users, even an Administrator user.

    For old web entry modifications, ProcessMaker changes automatically the user by Guest, and a confirmation message displays when the Web Entry is saved.

    

  • Require user login: Select this option to set a login page where any ProcessMaker user can log in to create a new case using the Web Entry link. Before selecting this option, the following three options become available:

    • Hide Logged Information Bar: A section that contains information about the user logged in, such as the first name, last name and username, is added at the top of the window by default when the Web Entry link is accessed. The user information displayed is determined in the Display Information settings.

      

      If this option is checked, the Web Entry step(s) render without this information bar.

    • Hide Active Session Warning: As of ProcessNaker 3.7.7, disable the active session warning in Links in Active Sessions.

      Note: Anonymous users use the warning message by default no matter if the Hide Active Session Warning option is enabled.

• Callback Action: Select one of the following actions to redirect the web browser after the steps assigned to the Web Entry are completed.
  • Redirect to ProcessMaker predefined response page: A confirmation message displays after the last step is completed.

    

  • Redirect to custom URL: Select this option to redirect the user to a custom URL after the steps of the Web Entry are completed. The URL where the user will be redirected to can be set in the Custom URL field.
  • Redirect to custom URL and to clear login info: Select this option to redirect the user to a custom URL and clear the user session after the steps of the Web Entry are completed.

    Note: The SAML SSO's session is not cleared even if the Clear Login option in the SAML's Web Entry certificate overwrites this condition with its own priority.

• Custom URL: A complete domain and port name where the user will be redirected to when the Web Entry is completed. Note that this field is only available if the callback action selected was Redirect to custom URL or Redirect to custom URL and clear login info. A @=variable can be inserted in this field by clicking the @@ button. Note that the "http://" or "https://" prefix must be included in the variable's value, or when including the variable in the field, as shown in the image below:

  

• Show Task in New Case: Check this option so users who have been assigned to work on the task after the start event which was configured as a Web Entry can see this process in the list of processes of the New Case folder. If this option remains unchecked, the process won't be listed in the New Case folder.

Link

The options in the Link tab allow the user to configure the structure of the link that will be generated.

• Link Generation:
  • Generate link using workspace default values (skin, language): Select this option to generate a link with the default skin, language and hostname.
  • Advanced link generation: Select this option to customize the URL that will be generated.
• Skin: Select the skin that will be used when displaying the steps of the Web Entry. The Classic and Neoclassic skins are the default options.
• Language: Select a language.
• Custom Hostname: Set a hostname that is different to the one that your ProcessMaker server has. For example, if your ProcessMaker URL looks like this: http://192.168.17.45/, and the custom hostname is set to "example.processmaker.com", the URL will change to:
  http://example.processmaker.com/sysworkflow/en/neoclassic/62238512456f1d1505aa403006045594/29116141356f1d15082ae94059299669.php
  This field validates URLs with the following formats:
  1. Protocol + IP + Port
  2. Protocol + Domain name + Port
  If there is a port, it must be filled. The port is not autocompleted.
• Web Entry URL: The URL of the Web Entry that is generated when the Generate Link button is clicked.

Finally, at the bottom of the Web Entry window, there are three buttons.

• Delete: Erases the URL created and clears the Web Entry configuration. The following message displays to confirm the action:

  

  Click the Yes and a quick message displays confirming that the URL was successfully removed from the Web Entry window and from the start event.

  

• Save: Saves the configuration if all the fields are correctly filled in. Otherwise, a message displays indicating which fields need to be corrected or filled in.

• Cancel: Cancels the operation and closes the window.

Access the Link

Follow the next steps to access the link:

1. Copy the Web Entry URL generated into another tab to be redirected to the Web Entry form.

2. In this example, the “Require user login” option was selected, so the user must type their credentials to access the Web Entry form. The skin chosen is “neoclassic”.

   

   If the skin selected is "classic", the login interface would look like this:

   

   After logging on, if the Hide Logged Information Bar box was checked, the top of the Dynaform does not display the user’s information.

   

   If it wasn't checked, the top of the Dynaform displays the user's information.

   

3. Fill out the information requested and submit the form. In this example, the selected callback action is "Redirect to custom URL". The custom URL set to "http://www.processmaker.com". Therefore, after submitting the form, the browser redirects to the ProcessMaker web page.

Links in Active Sessions

Available Version: As of ProcessMaker 3.6.2

When using the Web Entry link and there is an active session open, select whether to continue with the current session or logout from session. It to avoid security vulnerability if any other user has access to your web browser, and impersonate your current session.

Copy the Web Entry URL generated into another tab to be redirected to the Web Entry form. The You have an active ProcessMaker session with user "{name_of_the_user}". Please select one of the options: window displays:

Select one of the options:

• Continue With The Session: This option continues the case with the current logged user.
• Logout From The Active Session: This option logs out the current session and continues the case with the Guest user. However, after submitting the case, it is no longer available to continue.

Note: The SAML SSO Authentication session can only be closed by using the IDP settings and services. Then, Web Entries close previous sessions and does not take into account SAML Sessions. As of ProcessMaker 3.7.5, the You have an active ProcessMaker session with user "{name_of_the_user}". Please select one of the options: window does not display in the following scenarios:

• An Anonymous Web Entry with an active SAML session
• A Logged Web Entry with an active SAML session
• A Logged Web Entry with an active ProcessMaker session

Web Entry Cases Status

Web Entry cases are different to other cases if the Web Entry has multiple steps. Based on this, the Web Entry cases status can be:

• If the Web Entry link starts the case but the case is not submitted, the status is Draft.
• After submitting the form, the status is Draft.
• After routing the case, the status is To Do.

Insert Web Entries into Web Pages

The easiest way to insert a Web Entry form into an external web page is to simply add a link (anchor) to the Web Entry form in the web page.

For example, a web entry generated with the "PHP Pages with Web Services" option has the link:

Then, a link to the Web Entry form could be added to a web page:

To link to the same Web Entry form by clicking the image

A Web Entry form can be embedded inside an existing web page through the use of HTML frames

For example, the same web entry form can be embedded in a HTML frameset like this:

Likewise, the same web entry form could be embedded in an <iframe>.

If the Web Entry form was generated with the Single HTML option, then it just generates the HTML code. Paste that code into an HTML file and save the file in a public place in the web server, so it can be used as the src for the frame.

Structure of the Web Entry Tables

The wf_<workspace>.WEB_ENTRY and wf_<workspace>.WEB_ENTRY_EVENT tables provide handy information about Web Entries, which can be useful to consult in SQL queries.

Web Entry Table

WEB_ENTRY_EVENT Table

Web Entry Endpoints

The current methods implemented for web entries in the ProcessMaker API designer are listed below:

1. Get a list of Web Entries

2. Get a Web Entry

3. Create a new Web Entry

4. Update a Web Entry

5. Delete a Web Entry

6. Generate a Web Entry Link

Web Entry Event Endpoints Parameters

Get Web Entries List

Gets the list of Web Entries in a specific process.

GET /api/1.0/{workspace}/project/{process_uid}/web-entry-events

Parameters:

Name	Type	Description
workspace	String	Workspace name.
process_uid	String	Process UID.

Result:

Type	Description
array	Returns an array of objects containing data about each web entry.

Example:

Response

Get a Web Entry

Gets information about a specific Web Entry.

GET /api/1.0/{workspace}/project/{process_uid}/web-entry-event/{wee_uid}

Parameters:

Name	Type	Description
workspace	String	Workspace name.
process_uid	String	Process UID
wee_uid	String	Web Entry UID.

Result:

Type	Description
array	Returns an array of objects containing data about the web entry.

Example:

Response

Create a New Web Entry

Creates a Web Entry.

POST /api/1.0/{workspace}/project/{process_uid}/web-entry-event

Parameters:

Name	Type	Description
workspace	String	Workspace name.
process_uid	String	Process UID.

Required Fields for a Web Entry with Multiple Steps and Anonymous User Authentication:

Name	Type	Description
evn_uid	String	The UID of the start event where the Web Entry will be configured.
act_uid	String	The UID of the task that is connected to the start event.
wee_title	String	This value is the same as "evn_uid". This field was preserved to maintain compatibility with Web Entry v.1
we_type	String	The type of Web Entry, which must be set to "MULTIPLE" to create a web entry with multiple steps.
usr_uid	String	User UID.

Example:

Optional Fields:

See the parameter table to read more about the additional parameters.

Result:

Type	Description
array	Returns an array of objects containing data about the Web Entry created.

Example:

Response

Note: When an anonymous user creates a Web Entry with multiple steps, the endpoint response defines automatically the user Guest.

Update a Web Entry

Updates a specified Web Entry.

PUT /api/1.0/{workspace}/project/{process_uid}/web-entry-event/{wee_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name.
process_uid	String	Process UID
wee_uid	String	Web Entry UID

Required Parameters:

Name	Type	Description
tas_uid	String	Task UID
dyn_uid	String	Dynaform UID
usr_uid	String	User UID
we_title	String	Title
we_method	String	Creation method = "WS"
we_input_document_access	String	Input document access

Optional Fields:

Name	Type	Description
we_description	String	Description
we_data	String	Data

See the parameter table to read more about the additional parameters.

Result:

Type	Description
array	Returns an array of objects containing data about each web entry.

Example:

Request

Response

Note: When an anonymous user creates a Web Entry with multiple steps, the endpoint response defines automatically the user Guest.

Delete a Web Entry

Removes a Web Entry from a start event.

DELETE /api/1.0/{workspace}/project/{process_uid}/web-entry-event/{wee_uid}

Parameters:

Name	Type	Description
workspace	String	Workspace name.
process_uid	String	Process UID
wee_uid	String	Web Entry UID

Result:

Type	Description
array	Returns an array containing the response.

Example:

Response

Generate a Web Entry Link

Generates the web entry link.

GET /api/1.0/{workspace}/project/{process_uid}/web-entry-event/{wee_uid}/generate-link

Parameters:

Name	Type	Description
workspace	String	Workspace name.
process_uid	String	Process UID
wee_uid	String	Web Entry UID

Result:

Type	Description
array	Returns an array containing the Web Entry link.

Example:

Response

Get Languages of a Workspace

Gets the languages installed on a specific workspace. This endpoint has public access, which means that both users that are logged in and not logged in have access to the endpoint's information.

GET /api/1.0/{workspace}/system/languages

Parameters:

Name	Type	Description
workspace	String	Workspace name.

Result:

Type	Description
array	Returns an array of objects containing the languages installed on the specified workspace.

Example:

Response

Get Skins of a Workspace

Gets the skins of a specific workspace.

GET /api/1.0/{workspace}/system/skins

Parameters:

Name	Type	Description
workspace	String	Workspace name.

Result:

Type	Description
array	Returns an array of objects containing the skins of the specified workspace.

Example:

Response