iTWO 4.

0 - Workflow Designer

Verfasser: André Riebau

Lukas Ramm

Fatemeh Shirali

Datum: 06.09.2021

Version: 1.4

Version Datum Autor

1.0 30.08.2021 initial
1.1 31.08.2021 Fatemeh Shirali
1.2 31.08.2021 Lukas Ramm
1.3 01.09.2021 André Riebau
1.4 06.09.2021 Lukas Ramm
Content
Functional Documentation .............................................................................................................. 4
Workflow Template Column ....................................................................................................... 5
Versions of Workflow-Templates ................................................................................................ 6
Decisions.......................................................................................................................................... 7
Formula ....................................................................................................................................... 8
User Decision / User Decision Ex ................................................................................................. 9
Object Action ................................................................................................................................. 10
Change Status ............................................................................................................................ 11
Compress Files Action ............................................................................................................... 12
Compress String......................................................................................................................... 13
Decompress String..................................................................................................................... 13
Get Entity Action ....................................................................................................................... 14
Create Entity Action................................................................................................................... 14
Save Entity Action ...................................................................................................................... 15
Get Clerk from Company Action................................................................................................ 16
Get Clerk from Project Action ................................................................................................... 17
Clerk from Procurementstructure Action ................................................................................. 17
Get Project Document Action ................................................................................................... 18
Save Project Document Action .................................................................................................. 19
Get Text from Document Action ............................................................................................... 20
Text to MD5 Action ................................................................................................................... 20
Save Text To New File Action .................................................................................................... 21
Deserialize From Xml Action...................................................................................................... 21
Serialize From Xml Action .......................................................................................................... 22
Generate Save Link Action......................................................................................................... 22
Script Action .................................................................................................................................. 23
HTML Encoded Entities Action .................................................................................................. 24
Script Action .............................................................................................................................. 24
SQL Action ................................................................................................................................. 25
SQL Action (External) ................................................................................................................. 26
SQL To CSV Action ..................................................................................................................... 27
Throw an Exception / Throw a Validation Exception ................................................................ 27
User Task ....................................................................................................................................... 28
Document-ClientAction ............................................................................................................. 28
User Input .................................................................................................................................. 29

2
 Extended User Action ................................................................................................................ 31
External Function........................................................................................................................... 32
Get User by Clerk ....................................................................................................................... 32
Report Action............................................................................................................................. 33
Server WebAPI Post Action ....................................................................................................... 34
Server WebAPI Get/Delete/Patch/Put Action ........................................................................... 35
Soap Action................................................................................................................................ 36
Get Bidders by RFQ.................................................................................................................... 37
Get Documents by RFQ ID ......................................................................................................... 37
Send Message ................................................................................................................................ 38
Mail Action ................................................................................................................................ 39
Mail Report Action .................................................................................................................... 41
Workflow Action............................................................................................................................ 42
Go to Action............................................................................................................................... 42
Start Workflow .......................................................................................................................... 43
Start Workflow Async ................................................................................................................ 44
Start Workflow for every id ....................................................................................................... 45
Glossar ........................................................................................................................................... 46

3
Functional Documentation

Open iTWO4.0 and go to the second page. In “Administration” section click on Workflow Designer.

Use “Refresh” icon in iTWO menu bar to refresh the list of workflows.

Attention: Only 100 entries will be shown and the search on the left will only respond to these 100
entries! You can change hit count in the search menu and search over all items on right side of the
page.

4
Workflow Template Column

a) To create a new workflow:

click on “New Record” icon

b) To delete a workflow:

select the workflow

click on the “Delete Record” icon

c) To upload a workflow from your device:

click on “Import Version” icon

select the file from your device and click on “open”

1. In “Description”, type a name for the workflow. This name will be shown in right workflow column
for the users.

2. In “Comment”, you can type e.g., name of the company, to find the workflow easier

3. In “Kind”, choose kind of workflow through drop down menu (user workflow / system workflow)

In kind “user workflow”, the users can run the workflow from workflow column on the right.

In kind “system workflow”, the user cannot run the workflow manually. System workflow will be
activated e.g., by status change in customizing or by scheduler.

4. In “Entity”, select the entity, which is used for workflow. The workflow is visible only in this section.

5
Versions of Workflow-Templates

d) “Delete Record”: to delete a single version of the workflow

e) “Download Version”: to download a particular version

f) “Import Version”: to upload a version to an existing workflow

g) “Copy Version”: copy the selected version

h) “Change Status”: to change the status of a version e.g., to activate / deactivate it

5. Workflow-Status Column

If the light is on, the workflow is active

If the light is off, the workflow version was active and has been deactivated

If there is a pen, the workflow is in edit mode and can be changed

6. “Version”

the number of the different existing versions

7. “Comment”

optional description for this version

Attention: In Workflow Designer, changes are saved in the background by asynchronous Ajax requests.
From time to time, some changes may not be saved due to too fast change of templates or versions.
The same problem can occur when copying or creating a new version. Saving new versions can be done
manually using the Save button or when switching between actions in the current version. It makes
sense to save the current workflow version locally towards the end of the day.

6
Decisions

Decisions allow the selection of different paths that can be followed in the workflow. By checking a
condition, it is decided either automatically or through the active selection of a user, which is next step
in the workflow to proceed.

7
Formula

With the formula, a simple condition written in JavaScript can be used to check whether a certain value
is contained in a variable of the workflow context.

In the Designer, this is followed by the possible value. If this is true, the workflow continues at this
point. If several values are possible, further branches must be created in the Designer by clicking on
the Formula action and then inserting a new action (e.g. "Script Action").

The values to be checked for are configured per branch. Select a branch (black field in the designer)
and set a value as a parameter in each branch:

ATTENTION: Never remove a decision if the following workflow steps are still needed! Since the
designer is not able to combine all branches behind into one, ALL following steps will be deleted!
Depending on the number of following elements it makes sense to set the condition to "true" instead,
so that only the one path is used.

8
User Decision / User Decision Ex

For the design of the display options, the section: User Input is recommended.

The branches of the User Decision Dialog can be set with

OK -> true and

Cancel -> false

can be selected.

Please do not use -> User Decision Ex is currently not functional.

9
Object Action

The object actions offer some selections, which in most cases are specially tailored to the iTWO objects.
There are many functions that can be used generally as well as some very detailed functions that were
only developed for a specific individual case.

The following documentation on the object actions can therefore only describe the most common
ones.

10
Change Status

This action changes the status of an entity within the workflow, whereby most, but not all entities of
iTWO included. This function should always be used if “change status” must be recorded in the history
and is always preferable to a simple database update on the status field. The “change status” function
is only required if the status change for the selected object is not carried out manually by the user
anyway (see “change status” in the respective module).

Object Id: The id of the entity from the database whose status is to be changed must be entered here.

Status Name: The desired table and the corresponding status field whose status is to be changed must
be selected here.

New Status: To which new value will change the status?

Check Validate: The status matrix originally stated whether a change from a certain status to another
is allowed. If this check box is set, this condition is checked and the status change may not be carried
out on purpose, and an exception is written back to the context. If the “change status” is to take place
regardless of the status, the check box must be removed at this point.

New status: If the status should change, you can specify the variable in the context which the result is
in, i.e., the status, which the changeover made, will be saved.

11
Compress Files Action

For example, documents should send by e-mail or return a link to a package of documents later, this
action should combine several documents into a ZIP file.

FileList: A JSON array of Document ID's is required as input. All documents are represented in the
"BAS_FILEARCHIVEDOC" table by an index entry including a unique ID. The array contains a list with
the IDs of the corresponding documents from this table:

ArchiveName: containing file name where the ZIP should be stored

DocId: After the ZIP has been successfully created, the Document ID is saved in this variable, which can
later be used in the workflow, e.g., for sending e-mails or generating a link to the generated ZIP.

12
Compress String

With this function a very long string (text content) can be compressed and base64 encoded.

InputString: The text to be compressed and encoded.

CompressedString: The variable in which the fully compressed and encoded string is stored.

Decompress String

This action works in reverse to the "Compress String" action above and converts a previously
compressed string back to the original text.

CompressString: The compressed and encoded string from the previous Compress String action.

OutputString: The variable in which the decompressed original text is stored.

13
Get Entity Action

If you are searching for a specific entity, you must use "Get Entity Action".

In the "Action parameters" field, it is necessary to specify the ID; a context variable is usually used here.
In addition, the desired type of entity must be specified. Finally, the desired context variable is
specified for output.

Create Entity Action

If you want to create a new entity e.g., that no entity could previously be found for it, choose "Create
Entity Action".

To generate a new entity entry, the desired type must be selected with “Entity Name” and then the
context variable in which the new object is saved must be defined in output parameters.

It should be noted that the further adaptation of the new object in a subsequent e.g., "Script Action"
take place.

14
Save Entity Action

For example, documents are to be sent by e-mail or a link to a package of documents is to be returned
later, this action should be used to combine several documents into a ZIP file.

Please note that the context variable is entered for the attribute value and the correct type is selected
for "Entity Name".

It must be noted that the entity to be saved, also corresponds to the same object structure as the
selected entity.

15
Get Clerk from Company Action

In CompanyId enter the Id of the company / client and in ClerkRoleId enter the desired role of the
requested clerk.

You can find the CompanyId’s in the "BAS_COMPANY" table and the table ClerkRoleId’s in the
"BAS_CLERK_ROLE".

If the desired result does not appear, you can check under Quick Start -> Client -> Search in the view
"Administrators and Roles" which administrators are stored for the selected roles.

16
Get Clerk from Project Action

The “Get Clerk from Project” is needed, to search for certain clerk by project and role.

If you want to use the action statically, there is a standard text input with automatic completion. Here
the project number is required, and the needed role must be specified.

Switched to "Expert mode", the entry can also be used with context variables. Then “Project Id” is
needed instead of project number. (The "Project Id" is an autoincrement counter from database
usually bigger than 1000000).

Clerk from Procurementstructure Action

To select a clerk with a specific role from a certain procurement structure, this function can be used.

Using the selection in the input parameters or as a context variable (in Expert Mode) the corresponding
clerk to your search is returned.

17
Get Project Document Action

iTWO4.0 saves all documents in the database table "PRC_DOCUMENT". Since these documents are
needed, the "Get Project Document Action" was created.

To get the documents, you just need to enter one of the Id’s below.

Then the function searches for the

documents.

By specifying a context variable in Output

Parameter "Document List", a list of
documents is returned.

<- The view of the result list

18
Save Project Document Action

For this action, some parameters are not optional:

Required fields are:

Status

Document Category

Revision

Document Id

File Type

Project Document Type

Depending on the selected document

category, the Id field is required in each
case.

e.g., Project -> Project Id.

Unfortunately, no output is returned here if the file was created / linked correctly.

19
Get Text from Document Action

The “Document Reference” needs to be filled with the document Id and for “Text” field with the target
variable of the context.

The returned output text is the content of the file, but with whitespace characters and style tags.

Text to MD5 Action

With the "Text to MD5 Action" the MD5 hash value of a text / string can be generated.

This function can be used directly with a string, so it is possible to read out the text / content of a
document with "Get Text from Document" and get the hash value afterwards.

20
Save Text To New File Action

With this action any text can be written to a file. Therefore, specify the corresponding path, e.g., a
share / hard drive can also be used.

However, there is the advantage that there can be an answer, e.g., "Access to the path 'C: \\
von_iTWO40_eretzt.txt' is denied."

Deserialize From Xml Action

This function converts an XML text into a JSON object. This can be used as usual.

21
Serialize From Xml Action

This function converts a JSON object into an XML text. You can continue to work with this as XML.

Generate Save Link Action

With the help of the "Generate Save Link" action, you can generate company / person-specific
download links for the specified document. The document can also be packed into a zip with a
“Compress File Action”, so that several documents can be downloaded.

It is necessary to have the Document Id, a ModulString and at least one BusinessPartnerId or ContactId
or both. A context variable for the download link can be specified for the output parameters.

22
Script Action

The script actions offer important additions and basic functions for creating a workflow. The "Script
Action" and the "SQL Action" are mostly used to implement JavaScript logics as well as to extract
individual specific data from the iTWO4.0.

In the following documentation for the script actions, only the most common can be described.

23
HTML Encoded Entities Action

With the "HTML Encoded Entities Action" texts can be HTML encoded, which can be important for
dialogs and their presentation.

Script Action

The "Script Action" forms the heart of the workflow.

Best Practice:

It has turned out that a script action makes sense at the beginning to create the necessary variables
for the workflow. In this way, customer-specific values can be adjusted easily and centrally.

The configurations can also become very large very quickly, which is why it has become established to
define them at the beginning.

24
SQL Action

With the "SQL Action", database queries can be configured.

The special feature here is that there are three input options.

Option 1:

Query directly as a text

Option 2:

Query as a text with parameters / variables,

then it is marked with an "@"

Option 3:

Query completely or partially with context variables

25
SQL Action (External)

As an extension of the normal "SQL Action", the "SQL Action (External)" has an additional input
parameter to define a server and a database.

The input can be made in the same way as for the "SQL Action".

SQL Action First Object

The “SQL Action First Object” function, in contrast to the “SQL Action”, only returns the first hit.

When asked in the screenshot below, not all IDs in the system, but only the first one, would be output
and saved to the context variable.

Accordingly, the result is not stored in an array, but directly in an object, which also means that the
access to the data is different.

26
SQL To CSV Action

With the help of the "SQL To CSV Action" you can save the results of your query in a CSV file. To do
this, you must enter a separator in addition to the normal SQL query.

As a result of the function, you will receive a document ID (document), which you can download e.g.,
with the "Generate Save Link Action" (download link) or the "Document ClientAction" (display /
download).

Throw an Exception / Throw a Validation Exception

Both functions throw an exception and can be equipped with a message.

The difference between them is that the "Throw an Exception" throws an error of the "System.
Exception" class and "Throw a Validation Exception" one of the
"RIB.Visual.Basics.Core.Core.WorkflowValidationException" class.

Exception:

Validation Exception:

27
User Task

This rubric includes various dialogs for user interaction.

Document-ClientAction

This action expects a document ID. If the step is executed, either a new window opens showing the
file, or the file is downloaded directly from the browser.

Download / display of documents depends on the type of file, a TXT file was displayed in the browser
and a CSV file was downloaded directly.

28
User Input

The User Input dialog is built line by line and can be configured quite easily.

There are several elements for insertion:

The following are directly for inputs.

Design and links are more for designing and linking related data respectively.

If no context variable is specified for the input fields in the "Result", the line is not displayed.

29
The whole thing is configured in the "Parameter action" section.

With the checkbox "Show Description Ahead" the stored description is used in the dialog as described.

The elements are added, as already shown above, via the selection and can then be moved/arranged
up or down with the two buttons.

Edit (dark orange), works as usual for labels or titles, but also in the selection list, where the following
window/dialog opens.

Here it is now possible to distinguish between single and multiple selection.

As already known, new entries can be added/removed, as well as the position in the list can be
changed.
30
Extended User Action

With the help of the "Extended User Action" it is possible to completely set up a dialog according to
your own specifications. A prerequisite for this is sufficient knowledge of AngularJS and JavaScript.

HTML: The complete HTML source code of the dialog that is displayed to the user when the workflow
is executed, is stored in this editor field. It must contain all the required form fields for the tasks to be
carried out, which can be filled, marked, or shown or hidden as required.

There are two standard functions that can be used in HTML to close the dialog: the JavaScript functions
onOK () and onCancel (). Both functions submit the form and transfer the entered data to the context.
With onOK () the dialog will be closed, and the workflow goes to the next step, with onCancel () the
dialog remains active.

Script: To be able to mark or show / hide the above-mentioned fields, the functions required for this
must be implemented using JavaScript in the script area.

Context: The context variable is set here. This is necessary if form fields such as select boxes which are
filled with values for display.

Title: The dialogue header.

An output parameter does not have to be specified because the form fields are already written back
to the context via the AngularJS links.

31
External Function

In the case of the external functions, various functions have been grouped that are used for complex
applications in special modules.

Get User by Clerk

This action searches for registered user of the clerk, if a corresponding assignment exists in the system.

The input parameter is the UserId of the registered user from the context (Context.UserId). The
returned clerk, if available, is saved in the variable specified under "Clerk" in the context.

32
Report Action

The "Report Action" creates a file in the configured format from a predefined report template and
provides the ID for storage or download.

The export type is selected as the input parameter (among others, DOCX, PDF or HTML are possible).
Furthermore, the file name of the file to be generated without file extension, must be specified and
the report template must be selected.

After selecting the desired template, the parameters contained therein are displayed in the list below
and can either be filled with fixed values or placeholders from the context object.

The document Id of the generated file is delivered as output in the specified variable.

33
Server WebAPI Post Action

With the help of the "Server WebAPI Actions", general REST web services can be used.

With the "Server WebAPI Post Action”, the HTTP Post method is used to send a message to a web
service on a specific URL and to receive the response.

Url: Link address of the corresponding web service.

Content: The content (mostly in JSON format) that should be sent to the web service.

External API / own API: This selection indicates whether an external web service or the own API is used.

Header: If the external API was selected, additional header parameters (key / value) can be specified
here, e.g., for authentication.

The output variable contains the response from the web service after the request has been executed.

34
Server WebAPI Get/Delete/Patch/Put Action

The input parameters are identical to the "Server WebAPI Post Action", supplemented by two
additional input fields for authentication.

AccessToken: Contains the token that was made available as a response after logging in to the web
service if authentication is necessary for the service.

AccessTokenType: Contains the type of authentication, usually Basic or Bearer.

35
Soap Action

With this action, external SOAP services can be integrated into the workflow.

Url: This field contains the link to the SOAP web service.

Action: The action to be called by the SOAP web service can be specified here if this is required. Many
SOAP web services do not need this information if the request ("Content" field) already contains the
action to be performed.

Content: The field for the complete SOAP XML request.

Options: additional transfer values, if required for the SOAP service.

Answer: The response from the SOAP web service is written in the context variable.

Response Status: If this field has been assigned a context variable, the HTTP status code is also saved
in the context.

36
Get Bidders by RFQ

With the “Get Bidders by RFQ” action, the currently entered bidders for an RFQ Id is returned.

RfqId: Using the ID specified here, the bidders for the corresponding request are selected. The ID can
be used directly or by placeholder from the context.

CommunicationChannelId: Here a certain communication channel can be set, e.g., only bidders via the
communication channel e-mail.

Result: Variable to save the selected bidder contact information.

Get Documents by RFQ ID

This function gets the document IDs from the document container of the project.

However, it is better to use the "Get Project Document Action" directly.

37
Send Message

These two actions can send emails automatically with generated content and attachments within a
workflow.

38
Mail Action

Simple action to send e-mails with recipient, CC, and BCC as well as file attachments.

In the "From" field, either a fixed e-mail address is entered or an e-mail address from the context-
object is inserted by using a placeholder (e.g. {{Context.FromAddress}}).

In the subject field, either a fixed subject or placeholders can be used, whereby this can also be
combined, e.g. "Your invoice no. {{Context.InvoiceId}}". The same applies to the field for the e-mail
content.

The fields Recipient, CC, BCC, reply to and Attachments can also be filled in either fixed or with
placeholders in standard mode. If more than one value is to be entered in these fields, e.g., for several
recipients or different systems, a string must be transferred in expert mode separated by a semicolon:

Example for recipients: [email protected]; [email protected]; ...

Example for documents: 1001234; 1008563; ...

39
The check box next to “html” indicates that the e-mail content is sent in HTML format. With a hook in
“Save mail”, the generated e-mail is saved as a file in the document table, which can be written back
to the context variable of the workflow using the output parameter “Document Id”.

(There is currently no documentation for the check box "Use standard login information".)

40
Mail Report Action

This action is to be used in the same way as the "Mail Action" and only differs in the content of the e-
mail.

This content is generated from a report stored in the system. For this purpose, an existing report is
selected and the necessary transfer parameters are filled with either fixed values or placeholders from
the context object.

41
Workflow Action

Workflow actions offer the option to jump to other places within a workflow, e.g., to implement loops
with multi-part actions or to start another workflow from the currently running one.

Go to Action

With “Go to Action” you can jump to another named action within a workflow and continue processing
at this point. This can be helpful if, for example, you want to have the checking of an invoice approved
by several instances.

As a reference, a code is given in the “Go to Action”, which must be unique throughout the entire
workflow. Every action in the Workflow Designer contains such a "code" field (for example the right
picture). If this is set, the code specified there can then be selected in the “Go to Action” and the
workflow carries out the follow-up action referenced by the code after the “Go to Action”.

Since loops can be built by "Go To" actions, it should be mentioned at this point that the workflow can
terminate without changing the status if a maximum number of object actions is exceeded. If possible,
corresponding code should be written in JavaScript.

42
Start Workflow

This action calls another workflow, which process the “Start Context” and if necessary, returns the
result to the calling one.

It is possible, e.g., to create a workflow which can start several other workflows depending on a
decision.

As an input parameter, the action expects the Id the workflow should be started with (the ID of the
start entity). In addition, the complete context of the current workflow can be transferred if the new
created workflow requires further information.

The workflow that should be started must be selected in the “Workflow” field and after processing the
output parameters, the context of the called, finished workflow is returned for later evaluation of the
result.

This action is synchronous. The calling workflow waits until the called workflow will have ended, and
only then carries out the subsequent actions.

43
Start Workflow Async

The parameters of the “Start Workflow Async” action are filled in the same way as for the “Start
Workflow” action. In addition, the “CallingInstanceId” can be transferred, which is available as
“ParentInstanceId” when the workflow is called. In this way, within the called workflow, it can be
checked if or by which workflow it was started. (Important: Context.InstanceId is not available in debug
mode but it is available in the context object during normal processing.)

In contrast to "Start workflow", the called workflow is processed asynchronously. This means that the
calling workflow does not wait for the called one to be processed, but that executed independently of
it.

44
Start Workflow for every id

This action is used to start a workflow for each EntityId passed through the input array.

As an input parameter, a JavaScript array must be passed, that contains the EntityId’s of the
corresponding type with which the called workflow is to be started. The remaining input parameters
are identical to the "Start Workflow" action.

The specified workflow will be executed for all specified Ids one after the other. The original workflow
will be continued after the list of Ids is finished.

Attention: the workflow to be called up must be active, otherwise it can be selected as a template but
will not be saved.

45
Glossar

RFQ/ BANF Request for Quote

GP/ BP/ BPD/ NU Business Partner
BAS Clerk Clerk (Procurement Manager, Project Manager, …)

46