Integration Procedure

In this article we are going to cover basics of OmniStudio Integration Procedure (IP). I believe you have fair understanding of OmniStudio concepts and OmniStudio DataRaptor. I posted couple of articles related to that and I would recommend going through that if you are new to OmniStudio. You can go to Home page and access the articles in OmniStudio category.

This is other productivity tool packaged in OmniStudio that you would love to explore and use. OmniStudio provides several actions like DataRaptor Post, DataRaptor Extract, HTTP Action etc… We do not need to learn all the actions in details but having basic knowledge of these actions help us when we get a requirement. If none of the action meets our requirements, then we have to write APEX. Integration Procedure also provides an action (Remote Action) to call a standard or custom written APEX class. Scope of this article is to introduce you with Integration Procedure and not exploring all the actions so we would keep this article simple and focus on Integration Procedure.

Integration Procedure works as a container to place one or more actions, string it together, orchestrate as per requirement.

We have large number of actions that can be added to Integration Procedure. I have been developing Integration procedure since last 4 years but did not use all the actions so it would be ongoing learning with your project work.

Integration Procedure can be executed from OmniScript, FlexCard, APEX and several other tools. We would not surprise if in coming days Salesforce provides ability to execute IP directly from Salesforce Flows.

You may not always need to use Integration Procedure and you can directly add your action(s) in OmniScript. But at the same time there would be scenarios where you have to use Integration Procedure. We would explore Integration Procedure with one scenario.

Scenario

We got requirement to extract first 10 contacts from Salesforce that we would like to display in a flex card. Let’s assume We just need to extract few fields like FirstName, LastName, Email and AccountId

Solution

Yes, as you guessed correctly this is very simple requirement and we just need to create one DataRaptor extract. Do we really need an Integration Procedure here? Agree we do not need an Integration Procedure for this requirement. We can create one DataRaptor and use that directly on Flex Card.

Well as I mentioned earlier, an Integration Procedure can have one or more actions. Yes, we can create an integration procedure with just one action. With my experience and learning I would recommend to always use Integration Procedure if you are planning to use a DataRaptor. You can extend your Integration Procedure to add more actions if needed in future. You do not need to agree but since we are going to learn Integration Procedure so let’s create an Integration Procedure.

Use App Launcher and select “OmniStudio Integration Procedure”
Create a new Integration Procedure. Type and SubType together should identify an Integration Procedure uniquely. Name is used for display purpose only. Name, Type and SubType below are for learning purpose and you can use whatever you would like to use. Type we normally use to group. Below example I used Contact as Type as I am thinking to all Integration Procedure related to Contact I would use Type as Contact.
- Integration Procedure Name: Get First 10 Contact For Learning
- Type: Contact
- SubType: GetFirstTenContacts

We assume you already know how to create a simple DataRaptor Extract and you have created one that returns first 10 contacts details and it does not require any input
Add a DataRaptor Extract action by dragging it from Available Components to Structure section
Give a name for element and select the DataRaptor that you created to extract first 10 contacts from Salesforce. I am also adding DataRaptor snapshot if you need some help here

Integration Procedure by default does not return anything (except exception). So if you would like to get something back from Integration Procedure then you will have two options:-
- Return response from all actions by simply selecting “Include All Actions in Response” option on Procedure Configuration
- Use Response Action in Integration Procedure. This is recommended approach to get response from Integration Procedure. It is recommended to send only necessary input to Integration Procedure and get only necessary response back from Integration Procedure. This reduce the network traffic and also improves overall performance of Integration Procedure. In summary all Integration procedure should have at-least one response action that should return expected response or an exception response
Use Preview to test and ensure response is aligned with expected response. Few screenshots are added if you would like to reference.

Well, you saw how simple it was to create a new Integration Procedure. Believe it or not, most of the time we create simple Integration Procedure that contains one to three actions but at the same time you may get requirement to create Integration Procedure that calls some other Integration Procedures and performs several actions and transformations before returning the response back. As long as you know the basics you are good to work on any Integration Procedure. It will have one ore more actions and some response, so you need to learn usage of different actions available in Integration Procedures. Each action requires one or more articles with some examples to understand the basics (basics only). It may take some time and tryout before you consider yourself master.

I know this example does not justify understanding the capabilities of Integration Procedure, so I am going to modify the scenario and I would provide some help, but I am sure you can do it yourself.

Updated Scenario

We have to extend the Integration Procedure that we created, and we would like our Integration Procedure to perform two actions: –

Use a DataRaptor Extract action to get first 10 contacts from Salesforce. We already developed this DataRaptor
Send a simple email to these contacts using Email action. We have to use email field on contact for recipient of these emails

Well now our Integration Procedure requires two actions along with logic to loop through the contacts list returned by DataRaptor. I am adding few screenshots that should help you complete this.

Cloned the original Integration Procedure and added additional components / actions as given below

Loop Block: This one is needed to loop through set of records. In this case it would loop through contacts list
Email Action: This one is used to send the email
Get Account Details: Just added here so you know we can add multiple actions inside loop also. In this example it calls a DataRaptor and passed AccountId extracted by Contacts DataRaptor
Response Action: It can be simple status as Success or Failure or Contact Details or Account Details. You can try updating JSON path to different element and see how it changes.

Advantages & Recommendations

Integration Procedure runs on server. So request with necessary input would be submitted to server once and then all actions would be executed on Server. This means better performance and less interaction with client and server
Since Integration Procedure is executed on Server we have to ensure we are passing only necessary input and we are receiving only needed output
In a general rule if you are planning to use DataRaptor then instead of using DataRaptor directly in Flex Card or OmniScript you can create one Integration Procedure and use that in your flex cards or OmniScript
Implement modular design so you can reuse one Integration Procedure inside other Integration procedure
Handle fault and exception in Integration Procedure so you can show a logical message to user instead of technical fault
You can execute an action in Integration Procedure conditionally so you can have logic to execute the action that is needed for your business requirements
Use proper names for Type and SubType as this helps grouping similar process and it would be easy to maintain and identify