Functions

This section describes the main functionalities in the VSS Communication Framework:

• Notification Triggers

• Task Processing

• Dynamic Parameters

Imagine the following user stories:

Open

You can achieve the above user stories with the communication framework. The framework is very flexible to design your communication structure according to your business needs.

Notification Triggers

A transaction to define condition of the notification to be triggered. Notifications can be triggered from various VSS applications by mapping it to the Communication Event ID.

• Transaction code: /DBE/CF_NOTIF_TRG, or:

• On the SAP Easy Access screen, choose “Logistics > Logistics Execution > Vehicle Sales and Service > Communication Framework > Process Definition > Notification Triggers”.

Open

Prerequisites

The following is required before setting up the notification trigger:

1. Sender type is configured in customizing.

2. Recipient type is configured in customizing.

3. Notification channel is configured in customizing.

4. Communication event ID is configured in customizing.

5. Notification ID is configured in customizing.

6. Notification template is assigned to notification ID in customizing.

Functionalities

In this transaction, you can set up the following:

1. Trigger detail: In this step, you assign the communication event ID that will trigger the notification. You also define the business object type and source object type. Maintain the communication group if you want to restrict the notification for specific organization or sales area.

2. Define pre-checks: Pre-checks is used to define mandatory steps or pre-requisites before attempting to trigger necessary notification or task. The framework delivers sets of pre-checks that can be used to define the notification condition.

3. Define notification to be sent: In this step, you choose the notification ID to be used for the notification trigger. Notification ID is assigned to the notification template in customizing. You can define simple or complex notification content. For example, in case of sending email notification, the content of the notification can be complex. It can have specific layout or contain parameters from data objects. You can achieve this by creating your email template using standard SAP Email Template function in transaction code SE80. You can design the email content in HTML format and assign parameters that you have defined in framework customizing. You then assign this email template ID to the notification ID in the framework customizing. In case of simple notification content, for example, sent a request to service advisor to verify a service order. You can achieve this by using the FIORI push notification. Also in this step, you can define the notification priority, include attachment to the notification, define navigation target when the notification is clicked, define the target recipient, define validity of the notification, define context, and define sender.

4. Refer to “VSS 4.0 Communication Framework Cookbook” for explanation on how to use the notification trigger functionality.

Possible business case

Trigger notification from VSS event

Example scenario: Trigger a notification to service advisor when a service order is created.

Trigger notification from VSS Time Clocking event

Example scenario: Trigger a notification to service advisor when technician starts working on a job.

Task Processing

A transaction to define processing steps for task. Steps of processes can be defined to be executed one after another and while processing the steps, task attributes can be updated, task action or event can be executed, and notification can be sent to target recipient.

• Transaction code: /DBE/CF_TASK_TRX, or:

• On the SAP Easy Access screen, choose Logistics > Logistics Execution > Vehicle Sales and Service > Communication Framework Process Definition > Task Processing.

Prerequisites

The following is required before setting up the task processing steps:

1. Sender type is configured in customizing.

2. Recipient type is configured in customizing.

3. Notification channel is configured in customizing.

4. Communication event ID is configured in customizing.

5. Notification ID is configured in customizing.

6. Notification template is assigned to notification ID in customizing.

7. Task ID is configured in customizing.

8. Task status and task action is configured in customizing.

9. Task center layout and settings is completed.

Functionalities

Task ID is defined in customizing. You can define as many task IDs as needed per business requirement. Each task ID should represent a dedicated business process, for example: service order processing, additional job processing or sales order processing. You can assign business objects, communication group, navigation target and UI icons for each task ID.

Open

Once the task ID has been configured, you can create processing steps to each task ID.

Open

Imagine the scenario of a service order processing and you would like to monitor the lifecycle of the service order. You can create process steps that create or update task, update task attributes, execution task actions, update task priority and trigger notifications.

Open

From the example above, you define steps: Order created > Order released > Work started and so on. Each step can be executed by the communication event which is mapped with the VSS event. The steps can also be executed by the task actions which is triggered by the responsible assignee from the task center. You can assign task statuses to each process steps and monitor the status as the task progresses. “Final” step indicator can also be assigned to indicate that the processing of this service order is completed.

Refer to “VSS 4.0 Communication Framework Cookbook” for explanation on how to use the notification trigger functionality.

Dynamic Parameters

Essentials

Process design in Communication Framework in general involves definition of the trigger, starting conditions and actions to be performed. Actions are executed for the trigger when all starting conditions are met. In the process definition you have to cover particular business requirement, but you abstract from a specific business document, department, or organization. For example: when you define notification, that needs to be sent as a result of an event, in most cases the recipient (or recipients) is not known in advance and can only be determined depending on specific context (document, order or type of the event). In other words, Task (process) definition in Communication Framework acts as a template, that is applied for specific business object (document) when specific trigger occurs.

To address this requirement, most of the parameters that make up process definition in Communication Framework can be specified as dynamic parameters. It means, that their values are not saved as constants, but refer to variables, that are calculated on demand only when the process is triggered in the runtime. Such variables can point to simple globally available static value, to source business object attribute, current context value but can also form quite complex calculations using predefined or customer-defined functions. Of course, constant values are also supported.

Dynamic parameters can be used in notification customizing, notification trigger definition and task transaction definition. To check, whether given field value can be entered as dynamic parameter, please refer to Performance Assistant (F1 help) for the field in SAP-GUI. For example:

Open

Definition

Dynamic Parameter type

Dynamic parameters can be used in multiple ways. Here is the detailed description of all types of usage.

Constant value

Character-like constants (string literals) must be entered in quotes.

Numeric-like constants can be entered directly, using internal format.

Date and time can be provided as a string, using internal format.

Usage syntax:

Examples:

• Strings:

• Numbers:

• Date:

• Time:

Reference to global variable

Dynamic parameter can refer to any global variable. It means any variable, that is accessible globally from the ABAP scope in the Communication Framework runtime. It can be for example:

• Reference to system field (ABAP SYST structure).

• Reference to any static attribute of any global class.

Usage syntax:

Examples:

• System fields:

• Predefined variables:

• Static attributes of any global class:

Reference to predefined objects of the framework

Source business object in the scope of task instance or notification. In this case you can access any attribute supported by the object provider (refer to BAdI for source object provider and check list of objects delivered by the framework).

Usage syntax:

Communication task instance. Here you can access any attribute available from task instance header detail structure. Additionally, there are some special attributes supported (refer to the description of task special attributes).

Usage syntax:

Current trigger context. You can access value of any context field by parameter name. The result can be single value or a list (in case of parameter with multiple values).

Usage syntax:

All of the above objects (source business object, task instance, context) beside simple attribute access, support also function calls. It includes build-in functions (provided by the standard Communication Framework engine implementation) and customer defined functions, provided by dedicated BAdI implementations. For details on function definition please refer to function calling chapter.

Usage syntax:

Examples:

• $src-ms_vbak_com-vbeln – in case of VSS Order as source object, this gets field ‘vbeln’ of attribute ‘ms_vbak_com’ of VSS Order instance; check attribute nesting chapter below for more details; list of all available attributes can be found in documentation.

• $tsk-duedate – gets attribute ‘duedate’ of communication task instance; for list of all available attributes of task instance, please refer to documentation.

• $tsk-$property('VEHICLE_NO') – calls built-in function ‘PROPERTY’ of the task instance, passing ‘VEHICLE_NO’ as function parameter$

• ctx-reference_no – gets value of parameter ‘REFERENCE_NO’ from current trigger context.

• $ctx-@attachment – gets value of parameter ‘@ATTACHMENT’ from current trigger context; if there was more than one context params with the same name, the result of this dynamic parameter will be list of strings, containing all values found.

• $ctx-$cnt('JOBNR') – gets number of occurrences of field with name ‘JOBNR’ in the context.

Function call

Communication Framework supports framework-predefined built-in functions and customer-defined functions as well. Function in general is a part of logic, that is executed on demand and should return single result value based on input parameters.

Function can take zero, one or more importing parameters. Each parameter can be any type. Function must return one single returning value. Returning value can be any type. Parameters to functions can be provided in parentheses, comma separated. Parameters are referenced by their order (so parameter name plays no role from function call perspective).

Refer to chapter function calling for more details.

Function can be provided as:

• Global function (framework-predefined or customer defined),

• Source object function (framework-predefined or customer defined),

• Task instance function.

Global predefined functions are provided by Communication Framework. You can check the list of all available functions in documentation. Such functions are called using syntax:

Global customer-defined function indicates each compatible, publicly available class method. Compatible means, that interface of the method must conform to function requirement. Publicly available means public static method. This way any public static method of global class, with compatible interface, can be used as function in Communication Framework dynamic parameter. It can be SAP-delivered or customer-defined class. Functions of this type are called using following syntax:

Source object functions are functions offered by source object provider implementation. Customer can define his own function both in predefined source object and in customer-defined objects by implementing corresponding source object provider BAdI. Source object functions are called using following syntax:

Task instance functions are functions offered by Communication Task instance implementation. List of all available functions can be found in documentation. Such functions are called using following syntax:

Context functions are functions offered by Communication Task context. List of all available functions can be found in documentation. Such functions are called using following syntax:

Examples:

• $fnc-username(sy-uname) – calls built-in global function ‘USERNAME’, providing sy-uname as input parameter.

• $fnc-zcl_util-read_text('HEADER', 'Z001', $src-detail-vbeln) – calls static method ‘READ_TEXT’ of global class ‘ZCL_UTIL’, providing 3 parameters.

• $src-$get_field_job('000001', 'DESCR1') – calls built-in function ‘GET_FIELD_JOB’ of VSS Order source object provider, passing 2 parameters.

• $task-$actor_key('RES') – calls built-in task function ‘ACTOR_KEY’ with one parameter.

• $ctx-$get($src-zzname) – calls built-in context function ‘GET’ with parameter read from source object field ZZNAME.

Dynamic date

Communication Framework provides Dynamic Date Processor (DDP), that can be used to dynamically create date value. To use DDP, you must declare specific DDP operator together with parameters (optional). As result, single date value (of internal type DATS) is generated. List of all available DDP operators can be found in documentation.

Dynamic date utilizes function call denotation for definition and parameter passing. It can be defined using following syntax:

Examples:

• $date-month_end(6) – gets end of June of the current year.

• $d-week_begin – gets begin of the current week.

Case sensitivity

All references in dynamic parameter are case-insensitive, except of string literals. It means that $ctx‑reference_no works the same as $CTX‑REFERENCE_NO. But $tsk‑$property('VIN') is not the same as $tsk‑$property('Vin') although internal implementation of the corresponding function (like built-in function property for Task instance) can ignore case for input parameters.

Error handling

If dynamic parameter refers to non-existing attribute, non-existing context parameter or not existing or invalid function, it simply returns no value. No error is raised in this case and task/notification processing is not aborted. It depends on the usage, whether no value gives reasonable result or not.

Attribute nesting

You can access nested attributes of the variable. Variable must be flat structure - accessing internal table lines is not supported. Sub-attributes must be separated by hyphen '-'. Any level of nesting is supported.

Examples:

• task_priority-high – refers to component high of predefined, global constant task_priority.

• cl_global_class-header-field – refers to field field of structure header, which is static attribute of global class cl_global_class.

• $source-detail-customer-name1 – gets detail attribute of the source business object, then accesses component customer of the detail attribute and finally reads field name1 of customer component; both detail and customer must be structure-type components.

Calculations

Dynamic parameter supports simple calculation: addition/concatenation. You can define value as combination (summary) of more than one component. Each component must be valid value in terms of dynamic parameter. Components must be separated by '+' sign.

Depending on the resulting type of the components, the calculation can be concatenation (for character-like components) or addition (for numbers, dates, etc).

Examples:

• sy-datum + 2 results in date equal to two days after today,

• 'PFCG_ROLE_A_' + $src-detail-plant + '_ABC' assuming $src-detail-plant contains value ‘0001’, the result is decoded into string 'PFCG_ROLE_A_0001_ABC'.

Function calls

Dynamic parameters support not only access to static variables but allow also function execution. Functions in terms of dynamic parameter can be provided in following ways:

• Predefined (built-in) Communication Framework function,

• Customer-defined function (including any compatible method of the global class),

• Function defined by source object implementation.

Functions are specified in dynamic parameter using special syntax. It looks similar to simple variable access but supports additionally input parameters. Parameters can be provided to function by putting them as comma-separated list in parentheses ‘()’. If function does not require any parameter, or you don’t want to pass any parameter as they are optional, the parentheses can be omitted. Parameter values are passed to the function by their sequence. You can skip parameter only if it is not obligatory and there is no other parameter that must be provided after it. Each parameter must be valid value in terms of dynamic parameter. It means that parameter can be specified as constant, reference to variable or even another function call.

New functions can be implemented in two ways:

• As class method,

• As source object function (via source-object provider implementation).

• As task instance function (via CMF Task BAdI implementation).

Any class method is function-compatible when following conditions are met:

• It is accessible in the context of the execution. This is always true for public static method of the global class.

• It has zero or more importing parameters.

• It has exactly one returning parameter.

Usage syntax:

Examples:

• $fnc-zcl_utils-get_user_name(sy-uname)

It is also possible for customers to define functions that work as built-in functions in source object or Task instance. In that case, function call is passed to the source object via source object provider implementation (refer to BAdI for source object provider) or Task instance (refer to BAdI for CMF Task processing). With that approach, customers can add new functions to standard/already existing source objects or define functions for own source object implementation. During function execution, system passes function name together with parameter values into corresponding method of the BAdI implementation:

• For business source object

• For Task instance

Internal logic of the method is fully responsible for providing correct result for the call, based on input parameters.

Usage syntax:

Examples:

• $src-$partner_name('WE', true)

The BAdI implementation must then provide valid value as result of the call.

Predefined attributes, functions, DDP operators

Global attributes

TRIGGER

• Information about current event/action trigger

• Type: /DBE/CF_STR_ITRIGGER_DATA (DDIC structure)

TRUE

• Constant value abap_true (‘X’)

• Type: ABAP_BOOL

FALSE

• Constant value abap_false (‘ ‘)

• Type: ABAP_BOOL

UNDEFINED

• Constant value abap_undefined (‘-‘)

• Type: ABAP_BOOL

INITIAL

• Initial value (empty string)

• Type: String

DATE

• Constants for date

• Type: DATS

• Components

TIME

• Constants for time

• Type: TIMS

• Components:

NOTIF_PRIORITY

• Constants for notification priority

• Type: CHAR(1)

• Components:

TASK_PRIORITY

• Constants for Task priority

• Type: CHAR(1)

• Components:

Examples:

• true – equivalent for ‘X’

• trigger-event_id– ID of the Communication Framework event currently processing

• trigger-task_action – ID of the Task Action in case processing was triggered by action

• notif_priority-high – constant for high notification priority high (‘3’).

Predefined functions

COUNT

• Returns number of lines for table-type variable and 1 on case of any other not empty variable.

• Parameters:

• Result:

LENGTH

• Returns text length for character-like variable and 0 for any other variable.

• Parameters:

• Result:

USERNAME

• Returns long name of the SAP user provided as input parameter

• Parameters:

• Result:

CUSTOMER_NAME

• Returns customer name for customer number. GDPR conditions are considered.

• Parameters:

• Result:

DAYS_SINCE

• Calculates number of days that passed from specific date. If provided date is from the future, result is negative.

• Parameters:

• Result:

WRITE

• Returns output presentation of variable passed as input parameter.

• Parameters:

• Result:

FORMAT

• Formats text based on template and up to 9 parameters. Template variable must be defined as: &n, where n is variable number.

• Parameters:

• Result:

 Examples:

• $fnc-count($task-@attachment) – returns number of task attachments; refer to task instance special attribute @attachment for details

• $fnc-username($src-header_detail-ernam) – returns name of the source object creator (assuming source object provides creator username in field ERNAM of HEADER_DETAIL attribute

• $f-days_since($src-header_detail-erdat) – returns number of days since the source document creation.

Source objects

VSS Order

Object ID

• Class: BO

• Type: BUS2400

Attributes

HEADER

• Access to MS_VBAK_COM attribute of the VSS Order instance

• Data type: DDIC structure /DBE/VBAK_COM

HEADER_DB

• Access to MS_VBAK_DB attribute of the VSS Order instance

• Data type: DDIC structure /DBE/VBAK_COM

DIALOG_CONTROL

• Access to MS_DIALOG_CONTROL of the VSS Order instance

• Data type: DDIC structure /DBE/OE_DIALOG_CONTROL

Built-in functions

GET_JOB

• Access to the Job data

• Parameters:

• Result type: DDIC structure /DBE/JOB_COM

GET_JOB_FIELD

• Access to the single Job field value

• Parameters:

Result type: any

GET_ITEM

• Access to the Item data

• Parameters:

• Result type: DDIC structure /DBE/VBAP_COM

GET_ITEM_FIELD

• Access to the single Item field value

• Parameters:

• Result type: any

GET_DPR

• Access to the DPR document data

• Parameters:

• Result type: DDIC structure /DBE/ORD_DPR_LIST

GET_PARTNER_INFO

• Get data for the partner of the given role. If there are more than one partner for the role, only first one is selected.

• Parameters:

• Result type: DDIC structure /DBE/ORD_PARTNER_S

GET_PARTNER_NAME

• Get name of the partner in given role. If there are more than one partner for the role, only first one is selected. Takes GDPR rules into account.

• Parameters:

• Result type: string

 Examples:

• $src-ms_vbak_com-vbeln – for VSS Order as source object: return VSS Order number (field VBELN of attribute MS_VBAK_COM).

• $src-$get_field_job($ctx-/dbe/jobnr, 'DESCR1') – for VSS Order as source object: return value of field DESCR1 of Job with number provided by context parameter /DBE/JOBNR.

• $src-$get_item($ctx-/dbe/posnr)-zmeng – for VSS Order as source object: return value of the field ZMENG (quantity) for order item number equal to context field /DBE/POSNR.

• $src-$get_partner_name('AG', true) – for VSS Order as source object: returns Sold-To-Party name; when manual address has been entered in the order, it takes name from order document, not customer master data.

SRS Order

Object ID

• Class: BO

• Type: /DBME/WORD

Attributes

Any field from DDIC structure /DBME/WMA_STR_ORDH_DATA.

VSS Vehicle

Object ID

• Class: BO

• Type: /DBE/VEHI

Attributes

Any field from DDIC structure VLCVEHICLE.

DPF Transaction

Object ID

• Class: OT

• Type: /DBE/DP_TRANSACTION

Attributes

Any field from DDIC structure /DBE/DP_STR_PYMNT_TR_DETAIL.

Task instance

Attributes

In general, all simple fields of structure /DBE/CF_STR_INS_TASK_BASE are available as Task instance attributes. It means, that any customer-enhancement fields added to that structure will become available as well. Below is the list of most important standard Task instance attributes.

TASK_ID

• Task ID

• Data type (internal): CHAR 30 (/DBE/CF_TASK_ID)

TASK_KEY

• Key properties formatted into one field

• Data type (internal): CHAR 70

STATUS

• Current status

• Data type (internal): CHAR 10 (/DBE/CF_TASK_STATUS)

STATUS_PR

• Previous status

• Data type (internal): CHAR 10 (/DBE/CF_TASK_STATUS)

STATUS_TS

• Time of the status change (timestamp)

• Data type (internal): DEC 15 (TZNTSTMPS)

HISTRY_TS

• Time of history change (timestamp)

• Data type (internal): DEC 15 (TZNTSTMPS)

SRCOB_CL

• Source object class

• Data type (internal): CHAR 2 (/DBE/CF_SRCOB_CLASS)

SRCOB_TYPE

• Source object type

• Data type (internal): CHAR 30 (/DBE/CF_SRCOB_TYPE)

SRCOB_KEY

• Source object key

• Data type (internal): CHAR 70

SRCOB_EXTID

• Source object external key

• Data type (internal): CHAR 50

PRIORITY

• Task priority (priority code)

• Data type (internal): CHAR 1 (/DBE/CF_TASK_PRIORITY)

DUEDATE

• Due date (date)

• Data type (internal): CHAR 8 (DATS)

XREATM_TS

• Expected reaction time (timestamp)

• Data type (internal): DEC 15 (TZNTSTMPS)

CREATED_AT

• Time of the task creation (timestamp)

• Data type (internal): DEC 15 (TZNTSTMPS)

CHANGED_AT

• Time of the task update (timestamp)

• Data type (internal): DEC 15 (TZNTSTMPS)

CLOSED

• Task closed indicator (Boolean)

• Data type (internal): CHAR 1(XFELD)

CREATED_BY

• Username of the task creator

• Data type (internal): CHAR 12 (UBNAME)

CHANGED_BY

• Username of the task last processor

• Data type (internal): CHAR 12 (UBNAME)

PROGRESS

• Progress value (percentage number)

• Data type (internal): DEC 3.0

ITS_OBJTID

• Internal Task Instance UID

• Data type (internal): CHAR 32

ITSUID

• Internal Task Instance UID (url-formatted)

• Data type (internal): CHAR 32

STATUS_CT

• Time elapsed from the status change (in seconds)

• Data type (internal): DEC 10

HISTRY_CT

• Time elapsed from the previous history update (in seconds)

• Data type (internal): DEC 10

INITIATED_BY

• Initiator of the last task update (encoded recipient ID)

• Data type (internal): CHAR 82

XREATM_DATE

• Expected reaction time (date part)

• Data type (internal): CHAR 8 (DATS)

XREATM_TIME

• Expected reaction time (time part)

• Data type (internal): CHAR 6 (TIMS)

XREATM_EXC

• Expected reaction time has exceeded (Boolean)

• Data type (internal): CHAR 1(XFELD)

Special attributes

There are also special attributes predefined by the framework, that are used for access to some Task instance information, that is not available directly as simple attribute. It includes access to texts, attachments and Task properties. Special attributes are indicated by ‘@’ at the beginning of the name.

@TEXT

@T

• Return text element information.

• Usage syntax:

• Component meaning:

Components are optional, default values are used when not provided. Component can be omitted only if there is no subsequent component that needs to be provided.

• Return type:

@ATTACHMENT

@ATTA

@A

• Return attachment information.

• Usage syntax: