SAP SucessFactors Extension Application - "Run Smooth"

Description:

Run Smooth is a reference application which showcases how to build an event driven extensions for SAP SuccessFactors using the capabilities provided by SAP BTP Extension Suite. This solution is developed by extending the Employee Central module of SAP SuccessFactors to build an event driven application.

This application showcases:

1. Capabilities of SAP BTP Extension Suite
2. Building application on SAP BTP using SAP Cloud Application Programming Model(CAP)
3. Building and Event driven extension application using SAP CP Enterprise Messaging
4. Consuming REST API's from SAP SuccessFactors using SAP CP Destination Service
5. SCI(IAS) Tenant integration with SF

Business Scenario:

In this reference application called as Run Smooth a business scenario is used to showcase the technology components. A Manager maintains in the Run Smooth application the staffing details of all the projects to which the employees reporting to him are contributing to. He can create project and assign employees to the projects. An employee contributing to a project might decide to leave the team/ company. When this happens, the manager gets a notification with the projects that the employee is working on and the skillsets of the employee. This information can be used by manager to find/hire a replacement for employee and assign the projects.

Features:

• Create Projects
• Assign Employees
• View the list of projects, employees working on the projects.
• Get notification when an employee is leaving the team with the consolidated report on the skills of the employee.

Architecture

Solution Diagram

The Run Smooth application is developed using SAP Cloud Application programming Model (CAP) and runs on the SAP BTP, Cloud Foundry Environment. It consumes platform services like Enterprise Messaging, SAP HANA and Destination. The events generated in SuccessFactors are inserted into the Enterprise messaging queue. The application running in Cloud Foundry polls the queue for these messages and inserts them into the HANA database. The run smooth application also makes calls to SF OData APIs to get SF data.

Note: SAP fiori elements floorplans for OData V4 is in Lab preview and would be GA later this year.

Requirements

• Node js
• SuccessFactors test or demo instance.

Note: Please do not try running this application against a SuccessFactors productive instance as it involves triggering a Termination Event from SuccessFactors.

• Cloud Foundry Command Line Interface (CLI)
• To build the multi target application, we need the Cloud MTA Build tool, download the tool from here
• For Windows system, install 'MAKE' from https://sap.github.io/cloud-mta-build-tool/makefile/

Note: @sap Node.js packages have moved from https://npm.sap.com to the default registry https://registry.npmjs.org. If sap-registry is set in your system please delete by using below command.

`npm config delete "@sap:registry"`

Note: Minimum version to run the application is CDS : 4.x.x

• Install the following:
  1. cds - npm install -g @sap/cds npm install -g @sap/cds-dk
  2. multiapps plugin - cf install-plugin multiapps
  3. mbt - npm install -g mbt

Configuration

Step 1: Configure trust between SF and SAP CP using Extension Suite

Follow steps 1, 2 and 4 from this document to set up trust and destination to access SuccessFactors system using Extension Suite.

Ignore step 3 in the document as the service instance creation is automatically done when the application is deployed as MTA.

Step 2: Download the EDMX files

1. Open https://api.sap.com/ and login to the same
2. In the Search bar, search for "External User".
3. Click on the External User API from SAP SuccessFactors
4. Click on Details
5. Click on Download Specifications
6. Choose EDMX. The edmx file is now saved in the local machine
7. Similarly download

• User Management API from SAP SuccessFactors
• Skills Management API from SAP SuccessFactors

Step 3: Project Configuration

1. Clone this repository
2. Import the downloaded EDMX files using the command cds import <filename>.edmx
3. Use the above command to import all the edmx files
4. Open mta.yaml
5. Go to the section Success Factors Extensibility Service and modify the SuccessFactors System name as per the name given while registering the System in previous step.
6. Open the package.json file and add the below credentials section to all the imported edmx files

   "FoundationPlatformPLT": {
      "kind": "odata-v2",
      "model": "srv/external/FoundationPlatformPLT",
      "credentials": {
        "destination": "sfextension-service",
        "path": "/odata/v2",
        "requestTimeout": 18000000
      }
    },
    "PLTUserManagement": {
      "kind": "odata-v2",
      "model": "srv/external/PLTUserManagement",
      "credentials": {
        "destination": "sfextension-service",
        "path": "/odata/v2",
        "requestTimeout": 18000000
      }
    },
    "ECSkillsManagement": {
      "kind": "odata-v2",
      "model": "srv/external/ECSkillsManagement",
      "credentials": {
        "destination": "sfextension-service",
        "path": "/odata/v2",
        "requestTimeout": 18000000
      }
    }
   

7. Go to the section Enterprise Messaging Service
8. Check in your CF account that "default" service plan is available for Enterprise Messaging Service.
9. Modify "emname": "<yourmessageclientname>","namespace": "<yourorgname>/<yourmessageclientname>/<uniqueID>" with necessary details in the “enterprisemessage.json” file.

The <yourmessageclientname> and <uniqueID> can be any random unique identifier. <yourorgname> would be your org name without '-' or any special character. Please make sure that namespace does not exceed 24 characters. For more details regarding syntax, size and characters allowed in namespace are mentioned here

10. Check if the Cloud Foundry account you will be deploying the application has the following entitlements:

Service	Plan	Number of Instances
Destination	lite	1
Enterprise Messaging	default	1
SAP HANA Schemas & HDI Containers	hdi-shared	1
SAP SuccessFactors Extensibility	api-access	1
SAP Hana Service	64standard	1
SAP HANA Cloud	Hana	1
Application Runtime	memory	3
Html5 Applications	app-host	2
Launchpad Service	Standard	1

It is not necessary to have entitlements for both SAP HANA Service and SAP HANA Cloud. Either one of the service instances can be used for deploying the application.

1. Subscribe to 'Launchpad Service' from Subaccount > Subscriptions.

Assign Rolee Launchpad_Admin for Lunchpad service from trust configuration to your user.

1. There are two options to continue:

option 1: Create SAP HANA Service instance with plan 64standard as described here The application is configured for SAP HANA Cloud Service instance. Remove the following snippet from package.json to adapt it to SAP HANA Service instance.

"hana": {
   "deploy-format": "hdbtable"
},

option 2: Create SAP HANA Cloud service instance with plan hana as described here

If there are multiple instances of SAP HANA Service in the space where you plan to deploy this application, please modify the mta.yaml as shown below. Replace <database_guid> with the id of the database you would like to bind the application with :

# Hana HDI Container
 - name: cloud-sf-extension-cap-sample-db-hdi-container
   type: com.sap.xs.hdi-container
   parameters:
    service: hana
    service-plan: hdi-shared
    config:
      database_id: <database_guid>
   properties:
     hdi-container-name: '${service-name}'

Step 4: Deploy the reference application

If the application is to be deployed without portal service, please copy mta without portal service and replace the content of mta.yaml file with it.

1. Build the application mbt build -p=cf

2. Login to Cloud Foundry by typing the below commands on command prompt

   cf api <api>
   cf login -u <username> -p <password>
   

   api - URL of the Cloud Foundry landscape that you are trying to connect to.

   Select the org and space when prompted to. For more information on the same refer link.

3. Deploy the application

Navigate to mta_archives folder and run the below command from CLI

cf deploy cloud-sf-extension-cap-sample_0.0.1.mtar

In case you need to deploy the application again, delete the sfextension-service instance and then deploy.

Step 5: Integrate the Applicaion to Success Factors Home Page

1. Login to SF demo instance with sfadmin user.

2. Search and select Manage Home Page.

3. Click on Add Custom Tile.

4. Enter the Tile Name as Run Smooth and Click on Step2.

5. Enter the title as Run Smoothand, Subtitle as SAP CP SFSF Extension Sample App add an icon to your tile and Click on Step3.

6. Enter the Target as URL, check Open Link in New Window/Tab, add the approuter URL to URL and then Click on Step4.

7. Click on Save.

8. Navigate back to Home Page.

9. We can see the newly created Run Smooth tile in the Home Page.

Step 6: Enterprise Messaging Application

1. Follow the steps here to subscribe to the Enterprise Messaging Business Application
2. Follow the steps here to add the necessary roles to the user to access the Enterprise Messaging Business Application
3. Open your global account, then your subaccount.
4. In the left pane, choose Subscriptions.
5. Choose Enterprise Messaging and click on Go to Application link (after the subscription is activated).
6. In the application, choose the messaging client (specified in the Project Configuration>Step 2.5) created when the application is deployed.
7. Go to the tab Queue.
8. From the table, click on Icon for 'Subscription' (under Actions) for the Queue created when the application was deployed.
9. From the pop-up window, please note the topic name for future reference (Step 5.5.8)
10. Create Service Keys for Enterprise Messaging Service by following steps here. Note down the client id, client secret, Token URL and Base URL from the service key which is shown as a json.

Step 7: Setting up SuccessFactors system

In this step, you will configure the successFactors system to send message to the Enterprise Messaging service on Cloud platform.

1. Login to the sf demo instance.

   username: sfadmin password: <It will be provided to you in the mail that you receive on requesting for demo instance. >

2. Setting Outbound OAuth Configurations. In this step, the credentials required to send messages to the Enterprise Messaging service are set.

   1. In the demo instance search bar, search for Integration center

   2. Select Security center

   3. Select Outbound OAuth Configurations

   4. Click on Add to create new OAuth configuration

   5. Enter the below detail:

      OAuth Type: OAuth 2.0

      Grant Type: Client_Credentials

      Client ID, Client Secret, Token URL: you can get these details from the service key of the enterprise message service instance you created in Step 5. If there is no existing service key, please create it in the Cloud Platform cockpit.

      Add Custom Header Parameters.

      Add new row: key=x-qos. Value =1

3. Creating outbound integration. An integration specifies the endpoint to which a message should be send along with the content of the message.

   1. Navigate to integration center.

   2. Select My Integrations

   3. Select Create > More Integration Types

   4. Select the below options and click on Create:

      Trigger type: Intelligent service

      Destination type: REST

      Format: JSON

   

4. Search for the Intelligent Service Employment Termination. Select it and click on Select button.

5. Provide details for the integration.

   1. Enter name for the integration and click next

   2. In Configure Fields tab, Click + button. Insert sibling elements

   3. Select the created element and set label as 'employeeId'

   4. Click on Set as Associated field button. Select entity tree view. Select User ID. Click on 'Change Association to User Id'

   5. Similarly add new sibling for managerId and associate it with Supervisor id.

   6. Add new sibling element message with default value as 'Resigned'. Click Next

   7. Keep the default settings for Response field, Filter tabs. Click Next

   8. Edit the Destination Settings with the following details:

      REST API URL: give the Base URL of the queue which was copied from Enterprise Message Service Key in step 4.10 E.g For Europe Region Account it could be https://enterprise-messaging-pubsub.cfapps.eu10.hana.ondemand.com/messagingrest/v1/topics/<topicName>/messages

      For , use the topic name copied in Step 4.9. Note that the topic name must be double encoded.

      For example, if your topic name is sfem/emm/1909/sfemessage, then the / should be replaced with %252F. The resultant topic name will be sfem%252Femm%252F1909%252Fsfemessage.

      Authentication type: OAuth

      OAuth Configuration: Select the configuration created in Step 2 above on Setting Outbound OAuth Configurations.

      

   9. Click on Save

   10. In Review and Run tab - click on Run now

6. Configuring the event flow. This step ensures that when the event is triggered, the integration created in the above step is run.

7. Search for intelligent services center in the search bar.

8. Select Employment termination event

9. Add integration for the existing flow:

   • Click on Integration under Activities. (on the right-hand side corner)
   • Select the Integration created in the previous step. Click on Add integration.
   • Change the 'Timing' of the Integration to 'When the event is published' and save the flow (Actions > Save Flow).

Step 8: Setup your own IAS tenant for authentication [Optional]

Configure IAS Tenant

Demo Script

1. Go to Instance and subscriptions and open Launchpad Service.
2. Open the Launchpad Site created there.
3. Launch the URL and login as dleal(David Leal)

You can choose any employee who is a Manager.

5. If you have integrated your app into SuccessFactors, open your tile from SuccessFactors home page.

6. Click on Project Details tile

7. Click on a Project from the list.

8. Click on Edit button

9. Click on Create Button.

10. Click the Drop-Down

11. All employees reporting to David Leal is displayed.

12. Select a employee and assign them to projects. E.g Simon Rampal(srampal)

13. Login to SF demo instance with sfadmin user.

14. Search for Employee David Leal (dleal) in the Employee Directory

15. Select Employee David Leal

16. Click on Actions button and Select Org Chart

17. Choose an employee who is reporting to 'David Leal e.g Simon Rampal(srampal) and assigned to the project in step 8

18. Click on Take Actions button and Select Termination

19. Set values for

    • Termination Date (Recommended to use a future date. For example, a date one week from the current date)
    • Termination Reason - Early Retirement
    • Ok to Rehire - Yes
    • Regret Termination - Yes

20. Click on Save.

21. In the window Please confirm your request, click on the 'Show workflow participants'.

22. Workflow participants would be shown as 1. Paul Atkins (Production Director); 2. Tessa Walker (HR Business Partner Global), Christine Dolan (Chief Human Resources Officer)

This means that Paul Atkins and Tessa Walker (or Christine Dolan) must approve this request to proceed.

21. Click on Confirm button

22. Use Proxy Now functionality and Select Target User as Paul Atkins(patkins)

23. In the Home page of Paul Atkins click on tile Approve Requests

24. Click on Approve button for the request for approval of Early Retirement of Simon Rampal

25. Use Proxy Now functionality and Select Target User as Tessa Walker(twalker)

26. In the Home page of Tessa Walker click on tile Approve Requests

27. Click on Approve button for the request for approval of Early Retirement of Simon Rampal

28. Open the Web Application UI for Run Smooth application in browser.

29. Login with user David Leal (dleal).

30. Click on notifications tile from the Launchpad Site.

31. Notification will be displayed regarding Resignation of Simpon Rampal along with his Skillset.

Known Issues

How to Obtain Support

In case you find a bug, or you need additional support, please open an issue here in GitHub.

License

Copyright (c) 2019 SAP SE or an SAP affiliate company. All rights reserved. This project is licensed under the Apache Software License, version 2.0 except as noted otherwise in the LICENSE file.