List structure templates

Get

/platform/api/profiles/preview/templates

Returns one page of the structure templates this instance bundles: the values of the template member of mappingSettings.sourceStructure and mappingSettings.targetStructure, which builds that tree the way the editor's "Load template" does. format and side narrow the list, search finds a template by the words of its name and tolerates typos, best match first; without search the list is ordered by name. meta.total counts the templates matching the filters. A page past the last one answers 200 with an empty data array. An IDoc basic type usually comes in several SAP releases (IDOC_IN_DELVRY03, V7IDOC_IN_DELVRY03, V75IDOC_IN_DELVRY03) whose segments differ; see the Profiles guide for choosing one.

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.

Query parameters

page

integer (int32)

Zero-based index of the page to return.

Minimum0

Default0

size

integer (int32)

Number of entries per page; a value out of range is rejected, not clamped.

Minimum1

Maximum200

Default20

format

array of string

The template format. Repeatable; repeated values OR.

Valid Item values[ "EDI", "TRADACOMS", "FIX", "IDOC", "X12", "CSV", "EXCEL", "XML", "BWA", "JSON", "CARGO" ]

side

string

Only templates that can be sent on this structure: SOURCE for sourceStructure.template, TARGET for targetStructure.template. Only IDoc templates belong to one side; every other template is listed for both.

Valid values[ "SOURCE", "TARGET" ]

string

Words to find in the template name or its format, case-insensitive; every word must match, as a whole word of the name, as part of it, or with one typo (two for a word of eight characters or more). The best matches come first.

ExampleDESADV D07A

Responses

200

Templates returned.

The SAP releases of one IDoc

?format=IDOC&side=SOURCE&search=DELVRY03: the envelope as returned, the page in data, the paging state in meta.

{
  "data": [
    {
      "name": "IDOC_IN_DELVRY03",
      "format": "IDOC",
      "side": "SOURCE"
    },
    {
      "name": "V75IDOC_IN_DELVRY03",
      "format": "IDOC",
      "side": "SOURCE"
    },
    {
      "name": "V7IDOC_IN_DELVRY03",
      "format": "IDOC",
      "side": "SOURCE"
    }
  ],
  "meta": {
    "page": 0,
    "size": 20,
    "total": 3
  }
}

Expand All

object

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

data

Array of object (core.StructureTemplate)

object

A structure template this instance bundles; send its name as the template of mappingSettings.sourceStructure or mappingSettings.targetStructure. Read-only.

class

string

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

Valid values[ "core.StructureTemplate" ]

format

string

The format; the format query parameter filters on it.

Valid values[ "EDI", "TRADACOMS", "FIX", "IDOC", "X12", "CSV", "EXCEL", "XML", "BWA", "JSON", "CARGO" ]

name

string

The value for template.

ExampleV7IDOC_IN_DELVRY03

side

string

Which structure the template can be sent on; the side query parameter filters on it.

Valid values[ "SOURCE", "TARGET", "BOTH" ]

meta

object (Meta)

Everything about the response that is not the resource itself. Members may be added over time; ignore the ones you do not recognize.

page

integer (int32)

Zero-based index of the returned page.

size

integer (int32)

Number of entries per page.

total

integer (int64)

Number of entries across all pages.

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?