Embed a Start Form in an External Application

Sometimes users of an external service may want to invoke a process instance from within their application without navigating to Workspace. They can do so by embedding the start form in their application. This not only saves the effort of navigating to Process Automation from their application, but ensures seamless user experience as they're always in the context of their primary application.

For example, in case of an Employee Onboarding application in Oracle HCM Cloud, a new employee must fill a form with details and submit it. This is the start form that would initiate the onboarding process. By embedding the start form's URL in the Oracle HCM Cloud application, the start form can be accessed and opened from Oracle HCM Cloud itself without navigating to Workspace user interface in Process Automation. The URL of the start form can open in a new browser window or can be embedded in iFrame.

Process automation lets you load a Process Automation start form with the context of an existing application by passing data through the URL query parameters. Data in the URL query parameters can then be used in the On Load events to make API calls to external systems to get more information. This saves the user the effort of re-entering details required to finish tasks. Additionally, you can also pass the data in base64 encoded format.

You can only pass first level data in the URL query parameters. For example, form.department=Cloud.

For example, Oracle HCM Journeys lets you create an external URL based tasks and pass the context details of the journey, task and user performing the activity to the URL. This data can be populated in the Process Automation start form. Subsequently, the Process Automation start form can trigger an On Load event to query a HCM API to retrieve more information about the user, and then pre-populate fields such as name, department, and cost center.

Here is an example of how you can send data using URL query parameters:

http://<IP address and port>/process/workspace/pages.html?root=startForm&reloadOnSubmit=false&processDefinitionKey=ProcessApplicationSample-1.0-EmployeeOnboardingProcess&form.profile={"firstName":"first name of user","userName":"name of the user"}&form.team=TeamName&form.project=Name of Project&form.manager=Name of Manager

Here is an example of how you can send data in Base64 encoded format using URL query parameters:

http://<IP address and port>/process/workspace/pages.html?root=startForm&reloadOnSubmit=false&processDefinitionKey=ProcessApplicationSample-1.0-EmployeeOnboardingProcess&form.profile=SI6IkFzaHdpbmkgRGhha2VkIiwi&form.team=VkaGFrYXIgUmF&form.project=U2FuIEZyYW5jaXNjbywgQ2&form.manager=EZyYW5jaXNjby

Note:

In case of a Process Automation instance paired with a Fusion based Oracle Cloud Application, user authentication is seamless. However for all other applications and services users would be prompted to authenticate before using the start form.

Base URL:

https://{OPA_service_instance}/process/workspace/pages.html?root=startForm&processDefinitionKey=#&reloadOnSubmit=#

URL Query Parameters

Parameter	Value Type	Description	Default Value	Required (in Query Parameter)
processDefinitionKey	string	The Process Definition Key parameter uniquely identifies a process belonging to an application. This key can be found in Process Interface definition which is available upon calling the Process Interfaces REST endpoint. https://{OPA_service_instance}/process/api/v1/process-interfaces See List Process Interfaces in REST API for Oracle Cloud Infrastructure Process Automation.	"	Yes
reloadOnSubmit	string	Reloads the form after Submit action is performed.	false	Optional
form.	string	Populates the start form with the value in this variable.	Not applicable	optional