SAP SPM Incentive Management – Advanced Workflow White Paper – Web Actions

[raulcorrales]

Introduction

This document explains Web Actions scripts. Workflow provides Web Action scripts that enable third parties to collaborate with Workflow by sending data in JSON or XML formats. Workflow can unpack the data received with the Web Action script.

This document illustrates how an external application can change the status of a case and close it.

Assumptions

This document assumes that you have prior knowledge and experience with the following SAP SPM applications:

• IAS Administration
• Advanced Workflow

You will need to work with your team to get Administration permissions to these 2 applications on your GCP Tenant.

Also, you need to know the mechanisms of how to call Workflow REST APIs and for this, you will need to use a REST client to execute the APIs.

The examples provided in this document use 'Bruno' as the client.

Description

Web Action is a script type which allows your third-party applications to collaborate with Workflow by sending data in JSON / XML formats. In the Web Action script, Workflow application can unpack the data received and then your script can execute some custom code.

A use case, for example, could be performing external background checks. In an onboarding workflow for new producers, you might want to accept requests only if the background check is successful. Once a new onboarding case is created in your workflow, the case could remain in a temporary status while a request is sent to an external application to initiate the background check. This process may take a few days. When the background check is completed, the third-party application can send the results to Workflow. These results can then be processed by a Workflow Web Action script, where you can implement the necessary logic to move the case to the next workflow status if the background check is positive, or to close and reject the case if the background check is negative.

This document shows another example, a simple example to receive a case key to close the case and move it to “Closed” status.

Pros / Cons

With Web Action scripts, you can interact with third-party applications from within our Workflow application and implement complex business logic directly in your scripts, keeping your business logic centralized in our Workflow Groovy scripts.

This capability is incredibly powerful, providing you with a great deal of flexibility.

It allows you to seamlessly integrate external systems, automate processes, and ensure consistency across your workflows.

Additionally, you can handle advanced scenarios such as validating external data, triggering actions in other systems, or dynamically updating workflow statuses based on external inputs, all while maintaining a single source of truth for your business logic.

Code

This section provides an example of how Web Actions work.

First, we will demonstrate a Workflow Groovy script of the Web Action type that receives a JSON package containing the case key of the case we want to close and move to “Closed” status.

Next, we will show how to send the JSON package and execute the Web Action script via API.

1. Create Web Action Script:

From Workflow, go to Setup > DEVELOPMENT > Scripts and create a new script of "Web Action" Type with name “Close Case Web Action” (system Id = close_case_web_action):

Next, copy and paste the following code to your script:

import groovy.json.JsonSlurper;

/*
This script receives a JSON from an external application with the case key that we want to close 

Example:

{ 
	“cases”:
	[ 
		{ 
			“case_key”:“RMA-A-123”
		}
	] 
}
*/

logger.debug("Test Web Action - START")

// external application defines format expected by Workflow 

response.setContentType("application/json")  

def slurper = new JsonSlurper() 
def returnStatus = ""

try {

  // gets JSON sent from an external application

  def text = request.getBody() 
  
  // Parse a text representation of a JSON data structure

  def json = slurper.parseText(text) 
  
  // Get case key we want to close
  
  def caseKey = json.cases[0].case_key
  
  logger.debug("CaseKey: " + caseKey)
  
  // get case key from parsed JSON
  
  def currentCase = resp.getCase(caseKey) 
  
  // case will end up in this status
  
  def status = resp.getStatus('closed') 

  // close case and move case to status closed  

  currentCase.setStatus(status) 
  currentCase.close()
  resp.update(currentCase)
  
  // Set OK response message
  
  returnStatus = """
  { 
  	"status"  : "OK",
	"message" : "Cases closed successfully"
  }"""

} catch(e) {

  logger.error(e)
  
  // Set Error response message
  
  returnStatus = """
  { 
  	"status"  : "FAILED",
	"message" : "${e.getMessage()}"
  }"""
  
}

// sends response message to the external application in JSON format

response.writer.write(groovy.json.JsonOutput.toJson(returnStatus))
response.writer.close()

As you can see, this code gets the case key in JSON format, the case is closed with Closed status, and it returns a success or error response also in JSON format.

To be able to execute this script, you need to call a Workflow API what is explained on the next section.

2. Call Web Action from an External Application:

For this example, we will use Bruno, a REST API client.

As with all Workflow APIs, the first step is to authenticate using the mechanism outlined in the Workflow REST API documentation.

NOTE: For a more detailed explanation about the authentication process, you can refer to the SAP Blog created by the Advanced Workflow Virtual Practice group, which provides an in-depth guide on authentication:

Call Workflow REST APIs in GCP 

As explained before, the Web Action script is expecting to receive the data in JSON format with the case key of the case that we want to close with Closed status.

The following JSON code is an example of what the external system should send for this example:

{ 
   “cases”:
   [ 
      { 
         “case_key” : “RMA-A-2”
      }
   ] 
}

To run this example, please verify your Workflow tenant and copy the case key of an existing case (i.e.: RAM-SAP-2):

 Authentication:

To run the Workflow API, you first need to execute the Authentication REST API to obtain the access token required for Workflow API authentication.

NOTE: To run the Workflow APIs, you must first complete the necessary configuration. Please visit Additional Resources section, where you will find a link to the How to Call Workflow REST APIs white paper.

Before you begin, ensure you have the following information available:

Field	Example
Workflow application internal host name	xg3-wf-sbox.workflow.cloud.sap
IAS host name	azr7m8zct.accounts.ondemand.com
Client ID	dddde129-de6e-47c1-95fc-646b38259a7a
Client Secret	XXXXXXXXXXXXXXXXXXXXXXXXXXXX
Tenant	g0cb

You need to obtain a JWT access token using your Client ID and Client Secret and once you have the token, you can configure Bearer authentication to call the Workflow API.

To get the JWT access token, send a POST request to https://<sap_ias_hostname>/oauth2/token

You need to use Basic Authorization passing these 2 values:

Username	[Client ID]
Password	[Client Secret]

With these 2 Header parameters:

grant_type	client_credentials
Domain	[Tenant]

Bruno Sample:

Authorization:

Header Params:

Response:

Now that you have the JWT access token you can call the Workflow API.

3. Call Web Action:

The URL that calls the Web Action must be received in the following format:

https://[WORKFLOW_URL]/wpm/mt/[TENANT]/[DATA_FORMAT]/[SCRIPT_SYSTEM_ID]?

In this example, the external application sends the following URL:

https://xg3-wf-sbox.workflow.cloud.sap/wpm/mt/g0cb/json/close_case_web_action?

The URL contains the following example values:

Workflow URL	xg3-wf-sbox.workflow.cloud.sap
Tenant	g0cb
File Format	json
Web Action Script System Id	close_case_web_action

After obtaining the Access Token (as explained before), you can use it to call the Workflow REST API. Include the token in your API header using Bearer authentication.

When calling the Workflow API you need to use the following Header parameters:

Content-Type	application/json
domain	[Tenant]
Authorization	Bearer [Access Token]

Finally, you will need to pass the JSON data in your API body request.

Bruno Sample:

Header Params:

Body:

Response:

After the Web Action script is executed the case in Workflow is closed with Closed status as expected:

Conclusion

After reading this article you can call Web Services from external third-party application to interact with Advanced Workflow application.

Additional Resources

Advanced Workflow online documentation – Web Actions:

Web Actions Help

Bruno online documentation:

What is Bruno? – Bruno Docs

How to Call Workflow REST APIs:

Call Workflow REST APIs in GCP

[Sarfaraz_Shaikh]

I’m interested in SAP Advanced Workflow, but I can’t find structured learning materials beyond the SAP Help portal. The SAP Learning Hub portal doesn’t offer self-learning materials yet. Can you share any self-learning materials or let me know when they’ll be available on the SAP Learning Hub portal?