xAPPnow LOW CODE PLATFORM - User Manual 

Still no account yet?
×

Training Backend Service Model - Word Connector

 

Tutorial Overview

 
This low-code tutorial demonstrates the usage of a Word Connector element of xAPPnow Modeling Studio. The Word Connector provides the posibility of generate a PDF given a word template using placeholders.
 
 

Precondition

 
Before you can start working with a Word Connector the following preconditions have to be available
 
  • External System Administration - configuration of the word connector connection data in AUP
  • Connection Object - corresponding definition object containing the connection configuration in AMS
  • Word template file- a word document that will be used in the sample. You can download it from TAB "Attachments" of the model: "Automation/Service/Tutorial/WordConnector/Server/ConvertWordToPDF"
  • Parameters Business Object - a business object containing the parameters that will replaced using the placeholders
  • Entity Relationship Model - contains the Word schema of the internal database created in the domain "tutorial" to save the generated pdf and then read it to download it into your PC
  • View Object - special kind of business object to configure a specific DB view of one or more entities and a specific attribute selection for each entitiy
  • Error Object & Error Definition Object - special kind of business object and definition object to store the possible errors returned by the Word connector
  • Error Handler - submodels to handle fatal error of the Word connector
     
    REMARK: For Word tutorial we will use the same internal DB that is used for DB tutorial using a different schema.
     
    1. External System Configuration
     
    As a first step you need to ask your system administrator of the xAPPnow User Portal to configure the external system access to use the word connector.
     
     
    2. Connection Object
     
    As a second requirement we will need a connection object to a Definition Object Model of your project. The names of the connection object "WordConnection" must be provided by the system administrator (see "External Configuration" above).
     
     
Tutorial Model: Automation/Data Object/Tutorial/WordConnector/DEF
 
The screenshot below demonstrates the connection object.
 
 
 
 
 
REMARK:
 
The connection object does not display 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. Word template file

 
To execute this tutorial you need a sample word template called "Tutorial - Word Connector.pdf". This word file contains placeholders that will be replaced with the values given as parameters.  A placeholder must have a particular format according to the attribute type:
 
  • string and date:                     @DV(n=<attributeName>)
  • bullet and number list:           @SET_LIST(name=<boName>) This should be a list of a business object
  • @DV(n=<attributeName>)
@END_LIST
  • table:                                       
@TABLE(name=<boName>, header=true) This should be a list of a business object
Column 1
Column 2
  @DV(n=<attributeName1>)
@DV(n=<attributeName2>)
@END_TABLE
 
  • paragraph:                                        @DV(n=paragraph)
  • image:                                   @SET_IMAGE(n=<attributeName1>, position=right)
 
 
The parameters business object must contain the attribute names which must have the identical names of the corresponding placeholders of the Word template.
 
 
Training Backend Service Model - Word Connector
 
4. Parameters Business Object
 
 
This business object will contain the attributes given as input parameters. This must be manually created in Business Object Model with the exact names defined on the Word template. The following screenshot displays this business object used in the tutorial.
 
Tutorial Model: Automation/Data Object/Tutorial/Service/BO
 
Training Backend Service Model - Word Connector
 
 
5. Entity Relationship Model
 
We need an Entity Relationship Model (ERM) with the Word schema of the database.
 
Tutorial Model: Automation/Data Object/Tutorial/WordConnector/ERM
 
The screenshot below demonstrates the ERM used for this tutorial. It contains one entity "OutputFile" and a file entity "pdfResult" and the related columns, types and corresponding Javascript attribute names.
 
Training Backend Service Model - Word Connector
 
6. View Object
 
Another requirement we need is a so called "View Object" (VO), which is a special kind of business object (BO) that allows to specify any DB view of an entity and optionally one or more of its associated entities. In addition the attributes of a VO can be selected individually according to the query requirements.
 
 
Tutorial Model: Automation/Data Object/Tutorial/WordConnector/BOM
 
The screenshot below demonstrates the view object "OutputVO" used in this tutorial. This VO was created from the ERM above by specifiying this ERM as submodel and selecting entity "OutputFile".
 
 
Training Backend Service Model - Word Connector
 
 
7. Error Object & Error Definition Object
 
Step number seven is very important to handle possible error (e.g. "authentication exception") that could occur during an Word call.
 
For each connector type (DB, REST, PDF 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/ErrorHandler/BOM
 
The screenshot below demonstrates the error object "ErrorFile" which is required for a Word Connector
 
 
 
Training Backend Service Model - Word Connector
 
 
 
Tutorial Model: Automation/Data Object/ErrorHandler/DEF
 
The screenshot below demonstrates the error definition object "ErrorFile" which is required for a Word 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/ErrorHandler/FatalErrorHandler
 
The screenshot below demonstrates the submodel "FatalErrorHandler"
Tutorial Model: Automation/User Interface/ErrorHandler/FatalError
 
The screenshot below demonstrates the design of UI dialog "FatalError" on the editor
 
 
 
 

Model Explanation

 
Tutorial Model: Automation/Service/Tutorial/WordConnector/Server/ConvertWordToPDF
 
  • The model is started with a Word connector "WordToPDF" to generate the PDF resulted document
  • The sequence flow of the Word connector goes to a DB Connector which insert the result into the internal DB
  • In case of an error occurs, the fatal flow of the Word Connector triggers a fatal error end event "Fatal Error". This end event indicates that the parent process model that calls this backend model will handle the exception to display the error in a user task to the user
     
     
     

Exercise - Word Connector PDF Generation

 
In this exercise you will learn how to use a Word connector with a Generate PDF from Template function.
 
 
 
Exercise 1: Create the Model "ConvertWordToPDF"
 
  • Step 1: Right click at model tree folder "Automation/Service/Training/Exercise" to open context menu "Create Model"
  • Step 2: Enter model name "ConvertWordToPDF" and select option "Model Type: Submodel" in dialog "Create Backend Service Model"
  • Step 3: Click button "Search" to open dialog "Select Template" to select model "TMPL_Word" from folder ".../Template/TMPL_Word"
  • Step 4: Click button "OK" to create the model
 
 
 

Training Backend Service Model - Word Connector

 
 
Exercise 2: Complete the model "ConvertWordToPDF"
 
  • Step 1: Right click at event "Start" to open context menu and select a word connector, enter label "WordToPDF"
 
 
Training Backend Service Model - Word Connector
 
 
  • Step 2: Draw a standard flow from Word connector "WordToPDF" to DB Connector element
 
 
Training Backend Service Model - Word Connector
 
  • Step 3: Draw a fatal flow from Word connector element to Error End Event element "Fatal Error"
 
 
Training Backend Service Model - Word Connector
 
 
Exercise 3: Configure Word Connector
 
Function "Generate PDF from Template"
  • Step 1: Select Word Connector and open TAB "Implementation", SubTAB "Configuration" to configure the Word Connector
  • Step 2: Select Function: "Generate PDF from Template", map on Input File: "inputFile.file", on Output File: "outputFileVO.pdfResult", on Connection Object : "WordConnection" and Parameters with "parameters"
 
 
 
Training Backend Service Model - Word Connector
 
 
  • Step 3: Select SubTAB "Fatal Script" and enter the following script:
 
localData.genericError = localData.errorWord as unknown as GenericError
 
 
 
Training Backend Service Model - Word Connector
 
 
 
Exercise 4: Set Service Backend Model as Submodel
 
  • Step 1: Open model "Automation/Business Process/Training/WordToPDF"
  • Step 2: Select script element "Convert Word to PDF" and open TAB "General", SubTAB "Element" to select Submodel
  • Step 3: Click button "Search" to open dialog "Select or Create Submodel" to select model "ConvertWordToPDF" from folder "Automation/Service/Training/Exercise/"
 
 
 
Training Backend Service Model - Word Connector
 
 
 
Exercise 5: Publish the Business Process Model and User Task models
 
  • Step 1: Click button "Publish" to open dialog "Publish Model"
  • Step 2: Enter username and password and set option "Start Process" and "Cascade"
  • Step 3: Click button "OK" to publish the business process model
 
 
 
 
 
 
Exercise 6: Test Model in User Portal (Standard Execution)
 
 
  • Step 1: Login into User Portal and open menu "MyTasks" to start task "Upload Input Word Template"
 
 
 
 
 
 
  • Step 2: Enter parameters data and select the word file template then click button "Next"
 
 
 
 
 
  • Step 3: Open menu "MyTasks" to start task "Download PDF" to check the values
 
 
 
 
 
1

Enter Model Name

1. Enter Model Name
Enter model name "ConvertWordToPDF" and select option "Model Type: Submodel" in dialog "Create Backend Service Model"
2

Select Template

2. Select Template
Click button "Search" to open dialog "Select Template" to select model "TMPL_Word" from folder ".../Template/TMPL_Word"
1

Drag and Drop Word Connector

1. Drag and Drop Word Connector
Right click at event "Start" to open context menu and select a word connector, enter label "WordToPDF"
1

Draw flow

1. Draw flow
Draw a standard flow from Word connector "WordToPDF" to DB Connector element
1

Draw Fatal Flow

1. Draw Fatal Flow
Draw a fatal flow from Word connector element to Error End Event element "Fatal Error"
1

Open Configuration

1. Open Configuration
Select Word Connector and open TAB "Implementation", SubTAB "Configuration" to configure the Word Connector
2

Configure Connector

2. Configure Connector
Select Function: "Generate PDF from Template", map on Input File: "inputFile.file", on Output File: "outputFileVO.pdfResult", on Connection Object : "WordConnection" and Parameters with "parameters"
1

Enter Fatal Script

1. Enter Fatal Script
Select SubTAB "Fatal Script" and enter the above script. This fills the generic error with word error to displayed on parent process model user task.
1

Select Script Element

1. Select Script Element
Select script element "Convert Word to PDF" and open TAB "General", SubTAB "Element" to select Submodel
2

Select Backend Submodel

2. Select Backend Submodel
Click button "Search" to open dialog "Select or Create Submodel" to select model "ConvertWordToPDF" from folder "Automation/Service/Training/Exercise/"