For developers of SAP Integration Suite, navigating the interconnected landscape of today's business environment often leads to a critical juncture: the integration between CRM systems like Salesforce and ERP solutions such as SAP (see
https://blogs.sap.com/2021/02/09/salesforce-integration-common-requirements-and-use-cases./).
In this blog, we will explore the technical aspects of migrating an interface from the Advantco to the Rojo adapter within the context of SAP Cloud Integration for Salesforce. The aim is to offer a resource-saving approach that avoids the need for complete reconfiguration, while maintaining technical and strategic integrity.
We will start with a technical overview of the Advantco environment to comprehend the existing foundation. Subsequently, we will demonstrate the adjustments required for migrating to the Rojo environment. This approach will provide us with a clear understanding of the migration process for a Cloud Integration interface and illuminate the differences in functionality between both adapters.
Advantco Mapping structure
sObjects Node with Occurence of 1..*:
This node serves as the main node for the objects to be processed. The occurrence 1 to unbounded indicates that one to an unlimited number of objects can be processed within this node. The one-time generation by a constant means that this part of the structure has a fixed form and does not vary dynamically based on the incoming data.
Advantco - sObjects structure
Subordinate sObjects Node with Occurrence of 1..*:
This node, also with the occurrence of 1..*, is generated more frequently and is used to represent the individual objects or records that are to be processed. The multiple generations of this node reflect the ability to process multiple objects in a single message.
Advantco - sObject structure
Key Fields: Operation, ObjectType, ExternalID
Under the Account node, these fields are key elements in the mapping process and each field is set as a constant:
Advantco – ObjectType, ExternalID
Operation: This field specifies the function to be executed on the data. Setting it as a constant ensures that the same operation is uniformly applied to all records processed under this node.
Advantco - Operation Mapping
ObjectType: The field determines the type of object being processed. The value set here depends on the specific application and the requirements of the target system. In a Salesforce context, for example, it could be Account, Contact or another type of object. In our example, we have ‘Account’:
Advantco - ObjectType
ExternalID: This is typically a unique identification number or key used to uniquely identify or reference records. Setting the ExternalID as a constant ensures that a specific identifier is consistently applied to all data processed.
Advantco - ExternalID
Let’s now explore the migration process to the Rojo structure. We will start by highlighting the key differences compared to the Advantco structure, as previously outlined. Understanding these distinctions is crucial for a successful migration, as we migrate from the Advantco to the Rojo Adapter within the SAP Integration Suite.
How to generate the Rojo structure:
The Rojo structure can be created using Eclipse Rojo Adapter plugin. In this environment, on the left side, you can select the specific Salesforce object or objects required for you project, which in our case was ‘Account’. By selecting the ‘Generate XSD’ button, both the request and response XSDs are generated. This structure can then be used as a reference in the Message Mapping process within the SAP Cloud Integration.
Request XSD:
Rojo - Eclipse Request XSD
Response XSD:
Rojo - Eclipse Response XSD
General Advisory: Update XPath Expressions:
With the migration to a new structure, it’s important to remember that XPath expressions will need to be updated accordingly. Failing to update these expressions may lead to incorrect data processing or integration errors, so this step is essential for a smooth migration.
Rojo Mapping Structure
SObjectsCollection Node with Occurence 1..1
The ‘SObjectsCollection’ node acts as the primary node for all Salesforce objects (record) data elements within the mapping structure. This fixed occurrence ensures structural consistency and predictability in the data processing, as there will always be exactly one ‘SObjectsCollection’ node present.
Rojo - sObjectsCollection structure
allOrNone field
The AllOrNone field in Salesforce Robo Adapter is a boolean field that determines how the adapter should react when performing an operation (Insert, Upsert, Update or Delete) on multiple records in a Salesforce database.
If AllOrNone is set to 'true', the Salesforce Robo Adapter will stop and roll back the entire operation if any one of the operations on individual records fails. Essentially, this means that either all records get updated, inserted, or deleted successfully, or none of them do.
If AllOrNone is set to 'false', the adapter operation will continue despite any individual operation failures. This means that even if some records cannot be updated, inserted, or deleted, the rest will still be processed.
Essentially, AllOrNone decides whether the operation should be fully transactional (all-or-nothing) or not.
Rojo - SObjectCollection - allOrNone
Records Node with Occurence 1..*
In the Rojo structure, the ‘records’ node aligns with the second sObjects node from the previously described Advantco structure. This alignment suggests a comparable role in managing multiple data records, yet within Rojo’s specific framework.
Operational details in the mapping structure:
In Rojo’s data mapping approach, certain operational details such as ExternalID and Operation, are not included within the mapping structure, unlike in the previous approach. Instead, Rojo employs a similar method for managing the ‘ObjectType’ as seen in Advantcos approach, albeit under a different label, reffered to as ‘type’.
Under the ‘records’ node, there’s a subordinate ‘attributes’ node, within which we find the field ‘type’. This field corresponds to Advantco’s ‘ObjectType’ and is consistently mapped as a constant.
Rojo - type mapping
Configuration of the Rojo Adapter
As previously mentioned, it’s essential to configure the operational parameters directly within the Rojo Adapter when migrating from Advantco to Rojo. This involves aligning the adapter’s settings with the previously discussed mapping structure. In this section, we will explore and explain the various configuration options available for an effective migration from the Advantco to Rojo Adapter.
Operation and Method settings for sObject Collections: Within the processing tab of the Rojo Adapter, the operation is configured as ‘Salesforce Objects – sObject Collections’. This crucial setting determines the methodology of data processing. The method, analogous to what is referred to as the ‘Operation' key field in Advantco’s structure, is set to
‘Upgrade’. This aligns with Advantco’s ‘Upsert’ functionality, allowing for updating an entire collection, such as multiple timesheets, in a single operation.
In contrast to Update, the Upgrade operation creates a new data record if it does not exist. An update would result in an error if the data record does not exist.
Rojo - Adapter sObjectsCollection update
Handling Updates with External ID for a Salesforce Object: A significant feature of the Rojo Adapter is its capability to perform updates using an External ID. This method allows for more targeted updates, enabling precise modification to individual objects within a collection, such as a specific timesheet. This targeted approach is especially beneficial for scenarios that require exact, object-specific updates. To implement this, we select ‘Salesforce Object – Update’ in the ‘Operation’ field and specify the ‘Salesforce Object ID’, which corresponds to the External ID used in the Advantco mapping structure before, ensuring precise identification and modification of the intended object.
In general, within the Rojo Adapter, users can access a comprehensive list of all available operations and methods directly from the adapter’s interface:
Rojo - Adapter operations
SQL Query configuration in Advantco Adapter:
In the Advantco Adapter, the
SQL Query configuration is located within the ‘Salesforce Query/Search’ tab. This section is divided into three distinct fields:
SELECT: Here, we specify the field names that we want to retrieve. For instance, you might include fields such as ‘id’ and ‘status’.
FROM: This field is used to designate the target Salesforce Object. In our example, this would be ‘Timesheet’.
WHERE: This field is for defining the condition expression. An example could be setting a condition like ‘Status=’Reviewed’’, which filters the records based on the specific status.
Advantco - Adapter query
SQL Query configuration in Rojo Adapter:
In the Rojo Adapter, SQL Query configuration is facilitated through the ‘Operation’ field, located in the processing tab. To setup up the query, this field should be adjusted to SOQL – Execute Query’. During the migration process from Advantco to Rojo, it’s important to transfer the query details accurately. This involves copying the information from Advantco’s ‘Select’, ‘From’ and ‘Where’ fields into the ‘SOQL Query’ field in the Rojo Adapter. This step ensures that the same criteria and conditions used in the Advantco system are seamlessly integrated into the Rojo environment, maintaining the integrity and functionality of the data querying process.
Rojo - Adapter query
In the Eclipse editor, the SOQL editor feature becomes a powerful tool, allowing us to generate the corresponding query for our needs. A notable aspect within this process is the presence of ‘__c’ suffixes, which signify custom fields in the Salesforce structure. This notation is a key indicator, enabling users to easily identify and work with custom elements tailored to their specific Salesforce configurations.
Rojo - eclipse Adapter query test
Event-Based Integration:
An important consideration in migrating from the Advantco to the Rojo Adapter is the handling of the event-based Salesforce integration.
While Advantco supports SQL based events in its adapter, some adjustments are necessary when migrating to Rojo, as its adapter is not inherently designed for this. To ensure a similar process in Rojo integration, it seems to be a good approach to outsource the main process to a subprocess and equip it with a timer. This setup will allow the main process to be initiated based on the timer settings:
Rojo - Timer
Rojo - Timer settings
The Salesforce Rojo Sender Adapter offers further options for event-based data retrieval.
Here are some options for different event-based retrievals.
Rojo sender adapter - event types
For example, it is possible to consume platform events. By subscribing to a specific channel, data sets can be obtained. The logic of which records are available for collection is outsourced to Salesforce and in this case it is not determined by the SQL statements SELECT, FROM, WHERE.
Rojo sender adapter - platform events
Conclusion
This blog describes the complex integration of Salesforce with SAP, focusing on the efficient migration from the Advantco to the Rojo Adapter within the SAP Integration Suite framework.
Links
- Salesforce Rojo Adapter LINK