#Create or update a Business Object

Attention: When updating dependencies or tags, allways fetch the Business Object resource first to ensure operating on the latest version. Existing dependencies and tags have to be resent when doing an update - otherwise they would be cleared.

Dependencies are REQUIRED to be added when the BO functions access connectors or other BOs using Simplifier.Connector.* or Simplifier.BusinessObject.* APIs.

Project Assignment

Business Objects must be assigned to projects using the project assignment parameters:

For Creating New BOs:

• Set projectsBefore to empty array []

• Set projectsAfterChange to array of project names to assign the BO to

For Updating Existing BOs:

• Set projectsBefore to current project assignments (from existing BO)

• Set projectsAfterChange to new project assignments

Example:

#Create or update a Business Object Function

Creates or updates a JavaScript function within a server-side Business Object. Functions contain business logic code and can call connectors or other business objects.

Common Base Data Type IDs:

• String: "22ED1F787B6B0926AB0577860AF7543705341C053EB1B4A74E7CC199A0645E52"

• Integer: "B9B1191E0B70BA0845CF4F6A4F4C017594F8BA84FD2F1849966081D53A8C836D"

• Boolean: "2788FB5AA776C62635F156C820190D0FD3D558765201881A77382093F7248B39"

• Date: "06A9841478D7BE17C423F11C38CD6829E372093DBEC144F2A85FC7165BE8CD80"

• Float: "C09139C72F5A8A7E0036BA66CE301748BD617F463683EE03F92EDAAAA4AF8BC7"

• Any: "D31053204B4A612390A2D6ECDF623E979C14ADC070A7CB9B08B2099C3011BCAB"

Parameter Structure: Each parameter needs name, dataTypeId, and isOptional. Description and alias are optional.

Code: Standard JavaScript code.

Parameter access in the code: Input parameters can be accessed with let myVar = input.parameter_name; Output parameters can be assigned with output.parameter_name = someOfMyResults; Attention: In case an alias is defined for a parameter, you have use "alias" instead of "parameter_name". Example: output.alias = someOfMyResults; You can do an early return of output, but you don't need to end with a return. The function code will be postfixed with a "return output" anyway. If you do a return instead of return output, then in the first case you will return undefined output parameters - this is most probably not what you want to do.

Business Objects Development Guide

Overview

This guide provides comprehensive information for implementing Business Object functions in Simplifier, including Object API usage, connector access patterns, and Business Object to Business Object communication.

Server-Side Business Object API

The Simplifier object provides access to various server-side methods and components:

Available Components

• Logging: Server-side logging capabilities e.g. Simplifier.Log.info("my log") - see details: simplifier://documentation/server-businessobjects/api/Logging

• Utilities/Tools: Helper functions and tools - see details: simplifier://documentation/server-businessobjects/api/Utils

• Connectors: Access to data connectors - TODO add information later

• Business Objects: Access to other Business Objects - see this description

• Users: User management - see details: simplifier://documentation/server-businessobjects/api/User

Simplifier.Log.info(...) is logging to a Simplifier Log inside the database. The logged entries can be seen by the user but cannot be accessed by this MCP so far. console.log(...) is logging to the Simplifier logfile. The logged entries can be accessed by Simplifier Administrators only. The MCP cannot access these logs.

Accessing Other Business Objects

Basic Syntax

Examples

Configuration Requirements

Adding Dependencies

When accessing other Business Objects or connectors from a Business Object function, these components MUST be added as dependencies. (see schema for tool about getting, updating and creating Business Objects)

Dependency Types

• Business Objects: Other BOs that will be called

• Connectors: Data connectors that will be accessed

Dynamic Access Methods

Variables Approach

Dynamic Call Function

Parameter Validation

Security Considerations

• Always validate input parameters

• Validate data types and ranges for all inputs

Performance Tips

• Cache frequently accessed data when appropriate

• Avoid unnecessary nested Business Object calls

Debugging Tips

• To track down an issue (e.g. the connector issue) put the failing part into a very small bo function and return the result with JSON.stringify as a string, then you can check, whether the expected result is delivered. Indicate in the name of the function, that it can be deleted after debugging.

This documentation provides the essential patterns and best practices for implementing robust Business Object functions in Simplifier. Remember to always add dependencies and follow security best practices when accessing external components. Dependencies for yourself do not need to be added, but you can access own functions like Simplifier.CurrentBusinessObject.(payload?).

#Test a Business Object Function

Execute a business object function with provided input parameters for testing purposes. This allows you to test your functions with real data and see the results.

Common Base Data Type IDs:

• String: "22ED1F787B6B0926AB0577860AF7543705341C053EB1B4A74E7CC199A0645E52"

• Integer: "B9B1191E0B70BA0845CF4F6A4F4C017594F8BA84FD2F1849966081D53A8C836D"

• Boolean: "2788FB5AA776C62635F156C820190D0FD3D558765201881A77382093F7248B39"

• Date: "06A9841478D7BE17C423F11C38CD6829E372093DBEC144F2A85FC7165BE8CD80"

• Float: "C09139C72F5A8A7E0036BA66CE301748BD617F463683EE03F92EDAAAA4AF8BC7"

• Any: "D31053204B4A612390A2D6ECDF623E979C14ADC070A7CB9B08B2099C3011BCAB"

Parameter Usage:

• Use parameter "name" if no alias is defined

• Use parameter "alias" instead of name if alias is defined in the function

• Values must match the expected data type

Error Handling:

• Wrong BO/function name → 404 error

• Missing required parameters → 400 error

• Wrong parameter names → 400/500 error

• Invalid parameter values → 400/500 error

Delete an existing Business Object

Delete an existing Business Object Function

#Create or update custom data types

Custom datatypes can be either

• a struct type, which requires the definition of fields and their types (parameter "fields")

• a collection type, which requires a datatype for its elements (parameter "collectionDatatype")

• a domain type, which requires a parent type it is derived from (parameter "derivedFrom") These are mutually exclusive, so only specify exactly one of the three parameters.

In these parameters, referenced datatypes are specified by name. If it isn't a global datatype, the name must be prefixed with the namespace, separated with a slash.

Datatypes for connectors should be in the namespace "con/$name_of_connector", those for business objects in "bo/$name_of_bo".

#Delete a datatype Deletes the datatype with the given name. The name may be prefixed by the namespace, separated with a slash.

Create or update a Connector

This tool allows to

• create new connectors

• modify existing connectors

Attention: When updating a Connector, allways fetch the existing resource first to ensure operating on the latest version. Existing tags and endpoints have to be resent when doing an update - otherwise they would be cleared.

Connector Types

Common settings

For all connectors using SSL / TLS, the sslSettings option has two fields:

• trustType: An integer, with the following meaning:

  • 0: Always trust any certificate, regardless of CA signing

  • 1: Only trust the certificate specified explicitly

  • 2: Use system certificates for trust

  • 3: Combination of 1+2, trust explicitly specified certificate and any system trusted certificate.

• ignoreSSLCertificates: boolean, if set to true, any TLS validation will be skipped and the target will always be trusted, even when the certificate does not match the hostname.

When no SSL is required, or no specific settings apply, use the following sslSettings:

Connector type 'REST'

The object under endpointConfiguration / configuration defines properties, specific to REST Connector:

• endpointURL - the actual address of the remote REST endpoint

• sslSettings - SSL related options.

Complete Example:

Connector type 'SOAP'

The object under endpointConfiguration / configuration defines properties, specific to SOAP Connector:

• wsdlUrl - the address of a WSDL specification, which is used for the connector

• sslSettings - SSL related options.

Complete Example:

Connector type 'SAP RFC'

The object under endpointConfiguration / configuration defines the following properties specific to SAP RFC connectors, all of them are mandatory:

• sapSystem - ID of the target SAP system as a string.

• parallelExecutions - Boolean. If true, batch calls (i.e. multiple function modules are executed in one call) are executed in parallel.

• connectionPool - object with settings related to connection pooling:

  • peakLimit - number, maximum number of active connections at a time.

  • poolCapacity - number of pooled connections.

  • expirationTime - time in milliseconds for which connections are kept in the pool before being closed.

  • expirationCheckPeriod - time in milliseconds between checks for expired pooled connections.

  • maxGetClientTime - maximum time in milliseconds to wait for getting a connection (i.e. connection timeout).

Complete example:

Create or update a Connector call

This tool allows to

• create new connector calls

• modify existing connector calls

Attention: When updating a call, allways fetch the existing resource first to ensure operating on the latest version. Existing parameters have to be resent when doing an update - otherwise they would be cleared.

Connector Types

Connector type 'REST'

A REST Connector call defines a HTTP request to the configured endpoint address of the Connector.

Call parameters may define the following:

HTTP Method

Parameter name: verb

Type: String

Possible Values: GET, POST, PUT, PATCH, DELETE, HEAD, OPTION

The parameter is mandatory. If not specified differently, use constValue "GET".

Request body format

Parameter name: postFormat

Type: String

Possible Values: JSON, PLAIN, FORM, XML

Request Body

Parameter name: body

It can have an arbitrary data type. The data is converted and Content-Type header is set according to the parameter format.

Request Headers

Parameter name: headParams/<http-header-name>

Type: String

Example: To add a header "X-TEST", define a parameter with the name "headParams/X-TEST".

Path parameters

Parameter name: pathParams[<n>]

Type: Array[String] - that means it must always be given with array index, i.e. pathParams[0].

To form the URL of the call with complete path, all components of the array are joined by "/" and appended to the endpoint URL or the connector.

Defining a path is optional. If omitted, just the endpoint URL is called.

Examples: (assume endpoint URL is http://test-api.com)

• If pathParams[0] is "data", the address of the call is "http://test-api.com/data".

• If pathParams[0]="data" and pathParams[1]="customer", the address of the call is "http://test-api.com/data/customer".

URL parameters

Parameter name: queryParams/<query-param-name> (Type: String)

Example: To set the url parameter like in "http://test-api.com?level=4", define a parameter with the name "queryParams/level" and give it a value 4.

Output parameters

A REST Connector must have at least one output parameter

An empty parameter name, or "/" refers to the whole output object.

Use alias "data" for the whole output object.

Connector type 'SOAP'

A SOAP Connector call defines a SOAP operation to be invoked on the configured WSDL service endpoint of the Connector. You can retrieve the configured WSDL for a connector using the resource simplifier://connector/{connectorName}/wsdl

Call parameters may define the following:

Binding Name

Parameter name: bindingName

Type: String

The binding name identifies the specific service binding to use from the WSDL specification.

The parameter is mandatory.

Operation Name

Parameter name: operationName

Type: String

The operation name specifies which SOAP operation to invoke from the binding.

The parameter is mandatory.

Operation parameters

Parameter name: soap/<operationName>/<parameterName>

Type: depends on operation

Example: soap/_-ITIZ_-BUS2038_CREATE/index

Operation parameters contains the SOAP request parameters according to the operation's input schema defined in the WSDL.

URL parameters

Parameter name: queryParams/<query-param-name>

Type: String

Optional parameters can be added as query parameters appended to the SOAP request URL.

Example: To set a URL parameter like in "http://soap-service.com?version=1.0", define a parameter with the name "queryParams/version" and give it a value "1.0".

Output parameters

Parameter name: soap/<response-message-name>/<element>

An empty parameter name, or "/" refers to the whole output object.

Use alias "data" for the whole output object.

The output typically contains the SOAP response parsed according to the operation's output schema defined in the WSDL.

For example, given the following WSDL operation:

With the corresponding message and element definitions:

the resulting object for the / output parameter would look like this:

To get the relevant field only, the output parameter name would be /soap/InputOutputResponse/InputOutput

Connector type 'SAPRFC'

An SAP RFC connector call executes a function on the SAP system defined in the endpoint.

As RFC calls only work with existing functions in the SAP system, use the connector wizard to create them by first searching for available calls using the resource simplifier://connector-wizard/{connectorName}/search/{term}/{page}. After selecting the appropriate calls, use the tool connector-wizard-rfc-create to generate the calls.

RFC connector calls should define the following parameters with constant values:

SOAP compatibility mode

Parameter name: configuration/output/soapCompatibility

Type: Boolean

This parameter should be set to false, unless the user specified otherwise.

Use default values in output

Parameter name: configuration/output/useDefaultValues

Type: boolean

This parameter should be set to true, unless the user specified otherwise.

Autocommit

Parameter name: configuration/autocommit

This parameter should be set to true, unless the user specified otherwise.

Additional return information

Parameter name: configuration/operation/additionalReturnInformation

Type: Array of strings

Possible values: IMPORT, CHANGING, TABLE, EXPORT, EXCEPTION

Unless specified otherwise by the user, this should be set to ["IMPORT", "EXPORT", "CHANGING", "TABLE", "EXCEPTION"].

Output parameters

An RFC connector's output parameters depend on the called SAP system function. You should usually let the wizard create them, as it has all the metadata available.

Create one or more calls for an RFC connector using the wizard

The RFC connector requires calls to refer to existing functions on the remote SAP system. To find available functions, use the resource template simplifier://connector-wizard/{connectorName}/search/{term}/{page}. Select the desired function names and pass them to this tool.

#Test a Connector Call

Execute a connector call with provided input parameters for testing purposes. This allows you to test connector calls with real data and see the results.

Parameter Usage:

• Each parameter requires a "name" (the field name) and a "value" (the actual data)

• Parameter names must match the connector call's defined parameters

• Values can be any JSON value (string, number, boolean, object, array). The connector call specifies the expected input data type. Important: In case you miss properties in the result, check whether a datatype other than Any is assigned as output data type and whether validateOut is set to true - in this case values will be filtered to fit the datatype.

Delete a Connector call

Delete a Connector

Create or update a Login Method

Create or update login methods for authenticating connectors with external systems.

Supported Types:

• UserCredentials (BasicAuth): Username/password authentication

• OAuth2: OAuth2 client-based authentication

• Token: Token-based authentication (API keys, SimplifierToken)

• SAPSSO: SAP-Single Sign on via Logon Ticket

Note that the type of a login method cannot be changed later. If you need to change the type, create a new login method instead.

UserCredentials (BasicAuth)

Creates or updates a basic authentication login method with various source types.

UserCredentials with Provided Source (Default)

Stores username and password directly in the login method.

Configuration:

• loginMethodType: "UserCredentials"

• sourceType: "Provided" (source ID: 1) - default

• Target: Default (target ID: 0) - standard authentication header

Example - Creating BasicAuth:

Example - Updating BasicAuth password:

UserCredentials with Profile Reference

References a key in the user's profile.

Example:

UserCredentials with User Attribute Reference

References a user attribute by name and category.

Example:

OAuth2 Login Methods

Creates or updates OAuth2-based login methods with various source configurations.

IMPORTANT: When creating an OAuth2 login method with a client reference, the oauth2ClientName MUST match one of the existing OAuth2 clients configured in Simplifier. You can discover available clients using the simplifier://oauthclients resource before creating the login method.

OAuth2 with Client Reference

Uses a configured OAuth2 client from Simplifier. Discover available clients: Use simplifier://oauthclients resource

Configuration:

• loginMethodType: "OAuth2"

• sourceType: "ClientReference"

• Target: 0 = default header, 1 = custom header, 2 = query parameter

Example - Default header:

Example - Custom header:

Example - Query parameter:

OAuth2 with Profile Reference

References a key in the user's profile.

Example:

OAuth2 with User Attribute Reference

References a user attribute by name and category.

Example:

Token Login Methods

Creates or updates Token-based login methods for API authentication, including SimplifierToken support. Can be used for API-KEYs or for tokens, that you have received with former Simplifier Auth Clients and stored in the UserProfile or in the UserAttributes. In case you have received a token from a former connector call, you might want to add the token with every call in a header via a connector call input parameter.

Token with Default Source

Uses an empty configuration (no credentials stored). Typically used as a placeholder.

Configuration:

• loginMethodType: "Token"

• sourceType: "Default" (source ID: 0)

• Target: 0 = default header, 1 = custom header

Example:

Token with SystemReference Source

Uses the SimplifierToken for authentication. This is the primary use case for authenticating Simplifier apps accessing the REST API.

Configuration:

• loginMethodType: "Token"

• sourceType: "SystemReference" (source ID: 3)

• Target: 0 = default header, 1 = custom header

Example:

Token with Provided Source

Stores a token value directly in the login method. Useful for API keys.

Configuration:

• loginMethodType: "Token"

• sourceType: "Provided" (source ID: 1)

• Target: 0 = default header, 1 = custom header

Example - Creating Token:

Example - Updating Token value:

Example - Updating description only (without changing token):

Token with Custom Header

Place the token in a custom HTTP header.

Example:

Token with Profile Reference

References a token stored in the user's profile.

Example:

Token with User Attribute Reference

References a token from a user attribute.

Example:

SAP-SSO Login Methods

Creates or updates SAP-SSO login methods for API authentication. Can be used for users authenticated against a SAP authentication method or with a constant value or one stored in the UserProfile or in the UserAttributes.

SAP-SSO with Default Source

Uses an empty configuration (no credentials stored). Uses the SAP Logon Ticket from the user, which needs to be logged in using SAP-SSO.

Configuration:

• loginMethodType: "SAPSSO"

• sourceType: "Default" (source ID: 0)

• Target: 0 = default

Example:

SAP-SSO with Provided Source

Stores a logon ticket value directly in the login method. Useful for API keys.

Configuration:

• loginMethodType: "SAPSSO"

• sourceType: "Provided" (source ID: 1)

• Target: 0 = default header, 1 = custom header

Example - Creating SAP-SSO:

Example - Updating ticket value:

Example - Updating description only (without changing ticket):

SAP-SSO with Profile Reference

References a ticket stored in the user's profile.

Example:

SAP-SSO with User Attribute Reference

References a ticket from a user attribute.

Example:

Get recent log entries from Simplifier

This tool provides access to the Simplifier logging system. You can filter logs by level and time range. If no filters are used, it returns the 50 most recent log entries. If you are expecting to find some logs but they are missing, ask the user to check whether logging for execution is set to the right level in the Simplifier server settings.

Log Levels:

• 0 = Debug

• 1 = Info

• 2 = Warning

• 3 = Error

• 4 = Critical

Parameters:

• pageSize: number of log entries to return in one request, defaults to 50.

• page: if more than "pageSize" entries are available, this can be used for accessing later pages. Starts at 0, defaults to 0.

• logLevel: Filter by minimum log level (0-4)

• since: ISO timestamp for entries since this time

• from/until: ISO timestamps for a time range (must be used together)

Examples:

• Default: Get 50 most recent entries

• logLevel=3: Only errors and critical

• since="2025-01-01T00:00:00Z": Entries since date

#Create or update a SAP system

SAP Systems are used as the target of RFC connectors.

Attention: When updating tags, allways fetch the SAP system resource first to ensure operating on the latest version. Existing tags have to be resent when doing an update - otherwise they would be cleared.

You can find existing SAP systems with the simplifier://sap-systems resource, and details about a single system with simplifier://sap-system/{systemName}

Project Assignment

SAP systems must be assigned to projects using the project assignment parameters:

For Creating New SAP Systems:

• Set projectsBefore to empty array []

• Set projectsAfterChange to array of project names to assign the SAP system to

For Updating Existing SAP Systems:

• Set projectsBefore to current project assignments (from existing SAP system)

• Set projectsAfterChange to new project assignments

Example:

Delete an existing SAP system