xAPPnow LOW CODE PLATFORM - User Manual 

Still no account yet?
×

Training Frontend Service - Process Connector

 
Related subfolder of the training project: "Automation/Service/Training/Exercise/ProcessConnector"
 
 

Chapter Overview

 
This low-code tutorial demonstrates the usage of a Process Connector element of xAPPnow Modeling Studio. The Process Connector provides three main functions for process model: start a process, notify a process and fetch running instances. This sample starts a "Demo" process model, then notify this same model and fetch the running instances and displays all ouput data on a final UIM.
 

Precondition

 
Before you can start working with a Process Connector the following preconditions have to be available
 
  • External System Configuration - configuration of the engine url
  • Connection Object - special kind of a definition object containing the connection configuration attributes to configure a connector
  • Business Process Model - the process model which will be started or notified through the process connector
  • Process Business Object - the base business object with the output data of the process that will be started
  • Returned Instance Business Object - the base business object with containing returned data of the instance running
  • Message Definition Object - the definition message object that will be used to start the process model
  • Error Object & Error Definition Object - special kind of business object and definition object to store the possible errors returned by the Process connector
  • Error Handler - submodels to handle business and fatal error of the Process connector
     
     
     
    1. External System Configuration
     
    As a first step you need to ask your system administrator of the xAPPnow User Portal to configure the url connection of the engine for the specific runtime environment.
     
    The screenshot below demonstrates the configuration for the external system "Tutorial - Process Connector" to connect with the engine with user "john" and with related password.
     
     
    Training Frontend Service - Process Connector
     
     
     
    2. Environment Object
     
    In a second step you have to add a base definition object of type "Connection" to a Definition Object Model of your project. The name of the connection object "ProcessTutorial" must be provided by the system administrator (see "External System Configuration" above).
     
     
Tutorial Model: Automation/Data Object/Tutorial/Service/ProcessConnector/DEF
 
The screenshot below demonstrates the "Connection" object "ProcessTutorial".
 
 
 
Training Frontend Service - Process Connector
 
 
REMARK:
 
The connection object does not contain the attribute names or values for security reasons. A developer must never know the access values to any external system. In addition, it is never possible to write any access values into a logfile or display them in a UI page etc.
 
 
3. Business Process Model
 
For this tutorial we used a business process model named "Demo" wich contains message events to check and learn about the configurations and the advantages of optionals fields of process connector related to messages.
 
Tutorial Model: Automation/Business Process/Tutorial/Service/ProcessConnector/Demo
 
 
 
4. Process Business Object
 
This process business object will contain the output data of the process model after it is started. This must be added from Base Objects palette of the Business Object Model. The following screenshot displays this output business object.
 
Tutorial Model: Automation/Data Object/Tutorial/Service/ProcessConnector/BOM
 
 
 
 
 
 
5. Returned Instance Business Object
 
This returned instance business object will contain the returned data of the instance ID of the process model after the function fetch running instances it's succesfully executed. This must be added from Base Objects palette of the Business Object Model. The following screenshot displays this output business object.
 
Tutorial Model: Automation/Data Object/Tutorial/Service/ProcessConnector/BOM
 
 
 
 
 
 
 
6. Message Definition Object
 
In case the business process that will be started or notified has message events, the Message IDs must be configured on the process connector. For this tutorial we will have on a definition model a Message Definition Object containing the registration object that will be used on the tutorial.
 
Tutorial Model: Automation/Data Object/Tutorial/Service/Registration/RegistrationDef
 
 
 
 
 
 
 
 
 
 
7. Error Object & Error Definition Object
 
Step number seven is very important to handle possible error (e.g. "authorization exception") that could occur during a Process connection function.
 
For each connector type (DB, Process etc.) you have to add a specific Error Definition Object and the related specific Error Object once within each project, as well as one single generic error BO "GenericError". The Error Object defined that holds the current error category, error code and error details as well as the boolean attribute isBusinessError (false = Fatal Error). The business object "GenericError" is a general error object to accept all kinds of error and is typically used to display an error in the UI page.

 
Tutorial Model: Automation/Data Object/Appollo/CommonBO
 
The screenshot below demonstrates the error object "ErrorProcess" which is required for a Process Connector
 
 

 
 
 
Tutorial Model: Automation/Data Object/Appollo/CommonDef
 
The screenshot below demonstrates the error definition object "ErrorProcess" which is required for a Process Connector and contains the multi-lingual error codes.
Additionally, the error definition "ErrorCategory" contains the multi-lingual connector names to be used in UI pages to display the multi-lingual error category.
 
 
 
 
 
 
 
8. Error Handling
 
Within this last precondition we will add a submodel for the fatal error handling to the project. The fatal error will be displayed in a multi-lingual UI Dialog "FatalError" plus the stack trace, which can be analysed by the developer or system administrator.
 
 
Tutorial Model: Automation/Service/Base/API/FatalErrorHandler
 
The screenshot below demonstrates the submodel "FatalErrorHandler"
 
 
Tutorial Model: Automation/User Interface/Base/UIPage/FatalError
 
The screenshot below demonstrates the design of UI dialog "FatalError" on the editor
 
 
 
 
 

Model Explanation

 
Tutorial Model: Automation/Service/Tutorial/ProcessConnector/ProcessConnector
 
  • The model is started with a UI page "Request Registration" to enter data for a registration
  • The button flow goes to a first Process connector "Start Process" to start business process "Demo" described on precondition 3
  • If the business process is succesfully started the sequence flow calls a second Process connector "Fetch Running Instances" which returns the ID of the created instance
  • If the instance is successfully fetch then a third Process connector "Notify Process" is called to notify same previous business process "Demo"
  • If all three process connector functions are succesfully deployed a UI page "View Result" is displayed with the output fields of the connectors
  • In case of an error occurs, the fatal flow of the Process Connector triggers the call element "Error Handler"
  • This error handler returns fatal error in a modal dialog and ends the function
     
 
 
 
Process Connector Configuration
 
In the following section the functions of the process connectors of the model above are described in detail
 
  • Function: Start Process
 
  • Function: select "Start Process" to create an instance of a given process
  • Process Definition: search and select the business process that will be started
  • Input Data: this is an optional field and it contains the object in case it must be sent from the client service model to the process that will be started
  • Output Process Object: the base process business object with output data of the started process
  • Message ID: this is an optional field in case the process starts with a message start event
  • Connection: the connection object mentioned on precondition 2
  • Error Object: the error object of the Process connector
     
    REMARK: In function "Start Process" is possible to navigate to process model from process connector after select the process difinition
     
    Training Frontend Service - Process Connector
     
     
     
  • Function: Fetch Running Instances
 
  • Function: select "Fetch Running Instances" to get the instances IDs of the running instances of a started process
  • Process Definition: search and select the business process which instances IDs will be get
  • Returned Instance IDs: the list of base business object with returned data of the running instances
  • Message Event: this is an optional field in case the process starts with a message event
  • Connection: the connection object mentioned in precondition 2
  • Error Object: the error object of the Process connector
     
    REMARK: In function "Fetch Running Instances" is possible to navigate to process model from process connector after select the process difinition
 
 
Training Frontend Service - Process Connector
 
 
 
  • Function: Notify Process
 
  • Function: select "Notify Process" notify a process already started and waiting for a notification
  • Process Instance ID: string attribute containing the ID value of the process instance that will be notified
  • Message ID: message definition object waiting for the notification
  • Connection: the connection object mentioned on precondition 2
  • Error Object: the error object of the Process connector
 
 
Training Frontend Service - Process Connector
 
 
 

Exercise - Process Connector

 
In this exercise you will learn to use the three functions of a Process connector.
 
 
 
Exercise 1: Create Model "ProcessConnector"
 
  • Step 1: Right click at model tree folder "Automation/Service/Training/Exercise/ProcessConnector" to open context menu "Create Model"
  • Step 2: Enter model name "ProcessConnector" and set option "Model Type: Dynamic Service" in dialog "Create Frontend Service Model"
  • Step 3: Click button "Search" to open dialog "Select Template" to select model "TMPL_ProcessConnector from folder ".../Template/ProcessConnector"
  • Step 4: Click button "OK" to create the model
 
 
 
 
 
 
 
Exercise 2: Complete the model "ProcessConnector"
 
  • Step 1: Drag&Drop a process connector from palette and enter label "Start"
  • Step 2: Draw button flow "Register" from ui page "Request Registration" to process connector element "Start"
  • Step 3: Drag&Drop a second process connector from palette next to the first and enter label "Fetch Running Instances"
  • Step 4: Drag&Drop a third process connector from palette next to the second and enter label "Notify"
  • Step 5: Draw a standard flow from process connector "Start" to process connector "Fetch Running Instances"
  • Step 6: Draw a standard flow from process connector "Fetch Running Instances" to process connector "Notify"
  • Step 7: Draw a standard flow from process connector "Notify" to ui page "Show Result"
  • Step 8: Draw a fatal flow from each process connector to call element "Error Handler"
 
 
Training Frontend Service - Process Connector
 
 
Exercise 3: Configure Process Connector
 
In this exercise you will configure each function type of the Process connector.
 
 
Function "Start Process"
  • Step 1: Select Process Connector "Start" and open TAB "Implementation", SubTAB "Configuration" to configure the Process Connector
  • Step 2: Select Function "Start Process" and select "Demo" process model in field Process Definition using button "Search", map Input Data with "registration", Output Process Object with "process", Message Object with "Message", Connection Object with "ProcessTutorial" , and Error Object with "errorProcess".
 
 
 
  • Step 3: Open SubTAB "Final Script" and enter the following script:
 
localData.instanceProcessStarted = true;
 
 
Function "Fetch Running Instances"
  • Step 4: Select Process Connector "Fetch Running Instances" and open TAB "Implementation", SubTAB "Configuration" to configure the Process Connector
  • Step 5:  Select Function "Fetch Running Instances" and select "Demo" process model using button "Search" map Returned Instance IDs with "returnedInstance", Connection with "ProcessTutorial" and Error Object with "errorProcess"
 
 
 
  • Step 6: Open SubTAB "Final Script" and enter the following script:
 
localData.processInstanceID = localData.process.processInstanceId
 
 
Function "Notify Process"
  • Step 7: Select Process Connector "Notify" and open TAB "Implementation", SubTAB "Configuration" to configure the Process Connector
  • Step 8: Select Function "Notify Process" and map Process Instance ID with "processInstanceID", Message Object with "Message", Connection with "ProcessTutorial" and Error Object with "errorProcess".
 
 
 
 
  • Step 9: Open SubTAB "Final Script" and enter the following script:
 
localData.instanceProcessNotified = true;
 
 
Exercise 4a: Publish the Model
 
  • Step 1: Click button "Publish" to open dialog "Publish Model"
  • Step 2: Enter username and password
  • Step 3: Click button "OK" to publish the frontend service model
  • Step 4: Open model "Automation/Business Process/Tutorial/Service/ProcessConnector/Demo" and repeat steps 1 to 3
     
 
Exercise 4b: Publish the Fatal Error Handler
 
  • Step 1: Open model "Automation/Service/Base/API/FatalErrorHandler" to publish the fatal error handler
 
 
Exercise 5: Test the Model in User Portal
 
  • Step 1: Login into User Portal and open menu "Frontend Services" to start function "ProcessConnector"
 
 
 
 
 
  • Step 2: In UI page "Request Registration" enter "Name" and "Last Name", "Birthday" and "Email" and click button "Register". This object will be sent to the process that will be started
 
 
 
Training Frontend Service - Process Connector
 
 
 
  • Step 2: Verify the output info for each function of the process connector
 
 
 
Training Frontend Service - Process Connector
 
 
 
 
1

Process Connector
Start Process

1. Process Connector Start Process
The first process connector starts a given process
2

Select "Start Process"

2. Select "Start Process"
Select function "Start Process" to create a new instance of the selected process
3

Search and Select Process

3. Search and Select Process
Click button "Search" to select the business process model that will be started
4

Specify Input Data

4. Specify Input Data
Drag&Drop a BO to send it to the process that will be started.
5

Specify Output Data

5. Specify Output Data
Drag&Drop a BO containing the output data of the created instance and its process
6

Specify Message ID

6. Specify Message ID
Drag&Drop the definition object message from SubTAB Definition Object. This must be the same Message ID that will be mapped on Start Event of the process that will be started
7

Specify Environment Object

7. Specify Environment Object
Drag&Drop the environment object of type connection to stablish the connection to the engine. This is common for all function types.
8

Specify Error Object

8. Specify Error Object
Drag&Drop the error object to handle errors during function execution. This is common for all function types.
 
1

Process Connector
Fetch Running Instances

1. Process Connector Fetch Running Instances
The second process connector returns a list of instance IDs of a given process
2

Select "Fetch Running Instances"

2. Select "Fetch Running Instances"
Select fucntion "Fetch Running Instances" to obtain the list of instance IDs of the selected process
3

Search and Select Process

3. Search and Select Process
Click button "Search" to select the business process model
4

Specify the BO list

4. Specify the BO list
This BO list will be returned with the IDs of the running instances
5

Select Message Event

5. Select Message Event
Click to set Message Event in case the process has message event
6

Specify Environment Object

6. Specify Environment Object
Drag&Drop the environment object of type connection to stablish the connection to the engine. This is common for all function types.
7

Specify Error Object

7. Specify Error Object
Drag&Drop the error object to handle errors during function execution. This is common for all function types.
 
1

Process Connector
Notify Process

1. Process Connector Notify Process
The third process connector notify a process instance
2

Select "Notify Process"

2. Select "Notify Process"
Select function "Notify Process" to notify a given process instance
3

Specify Instance ID

3. Specify Instance ID
Drag&Drop the attribute containing the ID value of the instance that will receive the notification
4

Specify Message ID

4. Specify Message ID
Drag&Drop the definition object message from SubTAB Definition Object. This must be the same Message ID that will be mapped on message event on the instance to be notified
5

Specify Connection Object

5. Specify Connection Object
Drag&Drop the environment object of type connection to stablish the connection to the engine. This is common for all function types.
6

Specify Error Object

6. Specify Error Object
Drag&Drop the error object to handle errors during function execution. This is common for all function types.
 
 
1

Drag&Drop
Process Connector

1. Drag&Drop Process Connector
Drag&Drop a process connector from palette and enter label "Start Process"
2

Draw Button
Flow

2. Draw Button Flow
Draw button flow "OK" from ui page "Request Registration" to process connector element "Start Process"
3

Drag&Drop
Process Connector

3. Drag&Drop Process Connector
Drag&Drop a second process connector from palette next to the first and enter label "Fetch Running Instances"
4

Drag&Drop
Process Connector

4. Drag&Drop Process Connector
Drag&Drop a third process connector from palette next to the second and enter label "Notify Process"
5

Draw Standard
Flow

5. Draw Standard Flow
  • Draw a standard flow from process connector "Start Process" to process connector "Fetch Running Instances". Draw a standard flow from process connector "Fetch Running Instances" to process connector "Notify Process". Draw a standard flow from process connector "Notify Process" to end event
6

Draw Fatal
Flow

6. Draw Fatal Flow
Draw a fatal flow from each process connector to call element "Error Handler"