Implementation Design Principles – Best Practices using SAP SuccessFactors APIs for Custom Integrations
We all have personal and work-related goals. One of my goals for this year is to write more API related blog posts. So far I was helping our partners with questions in the SAP SuccessFactors Partner Delivery Community (PDC). But I thought it would be better to write about best practices for using SuccessFactors APIs before people start struggling. This would increase the chance that people will find those blog posts before they face challenges. Besides, it will also enable them to find them in the same place where they go for all other kind of questions, at google.
We started already last year to collect a lot of API best practices in one of our Implementation Design Principles documents (IDPs). In my future blog posts I want to focus on specific smaller problems. I want to explain the requirements and use cases behind them before I go into the architectures of possible solutions. Finally, I want to give detailed examples to learn and copy from.
I get my inspiration for the content I create from the interaction I have in the partner community, IDP workshops, webinars and meetings. I met in the past years a lot of talented people in the SAP SuccessFactors partner space. Some being beginners, some being super experts already. I like to thank our partners for their active engagement with our Product Advisory and Partner Success team at SAP SuccessFactors. The questions, the insights, the challenges, the solutions and the workarounds you share with us are an extreme valuable source. So, don’t stop and let your questions and ideas coming!
As a start I like to mention in this blog post the most important resources every partner must be aware of. They are essential when building custom integrations with SuccessFactors APIs.
Discover available SuccessFactors APIs
The first step is of course to know what APIs are available and if they cover the requirements of a integration or extensions a partner wants to build. The best entry point for this is our SAP API Business Hub. Here you will find most of the SAP SuccessFactors APIs. You will get here the API specification, a link to the documentation and the capability to test the APIs. You can test the APIs either in a Sandbox provided by SAP or in your own SAP SuccessFactors tenant. There is also the possibility to get code snippets for API calls or to get information to call the API from your favorite test client such as Postman. This video from Philip Mugglestone demonstrates this using the SAP SuccessFactors candidate API.
The API Business Hub is growing every day with new APIs from SAP and our Partners. The SAP SuccessFactors OData APIs are also available in the SAP SuccessFactors HXM Suite OData API: Reference Guide and the SAP SuccessFactors HXM Suite OData API: Developer Guide. The first guide explains the available OData API Entities with attributes and navigations. It also mentions the required permission settings to enable the APIs. The 2nd guide focus more on generic API concepts. Those are authentication concepts, handling of time data in OData queries and different operations to write data.
Use SuccessFactors APIs in the right way
The intention of the API guides above and the SAP API Business Hub is to discover and understand the basic building blocks of integrations, our APIs. It is not in their focus to explain how to build a correct, robust and performant integration based on requirements of a customer or a partner. Providing the APIs without a guidance how to use them in the right way gave too much room for errors. As a result, we saw a lot of quick build integrations. They did not make proper use of efficient integration patterns. Those integrations used full loads where delta loads would have been better. Others did not make use of the right API features to guaranty that no changes got lost in a data replication.
When we saw this situation, we decided to take up the task to change this. We made it our mission as a team to provide the missing piece of information to our partners and customers. Our first action was to call out for a workshop. We invited our most experienced implementation partners. Those which have built already many integrations for our common customers. We asked them about their challenges but also how they addressed them in their projects. We discussed what solutions did work well and which didn’t. The result of this collaboration is a new IDP we called “Best Practices using SAP SuccessFactors APIs for Custom Integrations”. You will find it with others on our SAP SuccessFactors customer community page. We explain in this document best practices for integration challenges and how to avoid common pitfalls. We answer questions, such as what APIs to use for which integration use case. We talk about how to build performant custom integrations using delta loads. And we share insights on how to build correct and robust OData queries using the right paging. “We” in this context does include me but also our partners. Without their help this document would not have been possible. I like to thank especially our contributors Andreea Bejenaru (PwC), Belinda Lineman (AspireHR), Clarisse Gondoprawiro (PwC) and Marc van Driel (Comentec) for their input.
But there are more building blocks than our APIs when custom integrations are being build. There can be events involved, integration monitoring tools and different middleware options. Those tools need guidance too. While the middleware options from all providers are huge, there are two SAP products where good guidance is available too.
First of all I like to mention the SAP Integration Suite Design Guidelines available at the SAP API Business Hub. This guideline explains design best practices for integrations and provides integration flows to copy from. Good examples are the right usage of batching and session reuse in the middleware. Both improve the performance of integrations. Batching, in specific, helps to avoid out of memory issues in the middleware in case of high data volumes.
Last, I like to mention our IDP “SAP SuccessFactors Integrations Tools: Integration Center and SAP Cloud Platform Integration”. This document is also available on the SAP customer community page. It helps with the question, when to use the SAP Integration Suite and when to use the SAP SuccessFactors Integration Center. We explain in this document for which simple integrations someone can use the code-free SAP Integration Center. We also recommend when it is the better option to use the SAP Integration Suite.
I like to conclude with a short summary. When you start building SuccessFactors integrations you should know our two IDPs: Best Practices using SAP SuccessFactors APIs for Custom Integrations” and “SAP SuccessFactors Integrations Tools: Integration Center and SAP Cloud Platform Integration. They are the best practice coming from our leading integration partners and SAP SuccessFactors. If you use SAP Integration Suite, the SAP Integration Suite Design Guidelines is a must read. Are you looking for detailed API features and specification? Then go to the SAP API Business Hub or check out our OData Development and Reference Guidelines.
This brings me to the end of my first blog post. As a last request I like to ask you to leave your comments and feedback. Do you have a topic about SAP SuccessFactors APIs in mind and you would like to know more details? Let me know about it in the comments! I’m more than happy to have a look and see if I can make a blog post out of it or if I can help in other ways.