Payload Mapping & Attribute Definition

For each Action you have to define which attributes are sent, received or used as key in the defined url.

Open

example attributes for Create outbound

Some attribute definitions seem to be empty in this example. This is OK. Inheritance feature is used here.

example attribute definition for SNOW

Open

It's important, that the attributes with definition of JSON Path “/table_sys_id” and “/table_name” come before the actual file-data.

External System

You can find the documentation on the External System level.

Action / Direction

You can find the documentation on the Action Definition level.

Attribute Name

Attribute name used to define a single data to be read or changed.

Use

Attributes are the central part of the Cross Connector product. Attributes are used to model the data structure of an external interface. An attribute can address a field of the payload send or received. It can be a http params. It can be a placeholder being part of the URI.

At the same time an attribute can hold a piece of data of a business transaction. It can be considered like a variable transferring data from a business transaction to an external tool or from an external tool to a business transaction.

Dependencies

For outbound actions, sending data from SAP Solution Manager to an external tool, the name of the attribute does not matter. You can choose a random name. You just have to ensure that the name in the attribute definition is equal to the name used in the field mapping.

For inbound actions the attribute name must be predefined as field in the CC4 odata service. If you chose an attribute name not existing, you could never receive a value from external. However, for constant values or http parameters you are again free to choose a random name.

Since we are sometimes reading and sometimes writing data, since we are sometimes creating and sometimes updating, we should use one and the same attribute for all actions and all directions. This is not a prerequisite but a recommendation.

The first letters IV, EV and KV do have a historical meaning. "IV" means import value on creation of a business transaction from external tool to SAP Solution Manager. The external tool is sending us the value and SAP Solution Manager is receiving (resp. importing) it. "EV" means export value on creation of a business transaction from external tool to SAP Solution Manager. We are sending back (resp. exporting) this value to the external tool. KV means key value. This attribute is being used as placeholder in an URI.

As you can imagine, an attribute being an import value in one action could be an export value in another action. An attribute can be used as exporting/importing value and as key value at the same time. Therefore the naming convention is not consistent in most cases especially if we follow the recommendation of reusing attributes for different actions and directions.

You just have to keep in mind: The attribute name is a variable name connecting the interface definition with the one order framework. That's all. That's the magic!

Example

Following attributes are pre-defined and pre-delivered. You can use them. You can redefine them. You can activate or deactivate them. You can add your own attributes if needed.

Key

Key attribute.

Use

This attribute is used as key attribute of the synchronization. A key attribute is a parameter of the endpoint URI used to call the API.

Dependencies

An attribute can be a key attribute and an inbound or outbound attribute at the same time. Usually POST calls does not have parameters and therefore no key attributes. On the other side PUT and GET calls always have parameters resp. key attributes.

Example

The External Ticket ID or GUID is always a key attribute on read or update calls.

Out

Outbound attribute.

Use

This attribute is used as outbound attribute of the synchronization. An outbound attribute is part of the body or http parameters. It is part of the request for outgoing calls and part of the response for incoming calls.

Dependencies

An attribute can be a key attribute and an inbound or outbound attribute at the same time. Usually POST and PUT calls to the external tool have a lot of outbound attributes. On the other side an outgoing GET call does have a lot of inbound attributes.

Example

Usually the business transaction ID, GUID, URL and the process type are attributes send from SAP Solution Manager to the external tool on creation and update. These attributes are therefore outbound attributes in these cases.

All data send to the external tool are outbound attributes. All data received from the external tool are inbound attributes. Regardless whether it is an outgoing or incoming call.

In

Inbound attribute.

Use

This attribute is used as inbound attribute of the synchronization. An inbound attribute is part of the body or http parameters. It is part of the response for outgoing calls and part of the request for incoming calls.

Dependencies

An attribute can be a key attribute and an inbound or outbound attribute at the same time. Usually POST and PUT calls to the external tool have a lot of outbound attributes. On the other side an outgoing GET call does have a lot of inbound attributes.

Example

Usually the business transaction ID, GUID, URL and the process type are attributes send from SAP Solution Manager to the external tool on creation and update. These attributes are therefore outbound attributes in these cases.

All data send to the external tool are outbound attributes. All data received from the external tool are inbound attributes. Regardless whether it is an outgoing or incoming call.

Mandatory

This attribute is mandatory.

Use

If for an outgoing action the request or the URI is not completely generated because a mandatory attribute could not be determined, the action is not executed.

If, for an incoming action, the request or URI is not completely transmitted because a mandatory attribute was not transmitted, the action is not executed.

Please set the flag if this attribute is mandatory for the proper execution of the action, both in terms of input, output and key. Please do not set it if the attribute is only optional.

Example

Usually, all key attributes (attributes in the URI) are mandatory. Usually the ticket IDs (internal and external) will also be mandatory attributes. Probably the transaction type is mandatory as well.

JPath

Path expression for modeling a payload.

Case 1: JSON Path expression for request or response payload.

Case 2: HTTP Header Parameter

Case 3: Parameter expression for URI (URI template RFC 6570)

Case 4: Search pattern for URI (Regular Expression)

Case 5: Alias for another attribute

Use

Case 1: If the attribute is used in the payload, a JSON path expression must be specified. In principle: simple attributes, structures, deep structures, arrays with index, arrays with filter conditions and constant values are supported.

Case 2: As HTTP Header Parameters only simple parameter names are currently supported here. The special character ~ is allowed, but not /{}[]@#=,

Case 3: As parameter expressions for URI key attributes, you can use whitespaces, simple names or paths of the form "/name/key". For the meaning and possibilities, refer to the information available on the Internet on URI Templates RFC 6570. Usually, the path expression is empty (whitespace) and the attribute will be used as URI placeholder.

Case 4: Search patterns are regular expressions with a left delimiter ^ and a submatch. They are used to extract a parameter value from a URI. This feature will be used in future for incoming actions. Currently this feature is not used.

Case 5: An alias is an alternative name for another attribute. Instead of storing the alias the path expression field, you can also make use the field dependency. Please use the field dependency and keep the path empty.

Dependencies

Please chose a path type corresponding to the path expression.

If the path expression is empty but a path is needed, we are reusing the attribute name as path for legacy reasons.

Example

Please take a look at the template profiles starting with # to get an impression of the possibilities.

Path Type

Path Type of a Path Expression.

Use

B Payload/Body Attribute Path (Content In/Out)

The path expression is a json payload path expression used for inbound or outbound communication.

H HTTP Header Parameter (Content In/Out)

The path expression is a name of a http field used for inbound or outbound communication

U URI Template Variable (Key Out)

The path expression is a parameter expression (URI template RFC 6570) used to build an endpoint URI used for an outbound communication.

R Regular Expression (Key In)

The path expression is a regular search expression used to extract a value from an endpoint URI used by an outbound communication. This feature is planned for future enhancements but not implemented/used so far.

A Alias (Alternative attribute name)

The path expression has to be empty and the dependent attribute field has to contain another attribute name. Alternatively, the path expression has to contain the other attribute name and the dependent attribute field has to be empty.

The attribute will be an alias for the other attribute. This means, that it will inherit the attribute definition of the other attribute. For inbound communication it will therefore receive the same value as the other attribute, which makes sense, if we want to store this data to two different places. For outbound it will set the value to the same target (json path or http field) as the other attribute, which makes only sense of only one of both can contain data or if both contain the same value.

Two famous aliases are IVPONUMBERSOLD or /SALM/EXTID.

V Virtual/Dummy/Helper (internal only)

The path expression has to be empty. The attribute is used to read and convert a value, but this value is not used for outbound communication directly. Instead, another attribute has to use this attribute as dependent attribute taking over its value. A virtual inbound attribute makes no sense, please use the alias concept here.

Dependencies

Please have a look at the documentation of the path expression.

You can keep the path type empty. In this case the path type will be calculated automatically based on the Key-In-Out flags and based on the legacy path expression prefix (e.g. body:, http-param: or ^). It is recommended to specify the path type explicitly without using the legacy prefixes to avoid miss-interpretation.

Value Type

Value type used to generate a proper JSON payload.

Use

A JSON payload is supporting only few data types. It is supporting structures/objects opening and closing with {}, arrays opening and closing with [] and strings opening and closing with "". Additional there are some special datatypes supported as well, like a number or true/false. No opening/closing letter is existing here.

If you choose "Autodetect", CC4 is always considering a regular attribute as string. If the value template or fallback value is maintained in the attribute definition, the data type will be detected by analyzing the value.

Since the auto detection might be wrong in some very special cases, you can force the right data type. It is recommended to choose "Autodetect" and to change to another value only if really needed.

Following value types are supported:

• Autodetect

• object Structure/Object {}

• array Array []

• string String ""

• float_str Floatingpointnumber

• int Number 0, 1, 2, 3, ...

• bool Boolean true/false

• null null

Dependencies

The value type is used/needed only for outbound JSON payload attributes. HTTP header fields or URI parameters are not using this concept. They are always strings. Same for inbound attributes, our REST API is currently providing only string attributes. Maybe this will change in future.

Example

The ISATTACHSET attributes are forced to arrays.

Fallback Value

Fallback value to be used as replacement for empty/initial external values on receive or send.

Use

You can specify an external fallback value here. It will replace the external value received from the external tool if no or just an initial value got received (Solman Inbound). It will replace any initial value just before sending it to the external tool (Solman Outbound). You can use this field as alternative to a value mapping of the initial/empty/whitespace value to something else. Proposal: If you already have a value mapping configured, you should use the value mapping feature for this initial mapping too. If there is no additional value mapping needed, you can use the fallback value feature.

You can also use this feature as constant value feature in case the payload attribute will never be received because of an invalid attribute path (Solman Inbound) or in case the business transaction value will never be read because of missing field mapping (Solman Outbound).

The external value could be an exact matching value like an assignee user id, transition id, a priority name or any other external value of an external ticket. Please perform a GET call in your web browser to read all values of a certain external ticket.

If the attribute is an array or a structure/object, you can also specify complex values like [], {} or much more complex payload snippets like {"info" : [ { "name": "company", "value" : "CrossALM" } ] } for instances here.

The external value could be an operation value alternatively. Following operation values are supported:

• #IGNORE# --> The field should be ignored. It should not be changed in external ticket (Solman Outbound) or business transaction (Solman Inbound).

• #DELETE# --> The field should be cleared/deleted/removed. It should be changed in external ticket (Solman Outbound) or business transaction (Solman Inbound).

• (whitespace) --> Fallback feature will be skipped.

Partial matching values (regular expressions or using of *, ?, +, % in between or at the beginning/end) are not supported here.

Dependencies

Please note that additionally a conversion routine can be used to perform a dynamic value mapping resp. conversion. Also a fallback value could be specified somewhere. In general, the value conversion is getting performed in following sequence. Therefore, the conversion result could be a mixture of multiple conversion rules.

Outbound / Int 2 Ext:

1. Read internal value from business transaction.

2. Convert value using conversion routine specified in field mapping.

3. Convert value using value mapping (Int to Ext).

4. Convert value using conversion routine specified in attribute definition.

5. Use fallback value defined in attribute definition if converted value is initial/empty and if fallback value is not empty.

6. Send external value to external tool as attribute of a payload, http parameters or as part of the URI.

Inbound / Ext 2 Int:

1. Receive external value from external tool as attribute of a payload, http parameters or as part of the URI.

2. Use fallback value defined in attribute definition if received value is initial/empty and if fallback value is not empty.

3. Convert value using conversion routine specified in attribute definition.

4. Convert value using value mapping (Ext to Int).

5. Convert value using conversion routine specified in field mapping.

6. Write internal value to business transaction or remove/delete a value from business transaction.

Example

Usually, attributes will be ignored if they are initial/empty. If an empty business partner will be received for example, it will not cleared/deleted/removed/changed in the business transaction. If an empty business partner will be read for example, it will not cleared/deleted/removed/changed in the external ticket.

This behavior was implemented for legacy reasons where only mandatory attributes got exchanged (mandatory means, that there is always a non-initial value) and where partial synchronizations got performed from time to time (partial means, that only some attributes got exchanged even if both sides are configured for much more attributes/fields).

To force a deletion/removal in this case, you can maintain the fallback value #DELETE#. To force a certain value, you can maintain it as fallback value here.

Prerequisites

Operations #IGNORE# and #DELETE# are supported since CC4 ABAP version 2.3.0.

Value Template / Pattern

Template or pattern for a value.

Use

This field or feature is used to build or decompose complex values. Values are usually transferred 1:1, apart from conversions. However, it can also happen that the value read from the business transaction needs to be supplemented before or after by another constant character string or even combined with another dynamic value. It may also be that the received value is very complex and only a substring is needed. This is what this feature is for.

Blank value:

Please leave the field blank if you do not need the feature.

Fixed value:

Maintain a constant string if you always want to assign this value to the attribute. Unlike the fallback value, the constant is used even if a real value has been received or read.

Template:

Maintain any character string including the placeholders #VALUE# and/or #DEPVALUE#. #VALUE# represents the original value of the attribute at runtime. #DEPVALUE# represents the value of the dependent attribute. Please note that when receiving from external, composition/extraction occurs immediately before conversion and when sending to external, composition/extraction occurs immediately after conversion.

Pattern:

Maintain any regular expression that can be used to extract a substring. The ABAP command FIND REGEX … IN … SUBMATCHES is used for this. The pattern must begin with ^ to be recognized as a pattern.

Example: ^[[:print:]]*-(\w*)$

Dependencies

Please note the dependencies with the dependent attribute and the conversion rules.

Example

• Preset with a constant value.

• Adopting the value of another attribute.

• Concatenate the values of two attributes (the own and the dependent).

• Placing strings before, in the middle or after.

• Building complex payload structures/arrays with a value in between.

• Extraction of a substring from a complex value.

Prerequisites

This feature is supported since CC4 ABAP version 2.4.0 (05/2024).

Conversion

You can find the documentation on the Field Mapping level.

Dependent Attribute

Attribute dependent on another attribute.

Use

Sometimes an attribute can only exist if another attribute is existing and has a proper value. If the dependent attribute is not existing or has an empty value, the current attribute will be ignored even if it has an own value.

Sometimes an attribute is just an alias of another attribute. That means, we want to extract the value from the payload in the same way as the other attribute is doing it. Usually the conversion / mapping and the location where we will store it (field mapping) is different.

Sometimes an attribute is just a virtual attribute and its value should be taken over to another attribute. Maybe it should be taken over without any change. Maybe we want to extract a section. Maybe we want to concatenate it with some other strings/values.

In all these cases mentioned above, we have to specify the dependent attribute here.

Dependencies

In most cases an attribute does not have a dependency. This field can be left empty then.

Example

Here are some examples:

• Constants for text attributes should exist only in case there is a none-empty text in JIRA Cloud V3 API.

• Attachment attributes transferring details like MIME type or filename should transfer these details only if there are some attachment data to be transferred in Jira Cloud V2/V3 API or ServiceNow API.

• IVPONUMBERSOLD should store the External Ticket ID (IVEXTID) in field SALES-PO_NUMBER_SOLD too.

• Same for /SALM/EXT_ID in case of Focused Build.

Disable / Inactive

You can find the documentation on the External System level.

Example attribute: IVPROJECT

Note that the attribute IVPROJECT is needed for Jira Cloud configurations to define a project on Jira side

1. name of the attribute

2. checkboxes for sending directions:

   1. key: the information saved in the attribute is needed for the url

   2. out: attribute is send from SolMan to external tool

   3. in: attribute is received from external tool

   4. mand: the attribute is mandatory

3. json path: represents the path in the payload send (those paths can differ for different ext. systems)

4. a static value can be defined, which should be send (can be anything you want)

5. a conversion routine can be sprcified, but it’s more common to specify conversions in the field mapping for all attributes independant from action in which that attribute is used