Get mapping function by id

Get

/platform/api/functions/preview/{id}

Returns a single mapping function by its id.

Security

OAuth

OAuth2 client-credentials flow for machine-to-machine access. Exchange a client id/secret at /dw/register/oauth/token for a bearer token, then send it as Authorization: Bearer <access_token>. Client credentials are provisioned in the Lobster administration UI.

This is the client-credentials token endpoint of the Platform API. /oauth/token, the token_endpoint advertised at /.well-known/oauth-authorization-server, serves the authorization code flow of the OAuth2AuthorizationCode scheme.

FlowClient Credentials

Token URL/dw/register/oauth/token

Refresh URL/dw/register/oauth/token

OAuth

OAuth 2.1 authorization code flow with PKCE, for acting as a signed-in user. It works with Microsoft and other single sign-on providers: the provider only confirms the user's identity to the platform, which then issues its own token.

POST /oauth/register (no authentication) with the JSON body {"redirect_uris": ["<redirect URI>"]} returns a client_id. The user's browser has to reach the redirect URI.
Open /oauth/authorize in the user's browser with response_type=code, client_id, redirect_uri, state and a code_challenge with code_challenge_method=S256. state is a fresh unguessable value per request, and code_challenge is the S256 hash of a code_verifier freshly generated per request from a cryptographically secure random source (43 to 128 characters, RFC 7636). The user signs in on the platform's login page, and the browser is redirected to the redirect URI with code and state; a callback whose state differs from the one sent is to be rejected.
The code is valid for 30 seconds. Exchange it at POST /oauth/token, form-encoded, with grant_type=authorization_code, code, redirect_uri, code_verifier and client_id.
The answer carries access_token (valid 30 minutes), refresh_token (valid 48 hours) and expires_in in milliseconds. Refresh with grant_type=refresh_token, refresh_token and client_id.

FlowAuthorization Code

Authorization URL/oauth/authorize

Token URL/oauth/token

Refresh URL/oauth/token

HTTP

Type bearer

Bearer token obtained from an authenticated browser or guest-user session.

Flow 1 — UI login: Log in via the Lobster web UI at /, then call GET /auth/sessionBearerToken to exchange the session cookie for a bearer token.

Flow 2 — Guest user login token: Append a GuestUser loginToken as a URL query parameter to the base URL to establish a password-free session:

GET <host>?loginToken=<GuestUser token>

Then call GET /auth/sessionBearerToken to obtain the bearer token.

Path parameters

integer (int32) Required

Function id.

Responses

200

Function returned.

Expand All

object

Standard Platform API success envelope. Every response carries exactly one of data (success) or error (failure) at top level.

data

object (core.MappingFunction)

A mapping function of this instance, called by id from a core.FunctionConfiguration in the functions chain of a target field or node. Read-only; includes the instance's custom functions.

class

string

The type of this object, always core.MappingFunction. Required where the member it is sent in accepts several types.

Valid values[ "core.MappingFunction" ]

deprecated

boolean

Whether the function is deprecated: it still runs, but a new profile should not use it.

description

string

What the function does and returns.

ExampleReturns last date of month from given date or timestamp 'a'

group

string

The group the function belongs to; the group query parameter filters on it.

ExampleDate functions

integer (int32)

The function id a core.FunctionConfiguration refers to. Ids from 5000 up are the instance's custom functions and differ between instances.

Example72

name

string

The name, with the parameters as letters; a parameter in brackets ([b]) may be empty but must still be sent.

Examplelast date of month(a)

parameters

Array of object (core.MappingFunctionParameter)

The parameters in order (a, b, ...), the order of the functionParameters of a core.FunctionConfiguration, which carries one entry for each, an unused one as an empty VALUE.

object

One parameter of a mapping function. Its position in the function's parameters is its position in the functionParameters of a core.FunctionConfiguration.

class

string

The type of this object, always core.MappingFunctionParameter. Required where the member it is sent in accepts several types.

Valid values[ "core.MappingFunctionParameter" ]

description

string

What the parameter means. Absent where the function does not describe it.

Exampledate or timestamp

helper

string

What kind of value the parameter refers to; absent for a plain value. E.g. CHANNEL_SELECTION takes a channel id, PARTNER_SELECTION a partner id, PROFILE_SELECTION a profile name, CERTIFICATE_SELECTION a certificate id, DB_ALIAS_SELECTOR a database alias, REGEX_EDITOR a regular expression, DATETEMPLATE_HELPER a Java date pattern, CHARSET_SELECTION an encoding name.

ExampleCHANNEL_SELECTION

mandatory

boolean

Whether the parameter needs a value. A parameter that is not mandatory may be empty, but must still be sent as an entry of functionParameters.

name

string

The parameter's letter, as the function's name refers to it: a for the first, b for the second, and so on.

Examplea

possibleValues

Array of string

The fixed values this parameter accepts, e.g. ["hex", "base64", "raw"], passed as a VALUE. Absent when the parameter has no fixed set.

string

secret

boolean

Whether the parameter carries a credential. A VALUE in such a position is returned encrypted; send it as PLAIN:<text>, or send the encrypted value back unchanged.

type

string

The type the function expects. Absent when it accepts any type. A VALUE parameter carries numbers and booleans as text.

Valid values[ "STRING", "INTEGER", "DOUBLE", "DATE", "BOOLEAN", "FLOAT", "BIG_DECIMAL", "BIG_INTEGER", "TIMESTAMP", "BLOB" ]

resultType

string

The type of the value the function returns. Absent when it returns any type, or none.

Valid values[ "STRING", "INTEGER", "DOUBLE", "DATE", "BOOLEAN", "FLOAT", "BIG_DECIMAL", "BIG_INTEGER", "TIMESTAMP", "BLOB" ]

400

The request could not be understood. BAD_REQUEST for a body that does not decode — its message names the property at fault — and VALIDATION_FAILED with one details entry per offending parameter for a malformed request target (an unknown query parameter or sort key). Also BAD_REQUEST for a response unit naming a channel this client cannot reference.

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}

Expand All

object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error

object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code

string

Stable machine-readable UPPER_SNAKE error code for programmatic handling, e.g. PARTNER_NOT_FOUND, VALIDATION_FAILED or FORBIDDEN. New codes may be added over time; treat an unknown code according to the HTTP status class. The HTTP status itself is carried by the status line only, never duplicated here.

message

string

Human-readable, non-localized explanation. Branch on code, never on this text.

details

Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code

string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message

string

Human-readable, non-localized explanation of this individual failure.

target

string

What this failure refers to, e.g. the violated field.

401

Authentication is required or the supplied credentials are invalid.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource."
  }
}

Expand All

object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error

object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code

string

message

string

Human-readable, non-localized explanation. Branch on code, never on this text.

details

Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code

string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message

string

Human-readable, non-localized explanation of this individual failure.

target

string

What this failure refers to, e.g. the violated field.

403

The caller lacks the permission for this operation on this resource (FORBIDDEN).

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Access to this resource is denied."
  }
}

Expand All

object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error

object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code

string

message

string

Human-readable, non-localized explanation. Branch on code, never on this text.

details

Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code

string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message

string

Human-readable, non-localized explanation of this individual failure.

target

string

What this failure refers to, e.g. the violated field.

404

The requested resource does not exist. The code is resource-specific, e.g. PARTNER_NOT_FOUND, PROFILE_NOT_FOUND or CHANNEL_NOT_FOUND.

{
  "error": {
    "code": "PARTNER_NOT_FOUND",
    "message": "Partner not found: 42"
  }
}

Expand All

object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error

object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code

string

message

string

Human-readable, non-localized explanation. Branch on code, never on this text.

details

Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code

string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message

string

Human-readable, non-localized explanation of this individual failure.

target

string

What this failure refers to, e.g. the violated field.

500

An unexpected server error occurred.

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred."
  }
}

Expand All

object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error

object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code

string

message

string

Human-readable, non-localized explanation. Branch on code, never on this text.

details

Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code

string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message

string

Human-readable, non-localized explanation of this individual failure.

target

string

What this failure refers to, e.g. the violated field.

Was this article helpful?