SAP S/4HANA on-premise PI Adaptor for Field Service Edge. Developer Guide

SAP S/4HANA on-premise PI Adaptor for Field Service Edge Developer Guide

The software with this guide is furnished under a license agreement and may be used only according to the terms of that agreement. Copyright Notice Copyright 2010-2017 ClickSoftware, Inc. All rights reserved. Trademark Edge Scheduling is a trademark of ClickSoftware; SAP is trademarks of SAP AG No part of this publication may be copied without the express written permission of ClickSoftware, Inc. Contact Information Contact information is available from the ClickSoftware web site: http://www.clicksoftware.com For support services, mail to support@clicksoftware.com or see http://www.clicksoftware.com/services/support.htm. For general information, mail to sales@clicksoftware.com Publication Notice This guide has been carefully compiled. The information in this guide does not constitute a warranty of performance. Furthermore, ClickSoftware reserves the right to revise this publication and make changes from time to time in the content thereof, without obligation to notify any person of such revisions or changes. ClickSoftware assumes no liability for losses incurred as a result of out-of-date or incorrect information in this guide. Version Document Version Date Changes 1.0 2017-05-10 Initial release

S/4HANA PI Adaptor for Field Service Edge - Developer Guide i Contents Contents... i Overview... 4 Document structure... 4 Support statement... 4 S/4HANA PI Adaptor architecture... 5 S/4HANA PI Adaptor data structures... 5 SAP Business Add-Ins... 6 S/4HANA event triggers... 6 Business Transaction Events (BTE) and HCM Workflows... 6 ABAP Reports... 7 Remote Function Calls (RFC)... 7 General recommendations for WSOPT enhancements... 9 Best practices for ABAP enhancements... 9 The usage of the application log (SLG1)... 11 Process Infrastructure content... 11 Maintaining Software Catalog Entries in System Landscape Directory12 Exporting WebService interfaces in Field Service Edge... 13 Working with Enterprise Service Builder... 13 Enhancements to the PM module... 16 Using additional qrfc destinations... 16 Extending the assignment integration... 17 Status dependent integration of data on order update in Field Service Edge 18 Extending the order integration in S/4HANA... 19 Filtering and modifying updates... 19 Implementing field level updates... 21 Adding customer specific data to the order integration... 23 Enhancements to the HR module... 25 Extending the engineer relevance check for transmission to Field Service Edge... 25 Implementing rotating shifts... 26 Suppressing engineer calendar updates during BGO activities... 26 Implementing data privacy for Non-Availability reasons... 27 Modifying customer specific data in the engineer integration... 28 Enhancements to the Mobile module... 30 Enhancing the time confirmation integration... 30 Changing the data source for time stamps... 30 Appendix... 31

S/4HANA PI Adaptor for Field Service Edge - Developer Guide ii Operation and message mappings... 31 Internal function modules... 36 HR Integration... 37 PM Integration... 40 Mobile Integration... 42 Enhancement Spots... 46 Enhancement Spots in the HR module... 46 Enhancement Spots in the PM module... 47 Enhancement Spots in the Mobile module... 48 Field reference for RFC function modules... 51 Integration RFC Modules for HR business objects... 51 Integration RFC Modules for PM business objects... 55 Integration RFC Modules for Mobile business objects... 56 Integration RFC Modules for Roster business objects... 58 Field reference for structures... 59

S/4HANA PI Adaptor for Field Service Edge - Developer Guide iii List of Figures Figure 1: SLD - Product definition with two units... 12 Figure 2: SLD - BuildTime dependency for SWCV Z_CLICK_SO_SERVER... 12 Figure 3: Assignment of installed products and software to a business system... 13 Figure 4: Field Service Edge Legacy Administration Tool - Outgoing message settings... 13 Figure 5: Customer SWCV with local copies of design objects in PI ESR... 14 Figure 6: Workflow for changing an Operation Mapping... 15 Figure 7: Function module with implicit enhancement at the end of the module... 16 Figure 8: Internal Assignment handler... 18 Figure 9: Graphical representation of conditional data mapping... 23 Figure 10: Example of order update enhancement objects in ESR... 24 Figure 11: Message mappings in S/4HANA, part 1... 32 Figure 12: Message mappings in S/4HANA, part 2... 33 Figure 13: Message Mappings in S/4HANA, part 3... 34 Figure 14: Message Mappings in S/4HANA, N/A integration... 35 Figure 15: Layering model Calendar Integration... 37 Figure 16: Layering model Engineer Integration... 38 Figure 17: Layering model (Non-)Availability Integration... 39 Figure 18: Layering model (Non-)Availability Inbound Integration... 40 Figure 19: Layering model PM Order Integration... 41 Figure 20: Layering model PM Inbound Integration... 41 Figure 21: Layering model Mobile Time Confirmation Inbound... 42 Figure 22: Layering model Mobile Notification Inbound... 42 Figure 23: Layering model Catalog Download... 43 Figure 24: Layering model Material Download... 43 Figure 25: Layering model Mobile Measurement Document Inbound Integration. 44 Figure 26: Layering model Material Consumption Inbound Integration... 44 Figure 27: Layering model Asset Update... 45

Ch 1 Overview 4 C H A P T E R 1 Overview This document contains a developer guide for the S/4HANA PI Adaptor for Field Service Edge integrated via SAP Process Integration (SAP NetWeaver PI) functionality. The relevant releases are SAP S/4HANA on-premise 1610, Field Service Edge. Required version of SAP NetWeaver PI is 7.5 with Enhancement Package 0 or higher. Document structure Field Service Edge and S/4HANA have different data models and describe similar entities in different ways. In each of the following chapters you can find a discussion of the different models and the mappings provided by the S/4HANA PI Adaptor. Possibilities to adjust these mappings according to your needs and the necessary customizing settings for Field Service Edge are described in the final section. Chapter 2Fehler! Verweisquelle konnte nicht gefunden werden. introduces the general architecture of the S/4HANA PI Adaptor components, mechanisms and interfaces. General recommendations and common concepts important to the enhancement of the standards are provided. Chapters 3 to 5 outline the steps which are necessary to adopt the out-of-the-box integrations of each module to the local environment and needs. Each short scenario describes how to extend the default structures and adopt all related parts. The

Ch 1 Overview 5 appendix includes listings and figures which describe the Operation and message mappings, the Internal function modules, the

Ch 1 Overview 6 Support statement Enhancement Spots and the Field reference for RFC function modules. The S/4HANA PI Adaptor is designed for customization and integration in an open environment. The customization and configuration part is handled in the main S/4HANA PI Adapter documentation. This developer guide completes the documentation with general advices, best practices for customer enhancements and an introduction to the S/4HANA PI Adaptor Application Programing Interface (API). Despite the open design and available access to all the internal mechanisms as well as to all interfaces support can be only granted for the standard coding and out-of-the-box functionality. The developer APIs and this documentation are provided AS-IS and do not claim to be complete or free of errors. Please open a support request for errors found in this document. Support cannot be provided for the following cases: A modified functionality is not working as expected. A required function cannot be implemented using the provided APIs. This developer guide is missing information on implementing a use case. The standard coding needs to be enhanced or explained. For enhancement requests respectively project consulting needs, please contact the ClickSoftware Support or your ClickSoftware representative for details.

Ch 2 S/4HANA PI Adaptor architecture 7 C H A P T E R 2 S/4HANA PI Adaptor architecture The S/4HANA PI Adaptor for Field Service Edge is delivered as an out-of-the-box experience covering standard integration scenarios for all business objects described in the main documentation. These default integrations are based on a common configuration in S/4HANA and an unmodified database scheme in Field Service Edge. The S/4HANA PI Adaptor is not limited to the standard integration, but it can be used as a starting point and a template for local enhancements according to individual needs. The following sections outline the general mechanisms to enhance the defaults provided by the S/4HANA PI Adaptor. S/4HANA PI Adaptor data structures The data structures used for data exchange between the S/4HANA and Field Service Edge contain a common superset of the information being available by default in each of the systems and which may be needed for integration purposes. The default set of information available for integration at the S/4HANA side of the S/4HANA PI Adaptor is documented in the Field reference for RFC function modules in the appendix starting at page 31. Sometimes additional details may be required to allow Field Service Edge to optimize the workforce in the best way or it is necessary to map the data in a different way. Both types of change require one or more of the following steps: Enhance the data structure in S/4HANA system Add additional ABAP code in the S/4HANA system to populate the new structures with data Enhance the data structure in the Field Service Edge system Add a new PI mapping between source and target structure or change an existing one The data structures used in the RFC modules can be enhanced by adding an append structure with the desired additional data. The ABAP Workbench (SE80) can be used to browse the available structures and to enhance them. A developer license is necessary for these enhancements. The appended data structures are only a container for additional data and must be populated with actual values during the processing of the related business objects. The place to add the additional program logic to do so depends on the business object to be enhanced. Please follow the examples outlined in the relevant sections for Adding customer specific data to in the following chapters. The equivalent enhancement method to add additional data to business objects in the Field Service Edge database is the definition of User Defined Properties. (UDP) Usually each UDP has its equivalent customer field in the related SAP structure and the other way round. The Field Service Edge Schema Editor provides access to the database scheme, where UDPs can be added to the business objects.

Ch 2 S/4HANA PI Adaptor architecture 8 The linkage or mapping between the source structure and the target structure is performed in the SAP PI mapping. Before these mappings can be enhanced, all the changes to the delivered structures must be re-imported into the PI Enterprise Services Repository. The preparations required to start PI development and the steps to re-import the changed structures are described in the Process Infrastructure content section on page 11. SAP Business Add-Ins The processing of each object and each event in the S/4HANA PI Adaptor follows a predefined processing flow with multiple steps, which are defined by delivered function modules. The integration provides a mechanism to extend or override the default behavior at some of the processing steps through Business Add-Ins (BAdI). These BAdIs reside inside Enhancement Spots inside the pre-defined processing flows. By defining a new implementation of the Business Add-In the default implementation can be replaced or enhanced. The processing flows and their Enhancement Spots providing the BAdIs are documented in the Appendix starting on page 36. S/4HANA event triggers For enhancements beyond adding additional data during the processing flow or beyond changes to the default enhancement spots, it is possible to replace the automatic event handlers and reports. Each processing flow in the S/4HANA PI Adaptor is started by such an event handler it may be triggered by a standard SAP Business Transaction Event (BTE), a function module for the standard SAP HCM workflow processing (SWEHR3), an incoming message from Field Service Edge or an ABAP report. The following sections describe the general concepts for each of these event handlers. Business Transaction Events (BTE) and HCM Workflows Business Transaction Event modules (BTEs) are used as event handlers registered for selected object events in the integrations for PM and the modules for the HR Workflows are used as event handlers for HR. The available modules as of WSOPT 216_700 patch 09 are: Publish & Subscribe BTE: Customer Enhancements (FIBF) /WSOPT/C_ASSET_ UPDATE_ BTE /WSOPT/C_CONFI_ UPDATE_ BTE /WSOPT/C_ORDER_ UPDATE_ BTE HR-CA: Event Linkage for Customer (SWEHR3) /WSOPT/C_ ALLOCATION_UPDATE /WSOPT/C_ATTABS_ UPDATE /WSOPT/C_CONTRACTS_UPDATE /WSOPT/C_ENGINEER_UPDATE For more information about the features supported by each of those modules please consult the main S/4HANA PI Adaptor documentation.

Ch 2 S/4HANA PI Adaptor architecture 9 ABAP Reports These modules are the entry points for the processing of events. In these modules some pre-processing and a basic check for integration relevance are executed. These handlers are delivered with the WSOPT Add-On and belong to the SAP namespace therefore no customer changes are allowed to them. The best approach to add changes to the default behavior is to copy the selected module into customer namespace and perform the changes in the copy. This approach allows the maintenance of an independent copy of the original coding and makes it possible to selectively adopt changes provided with future product updates without interrupting the running processes. ABAP reports or programs in the S/4HANA PI Adaptor are used for mass transfer of integrated business objects during initial transfer or update. The reports have a user input form for selection of objects, which are then passed to the standard processing workflow as used by the event handlers. The delivered programs belong to the SAP namespace and should not be directly extended or modified, but can be used as a template for a customer enhanced version. This might be necessary for cases where additional selection criteria are needed. The following enumerations contain the reports delivered with the standard package. HR module: /WSOPT/C_DOWNLOAD_BASECAL_PI /WSOPT/C_DOWNLOAD_ENG_PI /WSOPT/C_DOWNLOAD_INFTY_PI /WSOPT/C_NON_AVAILIBILITY_PI PM module: /WSOPT/C_DOWNLOAD_ORDER Mobile module: /WSOPT/DOWNLOAD_MATERIAL /WSOPT/C_DOWNLOAD_CATALOGUE New reports can be created for mass transfer of customer specific objects. Remote Function Calls (RFC) Remote Function Call (RFC) is the standard SAP method for communication between SAP systems. RFC calls a function to be executed in a remote system. The S/4HANA PI Adaptor for Field Service Edge uses two variants of RFC: synchronous RFC (srfc) for external integration with SAP PI and queued RFC (qrfc) for the internal processing. The first variant (srfc) executes the function call based on synchronous communication, meaning that both systems involved must be available at the time the call is made. The latter one is an extension of transactional RFC (trfc), which is a genuine asynchronous communication method that executes the called function module just

Ch 2 S/4HANA PI Adaptor architecture 10 once in the RFC server. The remote system need not be available at the time when the RFC client program is executing a trfc. The trfc component stores the called RFC function, together with the corresponding data, in the SAP database under a unique transaction ID (TID). If a call is sent and the receiving system is down, the call remains in the local queue until a later time. The calling dialog program can proceed without waiting to see whether or not the remote call was successful. If the receiving system does not become active within a certain amount of time, the call is scheduled to run in batch. trfc is always used if a function is executed as a Logical Unit of Work (LUW). Within a LUW, all calls are executed in the order in which they are called, executed in the same program context in the target system, executed in a single transaction, which means they are either committed or rolled back as a unit. To guarantee that multiple LUWs are processed in the order specified by the application, trfc can be serialized using queues (inbound and outbound queues). This type of RFC is called queued RFC (qrfc). The queues used by the S/4HANA PI Adaptor have a fixed naming scheme, which must be adopted by customer enhancements for a consistent background processing. The LUWs in the queues are grouped by the main business objects: CS_SDL_<AUFNR> : used by orders, material consumptions, measurement points, notifications, assignments, time confirmations, equipment, functional locations CS_SDL_HR<PERNR> : used by engineers, engineer calendars, contracts, non-availabilities, shifts, allocations CS_SDL_HR_C<BCALNAME> : used by base calendars CS_SDL_M<IMRC_POINT> : used by measurement documents (inbound) Enhancement-relevant RFC modules Most processing steps in the qrfc modules are located inside the default implementations of the before-mentioned enhancement spots and can be easily enhanced or replaced. The srfc modules used for integration must be divided into two groups: outbound interfaces used solely to push data into SAP PI and inbound interfaces receiving data from SAP PI with some preliminary functionality to validate and preprocess the passed data. The outbound interfaces can be extended solely by extending the data structures as described before. The inbound interfaces must process the received data (i.e. must copy the data from the communication structure to the related internal structure), but cannot be enhanced directly in most cases and must be copied to a local copy, where the changes are performed. The complete list of inbound and outbound RFC modules with their interface can be found in appendix chapter Field reference for RFC function modules. For easier reference a short list of inbound RFC modules follows.

Ch 2 S/4HANA PI Adaptor architecture 11 Task status update and task assignments: /WSOPT/C_PI_ASSIGNMENT_ UPDATE /WSOPT/C_PI_OPR_ STATUS_ UPD Task-related updates from mobile users: /WSOPT/C_PI_TIMECONF_INS /WSOPT/C_PI_NOTIF_UPD_IN /WSOPT/C_PI_MEASDOC_INS /WSOPT/C_PI_MATCON_INS Non-Availabilities for Engineers: /WSOPT/C_PI_NA_DEL_IN (inbound wrapper for enhancement spot) /WSOPT/C_PI_NA _INS_IN (inbound wrapper for enhancement spot) /WSOPT/C_PI_NA _UPD_IN (inbound wrapper for enhancement spot) Replacing an inbound RFC module which does not use an enhancement spot requires the replacement of the related message mapping in SAP PI as well. This is outlined in the last section about Process Infrastructure content. General recommendations for WSOPT enhancements This section provides general recommendations for ABAP-based customer enhancements of the S/4HANA PI Adaptor. These recommendations are only provided as best practices as used in the most parts of the standard product, with no claims of being complete. If there are good reasons, any of those recommendations can be ignored. For most enhancements it is recommended to copy the default coding, unless you know exactly what you are doing (and why). Best practices for ABAP enhancements Event handlers for PM BTEs and HR-CA linkage: Do not write to the application log the /WSOPT/ log object is not initialized at that stage. Do not output any text messages. The user can be notified about uncritical conditions by using the MESSAGE statement with message type W or I (warning or info). Messages are displayed in the bottom status line of the current SAPGui window. A message of type E (exception) should be used to cancel the current processing. It hinders the user to save the current state until the input is completed respectively corrected. Do not trigger a COMMIT WORK statement.

Ch 2 S/4HANA PI Adaptor architecture 12 ABAP reports: Please use WRITE statements as the main output channel. You may write to the application log. The ABAP report should be responsible for the whole life cycle of the application log handling. (Create, Write and Save) A message of type W (warning) opens a dialog box and can be used to notify the user about uncritical conditions. A message of type E (exception) cancels the current program. It should be used for critical conditions, e.g. missing configuration or communication errors that would make further processing redundant. The COMMIT WORK statement may be used to group larger units of work. An incorrect usage of this statement may influence the runtime performance. The addition of AS SEPARATE UNIT to the CALL FUNCTION IN BACKGROUND TASK will ensure that each function will be executed separately as an LUW. Custom WSOPT enhancement spot implementations: The enhancement spots of the WSOPT integration are usually being processed in background tasks within an LUW of a queued RFC. The application log is the main output channel. Please see the section about application log handling below. Do not use WRITE output statements. Do not use any message types other than E (exception). This will cancel the current qrfc with status SYSFAIL. Please provide an error reason description of possible in the message text. For temporary problems, e.g. object is locked by user or communication error, please try to use the RESTART_OF_BACKGROUNDTASK function module, wherever possible. The COMMIT WORK statement should be used very carefully at the end of the processing. The statement can lead to a preliminary closing of the application log object. For cases where a custom qrfc handler might be necessary, it is recommended to follow the coding principles and naming schemes from the standard adaptor implementation. Especially Use the same (or similar) LUW names for queues. Create a separate unit for each function module running in background task (AS SEPARATE UNIT).

Ch 2 S/4HANA PI Adaptor architecture 13 Use the same external reference ID naming schemes and include the SAPID prefix for uniquely identifying SAP objects. The usage of the application log (SLG1) The application log is the main output channel and tracing tool for all S/4HANA PI Adaptor related background processes. The main log object for all adaptor related messages is /WSOPT/. In addition each integration module HR, PM and MOBILE has its own application log sub-object. The function group /WSOPT/APPLLOG of package /WSOPT/BASIS provides some useful wrappers around the standard SAP interfaces for the application log. With these wrappers, the standard integration handles all life cycle steps of the application log handling. These steps are: 1. Initialize the application log object and sub-object at begin of each event handler. The initialization is handled by function module /WSOPT/CREATE_LOG. The sub-object name is a mandatory parameter. (e. g. ENG or ORDER ). Optionally an object reference number for easier searching through the log can be added as second parameter. 2. The function module /WSOPT/ADD_MESSAGE_LOG is the main logging statement for adding new logging messages. The parameters include subobject name, message type, message ID, problem class, message number, optional message variables 1-4, save flag, commit flag. The optional parameters save and commit are usually set by standard /WSOPT/ coding. The save parameter closes the log and no more messages can be appended. An explicit COMMIT WORK may be performed outside of the log handler by other coding parts. The message text parameters may be arbitrary chosen from any message classes. 3. To ensure the successful writing of the log messages to the application log, the parameters save and commit should always be set to X (enabled) in the very last log message before ending the processing with an exception, e.g. by message type E. Process Infrastructure content The Process Infrastructure content needs to be deployed in the Enterprise Service Repository (ESR). It contains the design time objects necessary for the translation between the messages and data representations. The ESR content of the S/4HANA PI Adaptor contains two parts, which model the interfaces of the peer systems: CLICK_SO_SERVER 8.1.6: contains the WebService interfaces of the ClickSoftware Field Service Edge. SER.OPT.SUT CS-ERPADAPT216_700: contains the RFC interfaces of the WSOPT Add-On and the mappings to/from the peer interfaces The Enterprise Services Builder in SAP NetWeaver PI allows to enhance the predefined objects and to add customer specific integration scenarios. The recommended best practices are part of the Enterprise Services Enhancement Guide, which is available at the SAP Developer Network (link).

Ch 2 S/4HANA PI Adaptor architecture 14 In short the following steps are required to start customer development based on the delivered S/4HANA PI Adaptor for Field Service Edge content. 4. Create new customer software objects in the Software Catalog in the System Landscape Directory (SLD). 5. Link the customer software objects to the related SAP objects. 6. Assign the customer software component to the technical systems and business systems used in the integration 7. Import the customer software components into Enterprise Service Builder and create new namespaces inside them 8. Import the updated interfaces with additional data structures from S/4HANA and Field Service Edge Maintaining Software Catalog Entries in System Landscape Directory Create a new Product (i.e. Z_WSO), a new Product Version (i.e. Z_WSO_216), a new Software Component (i.e. Z_SER.OPT.SUT_CS-ERPADAPT) and a new Software Component Version (i.e. Z_SER.OPT.SUT_CS-ERPADAPT216) in the Software Catalog in System Landscape Directory. The Software Component Version (in short SWCV) should have a Build Time dependency on the original SWCV SER.OPT.SUT CS-ERPADAPT216_700. Similar to the first Software Component and the Software Component Version create another customer definition based on the SWCV for CLICK_SO_SERVER. Figure 1: SLD - Product definition with two units Figure 2: SLD - BuildTime dependency for SWCV Z_CLICK_SO_SERVER Assign the customer product and the SWCVs to the technical systems and the business systems in SLD to make them available for development (Enterprise Service Repository) and integration (Integration Directory). The next figure shows the assignment to the business system BS_ERP60.

Ch 2 S/4HANA PI Adaptor architecture 15 Figure 3: Assignment of installed products and software to a business system Exporting WebService interfaces in Field Service Edge After UDPs were added to the Field Service Edge Business objects, export the changed WebService interfaces for inbound direction from: http://fse_server/so/integrationservices/scheduleservice.svc?xsd=xsd0 http://fse_server/so/integrationservices/serviceoptimizationservice.svc?xsd=xsd0 Save each of them as an.xsd file 1. The definitions for outbound interfaces must be exported one-by-one after the selection of the properties to be transmitted in the outgoing message setup in the Field Service Edge Legacy Administration Tool. Use the button Copy XSD to Clipboard, paste the content into a plain text editor (i.e. notepad) and save the file. Figure 4: Field Service Edge Legacy Administration Tool - Outgoing message settings Working with Enterprise Service Builder The Enterprise Service Builder is the developer frontend to the Enterprise Service Repository in SAP PI. This tool is used for development of design time objects. The 1 Depending on the method used to save the content into the.xsd file, it might be necessary to remove the initial <?xml version="1.0" encoding="utf-8"?> tag.

Ch 2 S/4HANA PI Adaptor architecture 16 following steps describe a typical (minimalized) workflow for extending the delivered objects in customer namespace. Create a new SWCV in Enterprise Service Builder by importing the just created Software Component from SLD. Create a new unique Namespace in each of the imported SWCV. Example namespace names are HTTP://EXAMPLE.COM/WSO/ERP/PM and URN:EXAMPLE.COM/WSO/SO_SERVER. Do not include a version number in the namespace. Figure 5: Customer SWCV with local copies of design objects in PI ESR Import the changed structure(s) of RFC function module(s) into the Z_SER.OPT.SUT_CS-ERPADAPT216 namespace by using "Import of SAP Objects". Import new External Definitions and upload each of the saved *.xsd files into the Z_CLICK_SO_SERVER816 namespace. The file category of the external definition needs to be changed to xsd instead of the default value wsdl. Create a new inbound, synchronous Service Interface with roles Request, Response, and Fault for each Webservice message containing the new UDP. Copy the standard Message Mappings (request, response and fault) of each interface you want to change from the delivered basis objects to your custom Z_SER.OPT.SUT CS-ERPADAPT216 namespace. For each copied Message Mapping, you need to: Change the source interface of RFC Message to your enhanced RFC structure. Change the target interface of the External Message to your enhanced WebService Message. The three Message Mappings (request, response and fault) are linked together in the related Operation Mapping. Copy the appropriate Operation Mapping to your namespace and change the source operation and target operation within the definition. You must select Read Operations to update the Source Message and the Target Message in each of the Request, Response and Fault definitions. Afterwards the new matching Mapping Program can be selected.

Ch 2 S/4HANA PI Adaptor architecture 17 Figure 6: Workflow for changing an Operation Mapping After the above changes are done, the new mappings can be used in the PI runtime the Integration Directory for integration of business systems. If the default mappings were already in use, it is not possible to replace the referenced standard Operation Mapping in Integrated Configurations or Configuration Scenarios. Otherwise create an initial configuration with Integrated Configurations according to the chapter Technical Interface Description of the main S/4HANA PI Adaptor documentation.

Ch 3 Enhancements to the PM module 18 C H A P T E R 3 Enhancements to the PM module This chapter describes examples and possible enhancements to the order and assignment integrations which are bundled in the /WSOPT/PM package of the WSOPT Add-On. Using additional qrfc destinations In some cases it may be desired to split the background queue processing of orders into several independently configurable units to assign enough free resources to the processing of higher prioritized orders, which need immediate transfer to Field Service Edge Server. For this enhancement it is possible to use the implicit enhancement spot at the end of function module /WSOPT/C_GET_RFCDEST_PM to add additional logic to decide on which qrfc destination to use. The necessary order header information for additional decision making is initially retrieved in function module /WSOPT/C_ORDER_ UPDATE_BTE and should be available as long as all orders are processed by the beforementioned BTE or a compatible version of it. If this information is sufficient, it should be possible to change the queue determination without having to deviate too much from the standard. Please see the following screenshot for an example of how the enhanced module will look like. Figure 7: Function module with implicit enhancement at the end of the module

Ch 3 Enhancements to the PM module 19 Additional queue names cannot be added to the table /WSOPT/PM_DEST. The easiest way to add multiple additional destinations is to add a new configuration table in customer namespace or to work with numbered suffixes appended to the retrieved queue name. For consistent processing of all events on the order business object, the inbound events such as assignment updates and task status updates need to be considered as well. The default inbound handlers use the same function module to determine the queue name and should work without any additional changes. In cases where these handlers are replaced by custom ones, they need to be modified to match the outbound queue names. Extending the assignment integration The default integration for saving assignment start and finish time is using the restriction Start and End fields of an operation. In situations where these fields are already being used, it will be necessary to change their storage location inside the inbound assignment handlers. The complete processing flow of the inbound assignment events is depicted in Figure 20 in the appendix. The transfer of the inbound values into the operations is performed in the internal assignment handler module /WSOPT/C_ORDER_ASSIGNMENT_I. To change the storage location of the fields, the following steps will be required: 1. Create a new internal assignment handler module as replacement for /WSOPT/C_ORDER_ASSIGNMENT_I. This is the main place for this change. 2. Create a new qrfc background handler similar to /WSOPT/C_ORDER_ASSIGNMENT_UPD, which executes the new internal assignment handler. 3. Implement BAdI /WSOPT/PM_ASSIGNMENT_UPDATE, which starts the new qrfc background handler. Use a copy of the default fallback implementation /WSOPT/PM_ASSIGNMENT_DEFAULT as template. The following figure shows the relevant part of the ABAP coding, where the intermediate structures used for operation updates is setup with the time values (START_CONS, STRTIMCON, FIN_CONSTR, FINTIMCONS):

Ch 3 Enhancements to the PM module 20 Figure 8: Internal Assignment handler Status dependent integration of data on order update in Field Service Edge Especially in Edge Mobility integration scenarios it might be required to send additional data with the order update to SAP (e.g. data that was maintained on the mobile device by the mobile engineer after a certain progress was made on the task). A common example is to send additional notes or meter readings after the field job was marked complete. The recommended approach for this case consists of the following steps: 1. Model the outgoing message (i.e. TaskCompleted) in Field Service Edge Legacy Administration Tool and export its definition as.xsd file. 2. Create a matching inbound RFC module with subsequent handlers for processing the new task update event with the additional data from the received message. You can use the existing RFC module /WSOPT/C_PI_OPR_STATUS_UPD as a reference.

Ch 3 Enhancements to the PM module 21 1. Use the same naming scheme for orders as it is done by the general handler in the background task queue. The queue name is set by default to CS_SDL_ + <order number>. 2. Export the current order ID to memory id /WSOPT/PM if you want to prevent a back-fired update from S/4HANA to Field Service Edge. This flag is read in the handlers /WSOPT/C_ORDER_UPDATE_BTE and in /WSOPT/C_ASSET_UPDATE_BTE. This should be done before the order is updated, and it s important that it s done in the same process that will update the order. 3. Publish the new Field Service Edge Outbound message to ESR: 1. Import the new object definition of the outbound Field Service Edge WebService message from step 1 into the External Definitions of the local Software Component Version for Field Service Edge Server (e.g. Z_CLICK_SO_SERVER) in the Enterprise Service Builder. 2. Create a Service Definition analogous to TaskUpdate. 4. Publish the new RFC module to ESR: 1. Import the new object definition of the inbound RFC module from the development system into the Imported Objects of the local Software Component Version (e.g. Z_SER.OPT.SUT CS-ERPADAPT216_700) in the Enterprise Service Builder. 2. You need to create a new message mapping similar to message mapping TaskUpdate_To_WSOPT_C_PI_OPR_STATUS_UPD 3. You need to create a new operation mapping similar to operation mapping TaskUpdate_To_WSOPT_C_PI_OPR_STATUS_UPD. Extending the order integration in S/4HANA Filtering and modifying updates The integration offers a single configuration point for controlling the relevance of an order for the integration with Field Service Edge. The relevance check is executed in background task and the default handler uses the values maintained in table /WSOPT/C_OPRST, which consist of Order Type, Maintenance Planning Plant and Control key, to determine if an order should be processed by the integration logic or not. In case the standard criteria are not sufficient it is possible to implement a custom relevance check in the interface method /WSOPT/PM_ORDER_IF~ORDER_RELEVANT of Enhancement Spot /WSOPT/PM_ORDER. The relevance check is run in the default qrfc handler after several other handlers were already executed. The BTE event handlers /WSOPT/C_ORDER_UPDATE_BTE and /WSOPT/C_ASSET_UPDATE_BTE are earlier places to determine if the order is relevant for the initial processing. The BTE handlers define on very high level if the order will be processed by the integration at all. They should not be used for relevance criteria that can be changed easily, because at that point any update to already created tasks in Field Service Edge would be suppressed. The final place for modifying the default behavior is the interface method /WSOPT/PM_ORDER_IF~ORDER_UPDATE of Enhancement Spot /WSOPT/PM_ORDER. This can be used for operation level enhancements. The Field Service Edge Legacy Administration Tool allows it to create filtering criteria for outgoing messages to suppress their transmission to the configured integration system. A similar mechanism is not implemented in the standard feature set of the

Ch 3 Enhancements to the PM module 22 S/4HANA PI Adaptor. Therefore two possible mechanisms, which can be implemented in the customer system, will be outlined below. Extending the order relevance check for transmission to Field Service Edge As already written above, the order relevance is checked by the interface method /WSOPT/PM_ORDER_IF~ORDER_RELEVANT. One possible use case to change the default relevance criteria is to extend the relevance criteria by PM activity type. The following steps outline the steps necessary to implement such an extension. 1. Create a new database table for storing the enhanced relevance criteria. Add a new field named ILART for data element ILA to store the PM activity type (or other fields according to your project requirements). 1. Create a new maintenance view for the table in transaction SE54. The table can then be maintained in transaction SM30. 2. Create a new BAdI implementation (SE19) for interface method /WSOPT/PM_ORDER_IF~ORDER_RELEVANT from Enhancement Spot /WSOPT/PM_ORDER. The new implementation needs to use the table from step 1 to determine the order relevance. You should copy the original implementation and change it or just add the additional coding. 3. Once the implementation is marked active, the new implementation is immediately used instead of the default fall-back implementation. Status-dependent filtering of transmission on operation level The required functionality to suppress the transmission of operation updates for selected statuses can be implemented in method /WSOPT/PM_ORDER_IF~ORDER_UPDATE of Enhancement Spot /WSOPT/PM_ORDER. The standard implementation of method ORDER_UPDATE is only a wrapper for /WSOPT/C_PI_ORD_INT, which works on a list of operations. This list of operations can be modified by custom coding before being passed to the standard handler. Steps to be done for this enhancement: 1. Create a new BAdI implementation (SE19) for interface method /WSOPT/PM_ORDER_IF~ORDER_UPDATE from Enhancement Spot /WSOPT/PM_ORDER. 1. Remove the operations not relevant for transmission from the operations list. 2. Please consider to update the relationships between operations, if necessary. 3. Pass the processing to the standard /WSOPT/C_PI_ORD_INT function module or write your own transmission logic. Filtering of transmission for completed operations The filtering of completed operations might be necessary in cases where orders have a very long lifecycle. The information that an operation is completed should be send to Field Service Edge, but that also means that that task could get deleted by a Purge Agent. In that case it s not necessary to update that task in Field Service Edge ever again, because the work is done and we don t want the task to be re-created later on. The problem is that we cannot filter those via Field Service Edge relevance criteria, and filtering by Status is also not working, since we want to send one last update so that Field Service Edge gets the Status information.

Ch 3 Enhancements to the PM module 23 The architectural design of the WSOPT Add-On does not query the Field Service Edge system before order updates to compare the known operations and their data at each system. Therefore a temporary table must be introduced to store the last know status, which was transferred to Field Service Edge. Here s the proposed solution for that scenario: Implementing field level updates 1. Create a new table that is able to store the order and operation number and the status text. 2. Create a custom BTE function module (a copy of /WSOPT/C_ORDER_UPDATE_BTE or /WSOPT/C_ASSET_UPDATE_BTE) and add coding that will check the current operation status values and compare them to the value from the new table. If the status of all operations is the same as in that table and that status indicates that the operation is closed, don t call the queue module order_update_rfc. 3. If the status integration from Field Service Edge to SAP is enabled, those status updates should also update the table. There are two possibilities to achieve that goal: 1. Similar to the chapter Status dependent integration of data on order update in Field Service Edge, a new function module for incoming messages needs to be created and used instead of the standard one in order to update the operation status in the operation itself and the new table. 2. Alternatively with the creation of an implicit enhancement spot in function module /WSOPT/C_OPERATION_STATUS_UPD that would update the new status table after the operation was updated 4. Create a new BAdI implementation (SE19) for interface method /WSOPT/PM_ORDER_IF~ORDER_UPDATE from Enhancement Spot /WSOPT/PM_ORDER. 1. Remove the operations that have a status indicating that the operation is closed, if that status is already in the new table. 2. Please consider to update the relationships between operations, if necessary. 3. Change the status value of each operation in the table if necessary. 4. Pass the processing to the standard /WSOPT/C_PI_ORD_INT function module or write your own transmission logic. The general update mechanism used by the S/4HANA PI Adaptor is triggered by events on supported business objects and it performs its updates on the whole business object. For the order business object this results in updates containing all the fields for all operations mixed with their shared order header data. A common request in projects is to support field level updates. Such a change to the default integration has to deal with several additional challenges: 1. The event must be processed and all field changes must be recorded in a consistent way. 2. The data provided by the RFC modules must be tagged for change mode as: update (with or without value) and ignore. 3. The mappings in PI must be adjusted to support the modes update value, delete value and suppress tag.

Ch 3 Enhancements to the PM module 24 The following explanations deal with the above requirements. Data retrieval in S/4HANA The biggest challenge is the correct, complete and consistent determination of changed fields. Each order related event is first handled by the BTE handlers, which are parameterized with copies of the object before and after the event (before-image and after-image). However, it is possible that some of the changes were performed on related objects (for which no such before-image exists and the changes cannot be reconstructed). Therefore, it is essential for the implementation to define which fields need to be tracked for changes and how this tracking can be achieved. A list with tracked fields instead of the ignored fields is the recommended approach. Extra care must be taken when fields pointing to or referenced from other objects change, i.e. relationships and dependencies between operations. Suppressing such changes or deleting the references can be implemented only in limited scenarios. Data transfer to PI Each data field which is considered for being suppressed, must be tagged for the requested update mode, which is one of update, delete, suppress. This can be easily achieved by maintaining two structures or tables with the same field members: Structure values : contains the actual values in the fields Structure updates : contains a Boolean switch for each field in structure values, which determines if the field will be updated or not. Data mapping in PI Based on the data received in the source structure from the S/4HANA system a new mapping must be implemented, which outputs the target structure with filled tags, empty tags or suppressed tags. An example of field DATA within the structure TAG is shown in the following listing: <TAG><DATA>SOME VALUE</DATA></TAG> Complete tag for updating the field content <TAG><DATA/></TAG> Empty tag for deleting the field content <TAG></TAG> Suppressed tag for suppressing changes To achieve the target message use the following mapping in PI message mapping. /ns1:targetmessage/ns1:tag/ns1:data=ifwithoutelse(stringequals(/ns0:z_source _RFC/up/data, const(value=x)), /ns0:z_source_rfc/val/data, keepss=false) The graphical representation of the above pseudo mapping code is shown in Figure 9.

Ch 3 Enhancements to the PM module 25 Figure 9: Graphical representation of conditional data mapping Adding customer specific data to the order integration The general concept for adding customer specific data to the S/4HANA PI Adaptor was introduced in the S/4HANA PI Adaptor data structures chapter. This section outlines a generic example of how to add a customer field to the operation data into the S/4HANA PI Adaptor integration. It is assumed that the preparations in SAP PI ESR were already performed according to chapter Process Infrastructure content. For example purposes let s add a string type field named Z_CONTRACT_TYPE, which is populated by the ORDER_UPDATE enhancement spot. 1. Create a structure ZWSOPT_ORD with field Z_CONTRACT_TYPE of type CHAR30. 2. Append the new structure to /WSOPT/C_PI_OPERATION. 3. Create a new BAdI implementation (SE19) for interface method /WSOPT/PM_ORDER_IF~ORDER_UPDATE from Enhancement Spot /WSOPT/PM_ORDER. 1. Add the new logic to determine the contract type at the start of the method. 2. Include the original coding in /WSOPT/C_PI_ORD_INT for executing the actual data transfer, logging and error handling to SAP PI at the end. Alternatively it is possible to go without the standard coding and rewrite that part from scratch. 4. Add a ContractType UDP to the task object in the Field Service Edge Schema Editor and re-export the ScheduleService.svc WebService. 5. Import the changed variants of RFC /WSOPT/C_PI_ORDER_UPD and the XSD of ScheduleService.svc into the appropriate local Software Component Versions in ESR. Create a new Service Interface for ProcessTask respectively ProcessTaskEx. 6. Create copies of the Message and Operation Mappings in your local SWCV and exchange the references to the new messages. Link the new source field in /WSOPT/C_PI_ORDER_UPD to the new target field in ProcessTask respectively ProcessTaskEx.

Ch 3 Enhancements to the PM module 26 Figure 10: Example of order update enhancement objects in ESR

Ch 4 Enhancements to the HR module 27 C H A P T E R 4 Enhancements to the HR module This chapter describes examples and possible enhancements to the engineer and engineer related integrations which are bundled in the /WSOPT/HR package of the WSOPT Add-On. Extending the engineer relevance check for transmission to Field Service Edge The engineer relevance is checked by the interface method /WSOPT/HR_ENGINEER_RELEVANT_IF~ENGINEER_RELEVANT in Enhancement Spot /WSOPT/HR_ENGINEER. One possible use case to change the default relevance criteria is to replace the default relevance criteria by a check against a custom table with explicit HR work center names. Another case might be to use the default table, but to add an option to (temporarily) disable the relevance of selected engineers by a status flag in the engineer data. The following steps outline the steps necessary to implement both extensions. Use case 1: 1. Create a new database table for storing the new relevance criteria. Add a new CHAR8 field named ARBPL to store the HR work center (or other fields according to your project requirements). 1. Create a new maintenance view for the table in transaction SE54. The table can then be maintained in transaction SM30. 2. Create a new BAdI implementation (SE19) for interface method /WSOPT/HR_ENGINEER_RELEVANT_IF~ENGINEER_RELEVANT from Enhancement Spot /WSOPT/HR_ENGINEER. The new implementation needs to use the table from step 1 to determine the order relevance. You should copy the original implementation and add your logic or change the old logic accordingly. 3. Once the implementation is marked active, the new implementation is immediately used instead of the default fall-back implementation. Use case 2: 1. Add an implicit enhancement at the end of interface method /WSOPT/HR_ENGINEER_RELEVANT_IF~ENGINEER_RELEVANT from Enhancement Spot /WSOPT/HR_ENGINEER. The enhancement should contain the logic to read the required flag (from an enhanced SAP infotype or a customer infotype) to disable the engineer relevance by setting the internal variable RELEVANT to an empty value.