Execution Manager with Payload

[ab13]

SuccessFactors Execution Manager tool

As an integration consultant, it might be asked how business users can get a view of interfaces status and check errors so they can take action.

If you're working in a SuccessFactors landscape, Execution Manager tool can be a solution for your business users who don't necessarily have access to SAP Cloud integration (aka CPI or SCI) instance and would appreciate not looking at the rather technical monitoring logs.

Let's make use of the SuccessFactors OData adapter to post events to EMEvent entity. You can certainly use HTTP adapter with JSON payload however, it would be tricky how to update your integration flow once SAP Basic Authentication is retired in 2023. Meanwhile, SF OData adapter can take care of the new OAuth authentication already.

It is helpful to have read this blog post by Gurdev S. where he has given you an overview of Execution Manager and how to quickly use it using JSON payload/HTTP adapter. My post deviates and dives a little deeper into other options within EMEvent / Execution Manager:

• 
  
  
  
  • usage SF OData adapter (using XML payload)
  
  
  • how to add payload for the event
  
  
  • download the event log
  
  
  • email notification
  
  
  
  

Add EMEvent upserts in your Integration Flows

a. Basic Events and Process State

First, let's establish what events we're going to post. Gurdev S. has beautifully outlined this in his blog post and I'll include it here with a focus on 3 basic patterns.

EMEventType	Final Process State
event 1- START event 2- END	COMPLETED SUCCESSFULLY
event 1- START event 2- ERROR event 3- END	COMPLETED WITH ERRORS
event 1- START event 2- FAILED	FAILED

Table 1: EMEventTypes

*Note: EMEventType INFO does not work any longer. You can use SUMMARY_SO_FAR as a replacement. When using SUMMARY_SO_FAR, be aware there's a button in the main screen specifically to show the information you post. Probably useful if you want to give updates such as how many records have been processed or number of errors so far.

b. Essential EMEvent Information

How do you make entries in Execution Manager ? What makes each run unique ?

These fields are what creates each entry in the table in the tool. Check the screenshot below with blue and green marks where each one is found in the tool UI.

EMEvent field	Map to	Remarks
Process Definition Identifier (Id)	Iflow ID (simple expression) camelId	This is the technical name of your iflow. Needs to be unique. You can filter using this in the main screen of the tool as dropdown. Check out the groovy script to get the value of camelId simple expression. It is called in the message mapping in the iflow sample in the link at the end of this blog post.
Process Definition Name	Property iFlowName	I suggest put an externalized property in your iflow for this. Can be useful if you want to add distinguishing feature such as specific payroll group if you're running an iflow with process direct and it will be called for each payroll group. Otherwise, you can simple copy the value of the Process Def Id.
Process Instance Identifier (Id)	Header SAP_MessageProcessingLogID	Needs to be unique to identify each run of your iflow.
Process Instance Name	Property fileName	This can be a filename or any data you find useful that could be filtered on in the Execution Manager tool. For example, it would be easy to check when was a certain file processed.

Table 2: EMEvent fields

Screenshot 1: Execution Manager Screens -

Main screen + Detail screen

c. Creating Events

Let's have a look at the detail screen where we have variations in the data we set. I've highlighted some items to easily see which iflow properties match the UI elements you see in the EM tool.

Screenshot 2: Execution Manager Detail screen

Screenshot 3: Execution Manager Detail with Payload

Screenshot 4: Execution Manager Detail without Payload

The colors highlighted in the screenshots above are being filled by the properties we set in the Iflow below.

c1. START / END - with payload

I imagine using payload if the data is not sensitive (can't imagine saving payslips or any PII data). But if you're going to add the payload to make it available in Execution Manager (see Screenshot 3 above which has the extra Download Report button), then add extra properties to be used later on in our message mapping to EMEvent entity).

It might make sense adding it to the start and end events (Event Type) -- START to show the file contents or initial data input and at the END, to show the data with messages you've collected after processing all the data.

Surely, there might be other ways of saving the payload (using persistence step or the adding to CPI logs) but if you're using EM, then you can take advantage of this feature.

Properties:

• hasEventPayload - Yes/No flag


• eventPayloadFileName - filename of the payload when downloaded in Execution Manager tool
  
  
  
  • This is optional: you can delete this and also disable in the message mapping; it means that the file will have a generic name like Payload.txt or Payload.html when downloaded depending on the eventPayloadType we set.
  
  
  • If you set this, it will follow the filetype of the eventPayloadFilename. For example, if you set it as Test.html and put eventPayloadType as XML, it will still be downloaded as Test.html. See Screenshot 3 Download Report button in yellow highlight.
  
  
  
  


• eventPayloadType - required field in the API. I have tried the following types:
  
  
  
  • TEXT
  
  
  • HTML
  
  
  • XML
  
  
  • etc.
  
  
  
  


• eventPayload - required field in the API
  
  
  
  • This is the base64-encoded payload; Use Base64 Encoder step in CPI.
  
  
  
  

Screenshot 5: Set Event with Payload (START event type)

Screenshot 6: Set Event with Payload (END event type)

c2. ERROR / FAILED - without payload

If you won't add any payload, just set hasEventPayload to No. This property will be checked later on in the Local Integration Process.

When do you use FAILED event? You can use it in your exception subprocess. So if you encounter an exception, it shows as Failed in the EM tool. Notice I've put the ${exception.message} in Screenshot 8 to record the exception in the eventAttributeValue property and should show up in Screenshots 3 and 4 in orange.

Screenshot 7: Set Event without Payload (ERROR event type)

Screenshot 8: Set Event without Payload (FAILED event type)

Screenshots 5, 6, 7 and 8 are your Set Event iflow steps as seen below in Screenshots 9 and 10.

If you're adding a payload in your event, make sure it is base64-encoded. You can use the Base64 Encoder step. Of course, if your actual payload has arrived already base64-encoded, then skip encoding it again.

Update EMgr step is a process call to map your properties (from Set Event step) to the API EMEvent fields and upsert to SuccessFactors. We'll show that in the next section.

Screenshot 9: Iflow steps - with payload

Screenshot 10: Iflow steps - without payload

 

d. Update Execution Manager Local Integration Process

How do we update Execution Manager tool ? First, we map our properties to the EMEvent entity and then, upsert to SuccessFactors.

The hasEventPayload property is checked by the router in this local integration process.

This local integration process is called by the Process Call step we named above as Update EMgr. See screenshots 9 and 10.

Screenshot 11: Update Execution Manager Local Integration Process

 

Let's look at the message mapping.

The properties we've set in the Set Event (Content Modifier) steps are used in this Message Mapping. Colors match the previous screenshots for easy reference.

For the Message Mapping without payload, it is a copy of this mapping but the eventPayload node is disabled.

Screenshot 12: Message Mapping (with Payload)

Screenshot 13: SuccessFactors EMEvent Query

Note: Remove the EMEvent id field when you're selecting the fields. There's a warning but it is possible to upsert properly without it.

Here's the list of fields in the query:

eventDescription,eventName,eventTime,eventType,eventAttributes/name,eventAttributes/value,process/processDefinitionId,process/processInstanceId,process/processType,process/processDefinitionName,process/processInstanceName,eventPayload/fileName,eventPayload/fileType,eventPayload/mimeType,eventPayload/payload,eventPayload/type

e. Download Event Log

Can you save the logs to analyze later ? Yes.

There's a download button and it will save a csv file for you (which you can open with Excel).

You may notice that the Event payload is not downloaded with the Event log CSV. So it might be cumbersome if you attach a payload for each event and download each event payload one by one.

Screenshot 14: Download Event Log

Screenshot 15: Event Log (CSV)

 

f. Multiple Event Attributes

You can add several Event Attributes and it will show something in the UI such as the one below. I discovered these a little while ago by looking at the other integrations (Scheduled Jobs in this matter).

When the event log is downloaded, it might take a few more formatting actions to get all the attributes separated. Plus, you need a little bit more effort in adding multiple nodes in your iflow for each event attribute. The pattern I have shown in the previous screenshots only caters to 1 set per event, which is enough for the moment.

Screenshot 16: Multiple Event Attributes

Screenshot 17: Event Log - Multiple Event Attributes

g. Email Notifications

You can also add email notifications, for example, so you can be notified if there was an interface run with errors. The email would be simple and straightforward (Screenshot 19) and clicking on the link will direct you to the Event Details screen like Screenshot 14.

Screenshot 18: Execution Manager - Manage Notification

 

Screenshot 19: Email notification sample

Next steps..

I hope this short blog post would help you enrich your Execution Manager / EMEvent posts.

Here's a link where you can download the sample iflow that has that message mappings and events.

What I would like you to try to explore the tool and API a little bit more:

• use notifications in the Manage Notification tab and have an simple email notification sent to your nominated email address


• post using Event Types: SUMMARY_SO_FAR and WARNING


• try the eventPayload mimeType and check what it is for

I would love to hear from you and what other features you have explored for this tool. Any feedback or thoughts are welcome as I can continue to improve the blog post (and future posts!). Thanks!