Call profile

See also: Validate element and call profile

The Behaviour type Call profile transfers a Lobster_data profile with data from the form and/or processes data returned from that profile in the form.

The Behaviour type Call profile transfers a Lobster_data profile with data from the form and/or processes data returned from that profile in the form.

images/download/attachments/189432203/image-2024-10-1_12-8-21-version-1-modificationdate-1727777301201-api-v2.png

  • If an element is linked to the behaviour (see Behaviours for details), the data of the linked element is transferred to the profile.

  • To run the profile with full form data, the form element needs to be linked explicitly to the behaviour (default configuration).

  • If no element is linked, the data from the context of the triggering event are transferred to the profile. In case of an Execute behaviour action, the data of the executing behaviour is transferred to the profile.

Hint: From Lobster_data 4.6 onwards profiles can directly be edited or created (see also Create _data profile dialogue).

If no File name expression is specified, the 'behaviour name' is used as the file name. Otherwise, the text value determined here is applied. The input data corresponds to the data that would be sent to the profile even before the Data source expression was applied.

The data sent can be optionally determined via the Data source expression. If no value is configured, the data is sent directly to the profile.

Example:

Behaviour name

Input data

File name expression

Data source expression

Sent file name

Data sent

Upload
{
"name": "image.jpg", 
"content": "RGFzIGlzdCBrZWluIGVjaHRlcyBCaWxk...."
}

Upload
{
"name": "image.jpg", 
"content": "RGFzIGlzdCBrZWluIGVjaHRlcyBCaWxk...."
}

Upload
{
"name": "image.jpg", 
"content": "RGFzIGlzdCBrZWluIGVjaHRlcyBCaWxk...."
}
{name}
{content}

image.jpg
"RGFzIGlzdCBrZWluIGVjaHRlcyBCaWxk...."

Upload
{
"name": "image.jpg", 
"content": "RGFzIGlzdCBrZWluIGVjaHRlcyBCaWxk...."
}
{name}

Data is transferred to the profile in XML, text or JSON format, combined with variables (if any). Settings for Encorder and Decoder define the interpretation of data transferred to/returned from the profile.

Encoder/Decoder

Description

SERVER

The data element is sent to the server which generates an export XML and passes it on to the profile. This data type should preferably be used for Lobster Data Platform / Orchestration types. Corresponding template structures are featured in Lobster_data to facilitate mapping.

CLIENT

An XML is generated by the client from the data object (using browser functionality). This XML is not compliant with the export XML and also not type-safe.

►NOTE◄ This option is only available for compatibility reasons, but should no longer be used.

JSON

The data element is sent to the server, which generates text output in JSON format resembling the object and forwards it to the profile.

►NOTE◄ The JSON format can also be used like the SERVER data type if a field named clazz is created in the root node indicating the corresponding qualified class name.

TEXT

Transfers the data as plain text to the profile.

STATIC_TEXT

Transfers a defined static text to the profile.

CSV
(Decoder only)

Parses the text returned by the profile in CSV format (comma separated values). The first line defines the data fields of the separated values.

If the called profile returns data (see the dedicated section below), these could be evaluated by the actions of the behaviour, e.g. by executing a Populate element data action for a container.

Provide returned value as download

If the option As download is set, data returned by the profile is handled as a download in the browser.

For this purpose two variables can be defined in the profile, which are evaluated and set in the header of the download request:

Variable VAR_CONTENT_TYPE

  • The value of variable VAR_CONTENT_TYPE defines the content type directly. For example, the value application/octet-stream can be used to declare the download as an Excel file.

  • Without any specification, the default value application/XML is set, and then the browser attempts to interpret the file as XML.

The precise handling (download or direct opening in the browser) can be configured for the different content types in the browser.

Examples of valid content types:

Content type

File type

application/pdf

PDF file

application/rtf

Rich text file

text/plain

Text file

text/html

HTML file

application/octet-stream

File for download, e.g. for docx, xlsx, ...

Variable VAR_RESPONSE_FILENAME

  • If this variable is set, the content of the variable is used as the file name for the download.

  • If the variable VAR_CONTENT_TYPE is not set, the system tries to determine a content type from the file extension.

Assignments to variables in the profile

Information about the applicable login context (company, role, user) is automatically assigned to the MSG_CALL variables predefined in profiles – as is usual for profile calls from Lobster_pro. These are filled with values at runtime depending on the session's login data and, if necessary, automatically taking into account adjustments made by the Ausführen als event action:

Data object

Value

Variable name
(in Lobster_data)

Data type
(in Lobster_data)

Company of session

ID (id) of the company account

 
MSG_CALL_SCM_Company_id

BigInteger

Company account data object as XML (text)

 
MSG_CALL_SCM_Company_xml

String

Role of session

ID (id) of the role

 
MSG_CALL_SCM_Role_id

BigInteger

User of session

ID (id) of the user account

 
MSG_CALL_SCM_User_id

BigInteger

Username (username)

 
MSG_CALL_SCM_User_username

String

Data object of the user account as XML (text)

 
MSG_CALL_SCM_User_xml

String

Custom variables can also be added using the Variables button:

images/download/attachments/189432203/image2020-3-26_15-53-8-version-1-modificationdate-1727777060229-api-v2.png

  • Within the Lobster_data profile, the Value of a variable can be referred to by its Name.

  • Instead of a specific value, the placeholder $input can be used to assign the behaviour data to a variable.

  • Click the symbols images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/add.svg and images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/forbidden.svg to add or remove variables.

  • The Apply button saves the configuration of variables and closes the dialog.

Processing data returned from the profile

To enable a profile to return data to Lobster Data Platform / Orchestration, the profile must address the Custom class SCM:de.lobster.scm.dw.util.CronPassBackDataResponse for an output path.

  • If the profile does not return any data, the behaviour ‘Call profile’ also returns the return value ‘false’ and the Actions on 'true' are not executed.

  • If the profile returns data, this data is handed to the Actions on 'true'. A classic use case for this is executing action Populate element data.

Special return values

Boolean values (true/false)

  • If a profile returns the Boolean value true as static text, the Actions on 'true' are executed.

  • If a profile returns the Boolean value false as static text, the Actions on 'false' are executed.

Error response

The option Global error handling must be set so that errors occurring in a profile call can appear to the user in the graphical user interface.

To generate an error response directly from the profile, there are two basic options:

  1. Use the throw exception _data function in the mapping phase of the profile.

  2. Create an ErrorResponse structure as a return value of the data profile.

Lobster_data features a template structure for the output structure (in mapping): Lobster SCM / core:ErrorResponse}

  • The _data profile must specify XMLNoTemplateUnit as the Integration Unit (IU).

  • ‘SERVER’ must be selected as the Decoder in the configuration of the Call profile behaviour.

►IMPORTANT◄ Node ErrorResponse must be defined as the root node for generating the XML!

The following properties are featured in the ErrorResponse template structure:

Field name

Description

errorCode

Freely definable error code to identify the error; the default is ‘0’.

httpResponseStatus

An optional HTTP Response Status (200 for OK); the default is ‘0’.

locale

A key value can be optionally provided here for the Locale (e.g. en or en_US). The default language of the user is used as a default.

errorText

A plain text description for the error (e.g. 'Something went wrong!').

stackTrace

Detailed text, which should contribute to the technical clarification of the error; typically, the program’s call stack would be recorded here.

errorType

The type of error (e.g. ProcessException, Fatal Error, etc.).

requestLog

A log excerpt which is listed in the area ‘Request Log’ in case of a PROCESS_EXCEPTION; this can usually be left blank in this context.

errorLevel

The error level (number), indicates the severity of the error and also controls the way the error is presented to the user.

The following error levels are supported:

Level

Name

Description/Presentation

0

SEMANTIC_EXCEPTION

A common error, which is to be expected under certain circumstances, e.g. in case of incorrect operation by the user ► only the errorText is presented.

1

PROCESS_EXCEPTION

A fatal error, which usually occurs unexpectedly; all of the details listed above are included, to enable analysis (e.g. by an administrator).

2

NOTIFICATION_SUCCESS

Displays a notification marked ‘Success’, which presents the errorText only.

3

NOTIFICATION_WARNING

Displays a notification marked ‘Warning’, which presents the errorText only.

4

NOTIFICATION_ERROR

Displays a notification marked ‘Error’, which presents the errorText only.

5

NOTIFICATION_INFO

Displays a notification marked ‘Info’, which presents the errorText only.

6

SUPPRESS

Suppresses the error completely for the user; the error can only be traced by the brower's developer console.

►NOTE◄ The _data mapping function ‘Localization Task’ can be used to localize error messages according to the Localization.