Create SOAP Service in OIC: Step-by-Step Guide
Create SOAP Service in OIC: Step-by-Step Guide to Building a SOAP API in Oracle Integration Cloud
SOAP-based web services continue to be widely used in enterprise environments, particularly with Oracle Fusion Applications, ERP systems, HCM applications, legacy applications, and other business systems.
Oracle Integration Cloud (OIC) provides a straightforward way to expose an integration as a SOAP web service using the SOAP Adapter. Instead of developing a SOAP service from scratch, you can configure the SOAP endpoint, define the request and response structure, add business logic, transform data, and publish the service through OIC.
In this guide, we will learn how to create a SOAP service in OIC, configure the SOAP Adapter, build the integration flow, test the service, and troubleshoot common issues.
What Is a SOAP Service in OIC?
A SOAP service is a web service that communicates using SOAP (Simple Object Access Protocol) messages, typically represented using XML.
In OIC, the SOAP Adapter can be configured as a trigger to expose an inbound SOAP endpoint. External applications can then send SOAP requests to the OIC endpoint, where the integration processes the request and returns a SOAP response.
Oracle’s current OIC documentation confirms that the SOAP Adapter can expose inbound SOAP endpoints and pass the incoming request payload to the next activity in the integration.
A typical architecture looks like this:
External Application
|
| SOAP Request
v
+----------------------+
| Oracle Integration |
| SOAP Trigger |
+----------------------+
|
v
Data Mapping
|
v
Business Logic
|
+-------------------+
| |
v v
Oracle Fusion Database / REST
Application API
|
v
SOAP Response
|
v
External Application
Why Create a SOAP Service in OIC?
Creating a SOAP service in OIC is useful when an organization needs to:
- Expose existing business logic as a web service
- Integrate legacy SOAP applications with cloud applications
- Connect external applications with Oracle Fusion Applications
- Transform XML messages between different systems
- Implement enterprise integration workflows
- Add authentication and security
- Connect SOAP clients to REST APIs
- Connect SOAP clients to databases or SaaS applications
OIC supports inbound SOAP endpoints over HTTPS and provides multiple security options, including HTTP Basic Authentication, WS-UsernameToken, OAuth 2.0, and SAML, depending on the configuration and OIC capabilities.
SOAP Service vs REST Service in OIC
Before creating the service, it is important to understand the difference.
| Feature | SOAP | REST |
|---|---|---|
| Message format | XML | JSON/XML |
| Contract | WSDL | OpenAPI commonly used |
| Protocol | SOAP over HTTP/HTTPS | HTTP/HTTPS |
| Security | WS-Security, Basic Auth, OAuth, etc. | OAuth, Basic Auth, etc. |
| Enterprise legacy systems | Excellent | Good |
| Lightweight APIs | Less suitable | Excellent |
| Typical use | Enterprise integrations | Modern APIs |
If the consuming application specifically requires a SOAP interface or WSDL-based contract, a SOAP-triggered integration is generally appropriate.
Prerequisites
Before creating a SOAP service in OIC, make sure you have:
1. Oracle Integration Instance
You need access to an Oracle Integration environment.
This guide focuses on the current Oracle Integration 3 experience.
2. Appropriate OIC Access
You should have permissions to create connections and integrations.
3. SOAP Adapter
The SOAP Adapter should be available in your OIC environment.
4. Service Definition
You should understand the request and response structure that your SOAP service needs to support.
Depending on the implementation, you may work with:
- Existing WSDL
- Uploaded WSDL
- Generated service definition
- XML schema
- SOAP operations
5. Target System
If your SOAP service needs to invoke another application, have the target connection details ready.
For example:
- Oracle Fusion
- REST API
- Database
- External SOAP service
- SaaS application
Step 1: Create a SOAP Adapter Connection
The first step is to create a SOAP Adapter connection.
Navigate to:
Home → Integrations → Connections
Click:
Create
Then search for:
SOAP
Select the SOAP Adapter.
Oracle’s documentation describes creating connections from Home → Integrations → Connections → Create, followed by selecting the required adapter.
Step 2: Enter Connection Details
Provide a meaningful connection name.
For example:
EMPLOYEE_SOAP_SERVICE
You can also provide a description such as:
SOAP connection for Employee Integration
Use meaningful naming conventions because connections may be reused across multiple integrations.
Step 3: Configure SOAP Connection Security
The exact security configuration depends on your integration requirements.
Common security mechanisms include:
- Basic Authentication
- OAuth 2.0
- WS-Security
- Username Token
- Certificates
- SAML
For inbound SOAP services, OIC supports multiple security policies depending on the endpoint configuration.
For a development environment, you may use a simpler authentication configuration.
For production environments, always select a security mechanism appropriate for the organization’s security standards.
Step 4: Test the Connection
After entering the required configuration, click:
Test
If your configuration is valid, OIC should successfully validate the connection.
Oracle recommends testing the connection after configuration. When a WSDL is involved, OIC provides validation/testing options that can validate the WSDL and its imported schemas.
If the test fails, check:
- WSDL URL
- Credentials
- SSL certificates
- Endpoint URL
- Network connectivity
- Authentication configuration
- Imported WSDL/schema references
Step 5: Create a New Integration
Now create the actual integration.
Navigate to:
Home → Integrations → Integrations
Click:
Create
Select an appropriate integration pattern.
For a SOAP service that should be invoked by an external application, an App Driven Orchestration is commonly used.
For example:
Integration Name:
Employee_SOAP_Service
Description:
SOAP service to receive employee information
and process the request.
Click Create.
Step 6: Configure the SOAP Trigger
The SOAP Adapter can be configured as the trigger of the integration.
The trigger represents the entry point of the service.
The flow becomes:
SOAP Client
|
| SOAP Request
v
SOAP Adapter
|
v
OIC Integration
Drag the SOAP Adapter onto the trigger section.
Select the SOAP connection created earlier.
Oracle documents that dragging the SOAP Adapter into the trigger or invoke area opens the Adapter Endpoint Configuration Wizard.
Step 7: Configure the SOAP Endpoint
The Adapter Endpoint Configuration Wizard guides you through the SOAP endpoint configuration.
Depending on the configuration, you can define:
- Service name
- Operation
- Request
- Response
- SOAP headers
- Security
- Callback configuration
- WSDL-related information
The SOAP Adapter supports different message exchange patterns, including synchronous request/response, one-way requests, and asynchronous request/callback scenarios.
For our example, we will use a simple synchronous request/response service.
Step 8: Define the SOAP Operation
Suppose we want to create an employee lookup service.
Our operation can be:
getEmployee
The request might contain:
<EmployeeRequest>
<EmployeeId>1001</EmployeeId>
</EmployeeRequest>
The response could be:
<EmployeeResponse>
<EmployeeId>1001</EmployeeId>
<EmployeeName>John Smith</EmployeeName>
<Department>IT</Department>
<Status>Active</Status>
</EmployeeResponse>
The exact XML structure depends on the WSDL/schema used by your implementation.
Step 9: Add Business Logic
Once the SOAP trigger is configured, you can add activities to process the request.
For example:
SOAP Request
|
v
Validate Employee ID
|
v
Call REST API
|
v
Transform Response
|
v
Return SOAP Response
OIC allows you to add various actions such as:
- Assign
- Switch
- Map
- Stage File
- Invoke
- Scope
- Fault handling
- For Each
- While
- Wait
Your integration flow depends on the business requirement.
Step 10: Add a Target System
Suppose the employee information is available through a REST API.
You can create a REST Adapter connection and invoke it from the SOAP integration.
The overall architecture becomes:
SOAP Client
|
v
SOAP Trigger
|
v
OIC Mapper
|
v
REST Adapter
|
v
Employee REST API
|
v
REST Response
|
v
OIC Mapper
|
v
SOAP Response
This is one of the useful capabilities of OIC: the client can continue using SOAP while the backend system can use REST.
Step 11: Map the SOAP Request
The Mapper is used to transform data between the SOAP request and target system.
For example:
SOAP Request
----------------
EmployeeId
|
v
REST Request
----------------
employeeNumber
The mapper could transform:
EmployeeId = 1001
into:
{
"employeeNumber": "1001"
}
This allows different applications to communicate even when their data structures are different.
Step 12: Map the Response
After receiving the response from the target application, map the data back to the SOAP response structure.
For example:
REST Response
---------------------
employeeNumber
employeeName
department
status
|
v
SOAP Response
---------------------
EmployeeId
EmployeeName
Department
Status
The response can then be returned to the original SOAP client.
Step 13: Add Fault Handling
Error handling is extremely important in production integrations.
Possible failures include:
- Invalid employee ID
- Authentication failure
- Target API unavailable
- Timeout
- Invalid XML
- Mapping failure
- Business validation error
Use OIC’s fault-handling capabilities to capture and process errors.
A simplified flow can be:
SOAP Request
|
v
Try Processing
|
+------ Success ------> SOAP Response
|
+------ Error --------> Fault Handler
|
v
Error Response
You should avoid exposing unnecessary internal system details to external clients.
Step 14: Activate the Integration
After completing the integration flow:
- Save the integration.
- Validate the integration.
- Fix any validation errors.
- Click Activate.
- Enable tracing if required for testing.
- Confirm that the integration is active.
Once activated, OIC exposes the SOAP endpoint for client applications.
Step 15: Get the SOAP Endpoint and WSDL
After activation, OIC provides the information required to invoke the integration.
The SOAP service generally exposes a WSDL that describes:
- Service
- Port
- Binding
- Operations
- Request structure
- Response structure
The client application can use the WSDL to understand how to invoke the SOAP service.
The SOAP Adapter is specifically designed to expose inbound SOAP endpoints and process requests sent to the endpoint.
Step 16: Test the SOAP Service Using SoapUI
One of the easiest ways to test a SOAP service is SoapUI.
Open SoapUI and create a new SOAP project.
Provide the WSDL URL.
For example:
https://<oic-instance>/ic/ws/integration/v1/Employee_SOAP_Service
Use the actual endpoint generated by your OIC environment.
SoapUI can then generate the SOAP request template from the WSDL.
For example:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:emp="http://example.com/employee">
<soapenv:Header/>
<soapenv:Body>
<emp:getEmployee>
<emp:EmployeeId>1001</emp:EmployeeId>
</emp:getEmployee>
</soapenv:Body>
</soapenv:Envelope>
Send the request and verify the response.
Example SOAP Response
A successful response could look like:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<EmployeeResponse>
<EmployeeId>1001</EmployeeId>
<EmployeeName>
John Smith
</EmployeeName>
<Department>
IT
</Department>
<Status>
Active
</Status>
</EmployeeResponse>
</soapenv:Body>
</soapenv:Envelope>
The actual response format depends on the WSDL and response schema configured for your integration.
Important SOAP Adapter Capabilities in OIC
The SOAP Adapter provides several important capabilities.
1. Inbound SOAP Endpoints
You can expose an OIC integration as a SOAP service.
2. External SOAP Invocation
The SOAP Adapter can also invoke external SOAP services.
Therefore, it can work in both directions:
External Client
|
v
SOAP Trigger
|
OIC
|
v
SOAP Invoke
|
v
External SOAP Service
Oracle documents both inbound SOAP endpoint exposure and outbound SOAP invocation capabilities.
3. SOAP Headers
OIC can work with standard and custom SOAP/HTTP headers depending on configuration.
4. Security
Inbound SOAP services can use supported security policies such as Basic Authentication, WS-UsernameToken, OAuth 2.0, and SAML.
5. HTTPS
Inbound SOAP endpoints are configured using HTTPS.
6. Synchronous and Asynchronous Patterns
OIC supports synchronous request/response and other supported message exchange patterns.
Common Issues When Creating SOAP Services in OIC
1. WSDL Validation Error
Possible causes
- Invalid WSDL
- Missing imported XSD
- Incorrect namespace
- Broken schema reference
- Inaccessible WSDL URL
Solution
Validate the WSDL independently and make sure all imported schemas are available.
2. Authentication Error
If you receive:
401 Unauthorized
check:
- Username
- Password
- Authentication policy
- OAuth configuration
- SOAP security headers
3. SOAP Action Mismatch
A SOAP Action mismatch can occur when the SOAP client’s request does not match the operation configured in the service.
Check:
- SOAPAction
- WSDL operation
- Binding
- Namespace
- Request structure
Oracle’s SOAP Adapter documentation includes specific troubleshooting guidance for SOAP Action mismatch errors.
4. XML Mapping Error
If the request reaches OIC but mapping fails, check:
- Namespace
- Element names
- Data types
- XML hierarchy
- Required fields
Always compare the incoming XML against the WSDL/schema.
5. Target System Failure
If the SOAP service works but the backend call fails, investigate:
- Target endpoint
- Authentication
- Network connectivity
- SSL certificates
- Timeout
- Target application logs
SOAP Service Best Practices in OIC
Use Meaningful Names
Use names such as:
EMPLOYEE_SOAP_SERVICE
CUSTOMER_CREATE_SOAP
ORDER_STATUS_SOAP
Avoid generic names such as:
TEST1
SOAP_INT
DEMO
Use Proper Error Handling
Always implement appropriate fault handling for production services.
Secure Your Endpoint
Do not expose sensitive enterprise services without authentication and authorization.
Validate Input
Validate important fields before calling downstream applications.
Keep Transformations Clean
Use Mapper for transformations instead of unnecessarily complex orchestration logic.
Use Reusable Connections
Create reusable connections instead of creating duplicate connections for every integration.
Monitor Integrations
Use OIC monitoring to review:
- Successful instances
- Failed instances
- Request/response details
- Errors
- Processing times
Test With SoapUI
SoapUI is useful for testing WSDL-based SOAP services before integrating the endpoint with a production application.
SOAP Service Architecture Example
Consider an organization where an HR application needs employee information from Oracle Fusion.
The HR application only supports SOAP.
Oracle Fusion exposes a REST API.
Instead of changing the HR application, OIC can act as the integration layer.
+--------------------+
| HR Application |
+--------------------+
|
| SOAP Request
v
+--------------------+
| Oracle Integration |
| SOAP Trigger |
+--------------------+
|
v
+--------------------+
| Mapper |
+--------------------+
|
v
+--------------------+
| REST Adapter |
+--------------------+
|
v
+--------------------+
| Oracle Fusion API |
+--------------------+
|
v
REST Response
|
v
+--------------------+
| Mapper |
+--------------------+
|
v
SOAP Response
|
v
+--------------------+
| HR Application |
+--------------------+
This approach allows the legacy SOAP client and modern REST backend to communicate without requiring either application to completely change its interface.
SOAP Service in OIC: End-to-End Flow
The complete process can be summarized as:
1. Create SOAP Adapter Connection
↓
2. Configure Security
↓
3. Test Connection
↓
4. Create App Driven Integration
↓
5. Add SOAP Adapter as Trigger
↓
6. Configure Operation
↓
7. Define Request/Response
↓
8. Add Business Logic
↓
9. Add Target Adapter
↓
10. Map Request
↓
11. Invoke Target
↓
12. Map Response
↓
13. Configure Fault Handling
↓
14. Validate Integration
↓
15. Activate
↓
16. Test Using SoapUI
↓
17. Monitor Execution
Key Takeaways
Creating a SOAP service in Oracle Integration Cloud is a powerful way to expose integration processes to applications that require SOAP and XML-based communication.
The SOAP Adapter acts as the entry point for inbound SOAP requests and can also be used to invoke external SOAP services.
The basic implementation involves:
- Creating a SOAP Adapter connection
- Configuring security
- Creating an App Driven integration
- Adding the SOAP Adapter as a trigger
- Defining the SOAP operation
- Mapping the request
- Calling the backend application
- Mapping the response
- Implementing fault handling
- Activating and testing the service
Once you understand this flow, you can build more advanced OIC integrations involving Oracle Fusion ERP, HCM, SCM, databases, REST APIs, legacy applications, and third-party SOAP services.
