Functions

This section describes the main functionalities in the VSS Communication Framework. Imagine the following user stories:

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”.

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.

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

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.

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:

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:

<attribute>

Examples:

• Strings:

o   'A001'

o   'Long description'

• Numbers:

o   123

o   99.78

o   -5

• Date:

o   '20230123'

• Time:

o   '081500'

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).

o   Predefined variable provided by the Communication Framework (refer to documentation for list of all available variables).

• Reference to any static attribute of any global class.

o   In that case class name is specified as attribute and class attribute is specified as subattribute.

Usage syntax:

<attribute>[-<subattribute1>[-<subattribute2>…]]

Examples:

• System fields:

o   sy-uname

o   sy-tcode

o   sy-datum

• Predefined variables:

o   task_priority-low

o   true

o   false

• Static attributes of any global class:

o   cl_abap_char_utilities-cr_lf

Reference to predefined objects of the framework

xxxx

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.

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-ms_detail-customer-name1 – gets ms_detail attribute of the source business object, then accesses component customer of the ms_detail attribute and finally reads field name1 of customer component; both ms_detail and customer must be structure-type components.

Calculations

Dynamic parameter supports simple calculation: addition. 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_' + t001w-werks + '_ABC' is translated into string 'PFCG_ROLE_A_0001_ABC' (assuming t001w-werks is globally accessible and equal to '0001').

Function callings

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.

Function execution can be defined in dynamic parameter using special syntax. It looks similar to simple variable access, but in contrast to it, functions can support 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 and they are not obligatory, 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).

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.

Customer can define his own functions by implementing compatible methods in global classes in customer namespace or use any compatible method in already existing class.

Such functions can be called using following syntax:

$func|$fnc|$f-<class_name>-<method_name>[(parameter1, parameter2, …)]

Examples:

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

o   Calls method get_user_name of class zcl_utils, providing current username as first input parameter.

It is also possible to define functions that refers directly to source object during task/notification processing. In this case, function call is passed to the source object via source object provider implementation (refer to BAdI for source object provider). This way 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 method /DBE/IF_CF_ENH_SRCOB_PROVIDER~GET_ATTRIBUTE of BAdI /DBE/CF_SRCOB_PROVIDER. Internal logic of this method is fully responsible for providing correct result for the call, based on input parameters.

Functions of this type can be called using following syntax:

$source|$src|$s-$<function_name>[(parameter1, parameter2, …)]

Examples:

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

o   Call function partner_name of current source object providing ‘WE’ as input parameter.

o   Technically method GET_ATTRIBUTE of BAdI /DBE/CF_SRCOB_PROVIDER is called in this case with following input:

• IS_SOURCE_ID > contains identification of the current source business object,

• IV_ATTRIB > is set to value ‘$partner_name’,

• IT_PARAMS > contains value ‘WE’ in first line and value ‘X’ (internal representation of ABAP true value) in second line.

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

List of delivered attributes, function, DDP operators

Predefined attributes

Examples:

• true – equivalent for ‘X’

• ms_trigger_data-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

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

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.

Task instance

Examples:

• $task-xreatm_ext – returns ‘X’ (ABAP ‘true’) when expected reaction time has exceeded

• $task-$actor_key('RES') – returns recipient key for the ‘Responsible’ actor role

• $task-@text – returns content of the last comment

• $task-@text-description-created_at – returns time of the task description update

• $task-@property-vin – returns value of the ‘VIN’ task property

• $task-@attachment-image/* – returns ID of all image attachments (result is a list of attachment ID)

Dynamic Date Processor operators

Examples:

• $date-year_end – gets end of the current year

• $date-year_end(sy-datum, 1) – gets end of the next year

• $date-quarter_begin(sy-datum, -1) – gets begin of the previous quarter

• $date-quarter_end($date-year_begin, 1) – gets end of the 2^nd quarter of the current year

VSS Task Center

VSS Task Center is a FIORI application that is built to track and monitor progress of task of VSS business objects. It is designed according to SAP FIORI design guideline and utilizes SAP FIORI Notification functionality to support the push notification and notification management.

The VSS Task Center adapts the Flexible Column Layout, which is a layout control that displays multiple floorplans in a single page. This layout offers faster and more fluid navigation between the floorplans. It is very responsive and expandable, powered by the FIORI functionalities and navigation tools that is available by standard.

Functionalities

The following describes the general functionalities of the VSS Task Center:

1. Monitor progress of task with progress status, progress percentage, task status, task priorities and task criticality.

2. Historical record of task execution with time stamp for audit trail purposes.

3. Segregation of tasks into customizable folders (represented by tabs); for example: “To Do”, “My Task”, “My Team’s Task” and “All Task”.

4. Filter functions to search tasks according to user-defined search criteria.

5. Export search result into raw data for further analysis.

6. Link to business objects which will navigate the user directly to the business objects.

7. Link to specific task upon clicking the FIORI notification.

8. VSS event execution directly in the task without the need to go into the backend transaction.

9. Customizable task actions to update task attributes such as task status and task priorities.

10. Management of various attachment types from image, documents, audio and video with upload and download functionality and playback capability.

11. Audio and video capturing functionality.

12. Attachment synchronization between the task and the business object.

Possible business case

Execute VSS events from Task Center

Example scenario: Release a service order.

With the introduction of the VSS Communication framework, you can now execute the order release event from the notification or from the task center.

Execute Task Action from Task Center

Example scenario: Increase task priority.

In addition to executing the VSS events from the task center, the framework also introduced task actions. Task actions can be defined in framework customizing and assigned to task ID. You can configure the task action to update task attributes such as task status, task priority, due date and expected in date.

Refer to “VSS 4.0 Communication Framework Cookbook” for explanation on how to setup the task center.

Plugins

The communication framework provides plugins to map the relevant VSS applications or objects with the communication event ID and define the notification triggering criteria.

VSS Order Engine: VSS Event Mappings

Prerequisites

The following is required before setting up the mapping:

1. VSS event is configured in customizing.

2. Communication event ID is configured in customizing.

3. VSS Order Status is configured in customizing.

Functionalities

This customizing allows you to map VSS event with the communication event ID. For example, you have a business requirement to trigger notification or update task when a particular VSS event is executed and in which level is the event is executed.

• Transaction code: /DBE/CF_VSS_EVT or;

• In Customizing for Logistics Execution, choose “Vehicle Sales and Service (VSS) > Common Functions > Communication Framework > Plugins > VSS Order Engine > VSS Event Mappings”.

You can also define the following:

• Attribute condition: Define mapping condition for selected VSS fields, for example, this mapping is valid only for order type “2000”.

• Status condition: Define mapping condition for selected VSS Order Status value and in which level the mapping should be validated for example, order level, header level, item level or job level.

Time Clocking: Event Type Mappings

Prerequisites

The following is required before setting up the mapping:

1. Time clocking order type is mapped to the framework key structure in customizing.

2. Time clocking event type is configured in customizing.

3. Communication event ID is configured in customizing.

Functionalities

This customizing allows you to map VSS Time Clocking events with the communication event ID. For example, you have a business requirement to trigger notification or update task when a particular VSS Time Clocking event type is executed (i.e.: work started, work ended, work ended and time confirmed, go on break, etc).

• Transaction code: /DBE/SPRO or;

• In Customizing for Logistics Execution, choose “Vehicle Sales and Service (VSS) > Common Functions > Communication Framework > Plugins > Time Clocking > Map Time Clocking Events”.

In this customizing, you map the time clocking event type with the relevant communication event ID in order to trigger a notification or update certain task. You also include additional parameters to the mapping.

Resource Scheduling: SRS Event Mapping

Prerequisites

The following is required before setting up the mapping:

1. SRS order type is configured in customizing.

2. SRS notification event is configured in customizing.

3. Communication event ID is configured in customizing.

Functionalities

This customizing allows you to map VSS SRS events with the communication event ID. For example, you have a business requirement to trigger notification or update task when a particular VSS SRS event is executed (i.e.: appointment scheduled, appointment cancelled, etc).

Please note that VSS SRS already has its own functionality to trigger notification. This plugin is additional function within the communication framework to be used by SRS in case of task processing for example, you want to create or update certain task when the SRS event is executed.

• Transaction code: /DBE/SPRO or;

• In Customizing for Logistics Execution, choose “Vehicle Sales and Service (VSS) > Common Functions > Communication Framework > Plugins > Resource Scheduling > SRS Event Mapping”.

Please refer to the “VSS 4.0 Configuration Guide” for more detail on how to configure the plugins.

VMS Vehicle: VMS Action Mapping

Prerequisites

The following is required before setting up the mapping:

1. VMS action is configured in customizing.

2. Communication event ID is configured in customizing

Functionalities

This customizing describes the mappings that can be defined between SAP VMS actions and the Communication Events. The objective is to build the relationship between VMS actions and Communication Event ID. For example, when a particular VMS action is executed, it will automatically fire the Communication Event ID, which in turn may result in a notification being triggered or a task being executed (depending on how the process is defined).

• Transaction code: /DBE/SPRO or

• In Customizing for Logistics Execution, choose Vehicle Sales and Service (VSS) > Framework Components > Communication Framework > Plugins > VMS Vehicle > VMS Action Mapping.

Please refer to the “VSS 5.0 Configuration Guide” for more detail on how to configure the plugins.

Task Substitution and Delegation

VSS Communication Framework supports the ability to route task or notification in case of for example, absence or vacation. Standard SAP functionality (transaction RMPS_SET_SUBSTITUTE) can be used to determine a substitute. Substitution can be appointed, and duration of the substitution can be maintained and activated. Communication Framework will validate the substitution determination and duration. If the condition matches, Communication Framework will assign the relevant task to the substitute.

Support multi-language notification

SAP Email Template functionality allows selection of language and creation of email template in multiple languages.

The following attributes are used to determine the communication language depending on the target recipient:

Business Partner

In case of sending notification to a business partner or customer, Communication Framework validates the customer’s “corresponding language” (defined in transaction BP) with the language defined in the email template and delivers the notification accordingly.

SAP User

In case of sending notification to an SAP User ID, Communication Framework validates the SAP User’s “language” (defined in transaction SU01) with the language defined in the email template and delivers the notification accordingly.

Employee ID

In case of sending notification to an Employee ID, Communication Framework validates the Employee’s “language” (defined in transaction PA30) with the language defined in the email template and delivers the notification accordingly.

Integration with Messaging Applications

Communication Framework supports bi-directional integration with popular messaging applications (internet communicators, like WhatsApp or Line). This integration is realized as one of the communication channels.

Customers are free to integrate with any messaging applications of their choice. To do so, customers must refer to the integration documentation provided by the messaging application of choice and perform the required account creation, technical setups, and customizing steps. Setups and customizing may differ between messaging applications as they may be using different technologies. In any case, Communication Framework offers BAdIs where customer can implement dedicated logic to realize the integration.

Communication Framework offers out-of-box integration with Whatsapps and LINE. Refer to the Communication Framework Cookbook for implementation detail.

Adherence to GDPR requirement

The system allows for customer to define allowed communication methods with regards to clearly defined purposes. The consents are recorded together with the exact description that is presented to the customer.

The consents are stored within the following objects:

• Business Partner/Customer

• Service Resource Scheduling Order header

• Online Appointment Scheduling (OAS) User master data

The consents can be updated by customers directly or on their behalf by authorized employees in the following applications:

• Business Partner Maintenance (BP)

• VSS Order processing

• OAS user maintenance

• To-Do basket order maintenance

• Mobile Service Advisor

The Communication Framework respects communication preferences by not sending notifications in case consent was not given.