1. Using Oracle Mobile Cloud Service
  2. Connector APIs
  3. SOAP Connector APIs

25 SOAP Connector APIs

Oracle Mobile Cloud Service (MCS) enables you to create connector APIs to connect to SOAP services. You can call these connector APIs from the implementations of your custom APIs.

Description of soap_connector_arch.png follows
Description of the illustration soap_connector_arch.png

How SOAP Connector APIs Work

A SOAP connector API is an intermediary API for calling SOAP endpoints. The connector API takes the form of a configuration that gives your apps a standard way to connect to these SOAP endpoints and take advantage of the security, diagnostics, and other features provided by MCS.

The key steps to creating a SOAP connector API are establishing a connection to an external system, examining and selecting a set of possible interactions, and then modeling them into a reusable API.

The SOAP Connector API wizard walks you through creating SOAP connector APIs, from specifying the WSDL location of a remote service, setting a port, setting security policies, to testing your endpoints.

SOAP Connector API Design Process

Here’s the process for designing a SOAP connector API:

  1. A SOAP Connector API is created in MCS using the SOAP Connector API wizard and is passed to the Asset catalog (the Asset catalog is a repository in MCS where API information is stored). The connector API is added to the list of connector APIs (using the API display name) on the Connectors Manage page on the Development tab.

  2. The WSDL location is passed to the WSDL Parser. The WSDL file describes how the service is called, what the expected parameters are, and what data structures are returned. From the data in the WSDL file a sample body is generated.

  3. The WSDL Parser goes to the provided WSDL location to obtain the WSDL file.

  4. All the available ports for the connector are extracted by the parser and returned to the Asset catalog, after which, the port can be selected and the connector API configurations, such as the endpoint URI and custom operation names, are provided.

  5. The Asset Catalog stores the security policies and the request and response schemas.

Here’s how the runtime flow goes:

Description of soap_rt_flow.png follows
Description of the illustration soap_rt_flow.png

  1. Custom code calls the SOAP Connector API. Information is then passed to the connector implementation. The implementation extracts the JSON payload from the request.

  2. The schemas, security policies, and API configuration are passed to the Asset catalog.

  3. The implementation sends the JSON payload to the JSON translator to translate it to XML using the schemas that are stored as part of the API configuration.

  4. The JSON translator returns the payload in XML format.

  5. A SOAP message is constructed from the XML, some HTTP headers (like context-id) and security-related headers are added and the request is sent to the external service.

  6. An XML response is sent by the service back to the connector API. Step 3 and Step 4 are repeated. The response is sent to the JSON translator by the connector implementation to translate the XML response to JSON. The translated response is sent to the connector API.

  7. The connector API sends the JSON response back to the custom code.

Why Use SOAP Connectors Instead of Direct Calls to External Resources?

  • Allows for simplified declarative connection and policy configuration.

  • Allows calls to an external service, along with security policy setup and credentials, to be encapsulated and used consistently across the mobile API.

  • Provides automatic translation of JSON requests to XML and XML responses to JSON, enabling you to interact with SOAP services without having to work expressly with XML. In addition, it provides you with the ability to provide the SOAP envelope itself, giving you the choice of using XML or JSON.

  • Lets you dynamically modify HTTP timeout properties via the user interface without having to bring down the service. This feature is particularly beneficial when the external SOAP service or network connectivity suffers a slowdown.

  • Provides you with extensive diagnostic information as its tightly integrated with the MCS diagnostics framework. Any outbound calls made through connector APIs are logged, which greatly helps with debugging.

  • Allows for tracking and analytics on remote API usage.

  • Lets you define interaction with the service at design time when you test the validity of your endpoints so that the terms of that interaction aren’t dependent on user input at runtime. This protects both the end system and your mobile backend from harm.

  • Provides a consistent design approach among multiple connector types for interacting with external services.

  • With any change in the interface for a service, lets you can handle any necessary updates, testing, and migration in one place.

Creating a SOAP Connector API

Use the SOAP Connector API wizard to quickly configure your connector API by providing a name and description, specifying a port, setting security policies, and testing it.

Creating a connection to an existing SOAP service can be a simple two-step operation:

  1. Name your connector API.

  2. Provide the WSDL of the external service.

Note:

A timeout can occur when downloading a large WSDL file or when connecting to a WSDL over high latency networks, which prevents the creation of the SOAP Connector API. To ensure the WSDL is downloaded, set the following environment policies before you create the API:

  • *.*.Network_HttpConnectTimeout

  • *.*.Network_HttpReadTimeout

Set these policies in the development environment in which you’re creating the SOAP Connector API. A mobile cloud administrator can export the policies file from the Administration view, edit these values, and import the modified file back to the development environment.

These policies affect only the connector APIs during design time. The timeout values that you set while configuring a connector API take effect during runtime.

To edit environment policies, see Modifying an Environment Policy.

You also have the ability to configure client-side security policies for the service that you’re accessing and testing and checking the results of your connection.

As soon as it’s created, your connector API appears in the list of connector APIs. When at least one connector API exists, you’re taken directly to the Connector API landing page when you click Connectors from the side menu. From there, you can select the connector API you want and edit it, publish it, create a new version or update an existing version, deploy it if it has a Published state, or move it to the trash. See Connector Lifecycle.

To call a connector API, you can create a custom API and configure the API’s implementation to call the connector. See Calling Connector APIs from Custom Code.

Setting the Basic Information for Your SOAP Connector API

Before you begin configuring your connector, you must provide some initial basic information like the connector API name, the address to the remote service, and a brief description:

  1. Make sure that you’re in the environment where you want to create the SOAP Connector API.

  2. Click open the side menu icon and selectApplications > APIs from the side menu.

    The Connectors page appears. If no connector APIs have been created yet, you'll see icons for each of the connector APIs that you can create. If at least one connector API exists, you'll see the a list of all the connector APIs. You can filter the list to see only the connector APIs that you're interested in or click Sort to reorder the list.

  3. Click SOAP or New Connector and select SOAP from the drop-down list.

    Each time you create a SOAP Connector API, the New SOAP Connector API dialog appears. This is where you enter the basic information for your new connector API.
    Description of soap_newapi.png follows
    Description of the illustration soap_newapi.png

  4. Identify your new SOAP Connector API by providing the following:

    1. API Display Name: Enter a descriptive name (an API with an easy-to-read name that qualifies the API makes it much simpler to locate in the list of connector APIs).

      For example, myOrderApi.

      Note:

      The names you give to a connector API (the value you enter in the API name field) must be unique among connector APIs.

      For new connectors, a default version of 1.0 is automatically applied when you save the configuration.

    2. API Name: Enter a unique name for your connector API.

      For example, myorderapi.

      By default, this name is appended to the base URI as the resource name for the connector API. You can see the base URI below the API Name field.

      The connector API name must consist only of lowercase alphanumeric characters. It can’t include special characters, wildcards, slashes /, or curly braces {}. A validation error message is displayed if you enter a name that’s already in use.

      If you enter a different name for the API here, the change will automatically be made to the resource name in the base URI.

      Other than a new version of this connector API, no other connector API can have the same resource name.

    3. WSDL Location: Enter the address of the existing SOAP service that this connector API will call. For example: http://example.com/incidentreport/reports.wsdl

      You can also copy and paste a WSDL address into this field. To ensure the WSDL you’re using is valid within the scope supported by MCS, see Troubleshooting SOAP Connector APIs.

      Note:

      When specifying a port in the URL, only standard internet access ports 80 and 443 are supported. Connection to a service can't be made using a custom port.

      You can save time by verifying that the URL you’re providing is trusted at trustedsource.org, otherwise, even if you’re connector API is configured correctly, the connection will fail. See Common Custom Code Errors.

    4. Short Description: Provide a brief description, including the purpose of this API.

      The character count below this field lets you know many characters you can add.

      After you've filled in all the required fields, click Create, which displays the General page of the SOAP Connector API dialog.

  5. Set the timeout values:
    Description of conn_timeouts.png follows
    Description of the illustration conn_timeouts.png

    • HTTP Read Timeout: The maximum time (in milliseconds) that can be spent on waiting to read the data. If you don’t provide a value, the default value of 20 seconds is applied.

    • HTTP Connection Timeout: The time (in milliseconds) spent connecting to the remote URL. A value of 0mms means an infinite timeout is permitted.

      The HTTP timeout values must be less than the Network_HttpRequestTimeout environment policy, which has a default value of 40,000 ms. To learn about environment policies, see Environment Policies.

      Note:

      If you have a mobile cloud administrator role in addition to your service developer role, you can open the policies.properties file to see the value for the network policies for the current environment from the Administrator view. Otherwise, ask your mobile cloud administrator for the values.

  6. Click Save to save your current settings.

    If you want to stop and come back later to finish the configuration, the click Save and Close. You can always click Cancel at the top of the General, Port, and Security wizard pages to cancel that particular configuration operation. You’ll be taken back to the Connector APIs page.

  7. Click Next (>) to go to the next step in configuring your connector API.

    After the basic information is provided, you can specify the interaction details for your connector.

    You can always edit your configuration when it's in a Draft state; however, after you publish your connector API, no changes can be made to it. You can make changes by creating a new version of an existing connector API. See Creating a New Version of a Connector.

Selecting a Port

The services and their associated ports that are available for the WSDL that you provided are listed on the Port page. A port is a set of actions that define the collaboration and interaction with a web service. A service defines the operations and structures of the WSDL and exposes those operations as explicit endpoints. Although a WSDL can contain multiple ports, the SOAP Connector API can only use a single port at a time. If you need to expose more than one port, you must create one SOAP Connector API for each port.

On the Port page, you select a single port that lists the available operations for that service. Optionally, you can provide alternate names for those operations to make them more meaningful or easier to read.

  1. Click the Port navigation link at the top of the SOAP Connector API wizard.
  2. Select a port from the service you want in the list.

    You can select only one port. Filter the list by entering a string in the Filter field and click the magnifying glass Image of a magnifying glass denoting the Search field.

    The endpoint field is populated with the service and port endpoint (URL) that are extracted from the WSDL. By default, the original operation name of the SOAP service is used to form the REST resource at which the functionality of the operation would be exposed by the SOAP Connector API.

    For example, an operation, CreateIncident, of the service, IncidentReport and port, ReportPort, can be mapped to the REST resource: /mobile/connector/myIncidentReportAPI/CreateIncident.

    This is the resource path to which custom code would send requests to. You could expose it differently if you wanted to, for example as the REST resource: /mobile/connector/myIncidentReportAPI/Create.

    Note:

    If you save the connector configuration without explicitly selecting a port, the first available port for the WSDL is selected for you by default. This action ensures your connector configuration is complete and valid for testing purposes. You can always change the port as long as the connector is in Draft state.
  3. (Optional) Rename one or more operations to make them more meaningful.

    All the operations available in the selected port are listed.

Each operation is mapped to the relative base URI that you entered. For example: the operation Create maps to Create resource.

Click Next (>) to go to the next step in configuring your connector API.

Setting Security Policies and Overriding Properties for SOAP Connector APIs

Select one or more security policies that describe the authentication scheme of the service to which you’re connecting. The security policies have properties, called overrides, which you can configure. One reason to override policy configuration properties is to limit the number of policies that you have to maintain: rather than creating multiple policies with slightly varied configurations, you can use the same generic policy and override specific values to meet your requirements.

You don’t need to set all the overrides for a policy; however, you should be familiar enough with a security policy to know which overrides to set.

  1. Click the Security navigation link at the top of the SOAP Connector API wizard.
  2. Select one or more security policies from the list of available policies and click the right arrow to move them to the Selected Policies list.
    For example, you might want to have wss10_message_protection_client_policy for message protection and wss_username_token_client_policy for authentication. Although you can move all the policies to the Selected Policies list, it’s unlikely that all policies are required for your connector API.

    To learn about supported security policy types for SOAP Connector APIs, see Security Policy Types for SOAP Connector APIs .

  3. Select a policy to read its description.
  4. Specify any other overrides, if applicable, to the selected policy if you don't want to use the default values.
    To override a policy property, enter or select a value other than the default. For descriptions of policy properties, see Security Policy Properties.

    To set or create a csf-key property, see Setting a CSF Key. To learn about credential keys and certificates, see CSF Keys and Web Service Certificates.

  5. Click Save to save your work or Save and Close to save your work and exit the SOAP Connector API wizard.
    Before you can test your connection, you must save your configuration. If you proceed to the testing page without saving the API configuration, you'll see a dialog asking you to save it. You can check the Always save before testing option to automatically perform a save operation for you every time you go to the Testing page.
  6. Click Next (>) to go to the next step, testing the connector API.
Setting a CSF Key

Click Keys open the Select or Create a New API Key dialog icon in the csf-key field in the Security Overrides section to open the Select or Create a New API Key dialog.

Description of conn_csfkey_dialog.png follows
Description of the illustration conn_csfkey_dialog.png

Provide an CSF key in one of the following ways:

  • Select an existing key from the Available Keys list (a description of the selected key is displayed below the list). The list displays only the basic credentials keys supported by the given policy property.

    When you select the key, its name appears in the Key Name field. Click Select to add the key. The other fields in the CSF Key Details pane are used only when creating a key.

  • Create a new CSF credentials key.

To create a new key:

  1. Click New Key.
  2. Enter a key name that is descriptive and easy-to-read. Note that after you create the key, you can’t change the key name.
  3. Enter a brief description of the key's purpose.
  4. Enter the user name and the password (the user credentials) for the service to which you are connecting. Repeat the password in the confirmation field.
  5. Click Save to add the key to the Available Keys list. You can create another key by clicking New Key or edit an existing one. Save toggles to Select allowing you to select a key in the list. Click Cancel to quit the task.
    The key name value will appear as the override value on the Security page. Note that the value of the key that you create pertains only to the environment in which it’s set.
If you want to edit some aspect of an existing credentials (CSF) key, select it from the Available Keys list and modify the fields as needed.
Setting a Web Service Certificate

Here the steps for setting the overrides for a Web Service certificate. However, for this release, don’t override the values for keystore.sig.csf.key and keystore.enc.csf.key because orakey is the only valid value for all of these certificate keys.

  1. Select a security policy.
    The properties for the policy are displayed in the Policy Overrides section.
  2. Select an alias from the drop-down list in the field for the certificate key (certificate keys are denoted by the keystore prefix) and select an alias.
    Unlike CSF Keys, you can’t modify a Web Service certificate. You can only select a different alias. Only mobile cloud administrators can create a new Web Service Certificate. If you don’t know the alias for the certificate you want, ask your mobile cloud administrator for the alias.

Testing a SOAP Connector API

Now that you've defined your connector API, you might want to verify your endpoints and ensure that you’re able to receive the expected results from the web service. Testing a connection is also an optional step but can save you time by identifying and fixing problems with your endpoints using the mock JSON body provided before you finalize the connector API.

Testing Your Connector

Now its time to validate your connector. The Test page lets you test the connection to a service using sample response data. You’ll see a list of all the operations that you defined for the port.

  1. Click the Test navigation link.
  2. Select the operation that you want to test.

    The base URI is displayed below the operation name. If you provided an alternate name for the operation, that name appears, otherwise the default operation name is shown.

  3. Click Examples to see Request, Response, and Fault payload examples (in JSON format).

    These examples are generated based on the request and response definitions in the WSDL file and can’t be edited. The request and response examples display a message body. Fault examples may show one or more faults depending on the operation. They display the error messages returned.

    For example, here is what a sample GET request looks like: 

    {
    "Header": null,
    "Body": {
            "GetIncidentById" :  {
				"IncidentId" : 2
            }
        } 
    }
}

    Here is the request in XML:

    <soapenv:Envelope 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:beta="http://xmlns.fixitfast.com/fif/beta">
   <soapenv:Header/>
   <soapenv:Body>
      <beta:GetIncidentById>
         <beta:IncidentId>2</beta:IncidentId>
      </beta:GetIncidentById>
   </soapenv:Body>
</soapenv:Envelope>
  4. (Optional) Click Add HTTP Header to add one or more HTTP headers to apply to the operation.

    You can select a predefined header or a custom header. For each header, select a header name and provide a value.

    These headers are for testing purposes only and won't be added to your SOAP Connector API configuration.

    The default format for the request body and the response body is JSON. You can set the format of one or both to XML if you prefer. See Using XML Instead of JSON.

  5. Use the sample JSON body provided to test your connector or create your XML body in the source editor. A JSON sample body that you can edit is generated for you from the operation that you’ve defined. For example:
            "Body" : {
            "CreateIncident" :  {
				"Title" : "new title",
				"EmailAddress" : "jack@oracle.com",
				"ImageLink" : "http://example.com/something"
            }
        }

    For comparison, here's what the body looks like in XML:

       <soapenv:Envelope
   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:beta="http://xmlns.fixitfast.com/fif/beta">
    <soapenv:Body>
      <beta:CreateIncident>
         <beta:Title>new title</beta:Title>
         <beta:EmailAddress>jack@oracle.com</beta:EmailAddress>
         <beta:ImageLink>something</beta:ImageLink>
      </beta:CreateIncident>
    </soapenv:Body>
   </soapenv:Envelope>

    Click in the editor and enter your own body (in JSON or XML format) if you prefer. To learn about JSON conventions and the mapping between JSON and XML, see How Does XML Get Translated into JSON?

  6. If you’ve selected a SAML-based security policy, open the Authentication section and enter your mobile user credentials for each method that you test. If you’re using default test credentials (Step 7), you can skip this step.

    With SAML-based security policies, the identity of the user making the call is propagated to the external service. For other security policies such as HTTP Basic Authentication and username token, the credentials used to authenticate with the external service are provided in the policy overrides as CSF keys. Depending on the operation you’ve defined, you may have to enter specific credentials for each operation or you might be able to use these credentials for all the methods to authenticate your connector with the service.

  7. Click Save as current mobile backend default credentials to save the user name and password you provide as the default.
  8. If you’re in the design phase of creating your connector and you just want to see if your endpoints are valid, click Default API Designer Test Credentials and select a mobile backend that you’re registered with and its version number.
    Optionally, you can enter your mobile user credentials (user name and password).

    These default test credentials are persistent across all the methods that you test. They remain valid during the current MCS session.

  9. Click Test Endpoint.

    Test Endpoint toggles to Cancel Test when you click it. If you want to stop the test for any reason, click Cancel Test.

    Click Reset to clear the fields and to change the header types and values and test body.

  10. Repeat Steps 1 through 4 for each method.
  11. Click Done when you’ve finished testing your endpoints.
    You’re returned to the Connector APIs page.
Getting the Test Results

After the test is run, the results are displayed at the bottom of the Test SOAP Connector API page. The result indicator is the response status:

  • 2xx - indicates a successful connection

  • 3xx - indicates a redirection occurred

  • 4xx - indicates a user error occurred

  • 500 - indicates an internal server error

Here's a list of the more common status codes that you'll want to use:

Code Description

200 OK

Successful connection.

401 UNAUTHORIZED

Error due to missing or invalid authentication token.

403 FORBIDDEN

Error due to user not having authorization or if the resource is unavailable.

500 INTERNAL SERVER ERROR

General error when an exception is thrown on the server side or when the service returns a SOAP fault response.

Click Request to see the metadata for the transaction, such as header information and the body of the request.

Click Response to see the details of the response returned. The response code tells you whether the connection was successful.

Test each of your operations and modify them as needed to validate your endpoints. After your connector API is tested, published, and deployed, you can go to the Connectors page to see analytical information about it, such as how often the connector is being called and what apps are using the connector. See Managing a Connector.

Getting Diagnostic Information

You can view the response code and returned data to determine if your endpoints are valid. A response status other than 2xx doesn't necessarily mean the test failed. If the operation was supposed to return a null response, a response should show a 4xx code.

By examining multiple messages, you can more easily determine where issues occur. For every message that you send, MCS tags it with a correlation ID. A correlation ID associates your request with other logging data. The correlation ID include an Execution Context ID (ECID) that’s unique for each request. With the ECID and the Relationship ID (RID), you can use the log files to correlate messages across Oracle Fusion Middleware components. By examining multiple messages, you can more easily determine where issues occur. For example, you can retrieve records from Oracle Fusion Middleware Logging using the call's ECID. From the Administration page, you can click Logs to view logging data: the connector API call received by a single MBE outbound connector API call.

Depending on your MCS access permissions, you or your mobile cloud administrator can view the client and server HTTP error codes for your API's endpoints on the Request History page allowing you to see the context of the message status when you're trying to trace the cause of an error. Every message sent has a set of attributes such as the time the event occurred, the message ID, the Relationship ID (RID), and the Execution Context ID (ECID).

To obtain and understand diagnostic data, see Diagnostics.

SOAP Connector API Design Tips

When you configure your SOAP Connector API, you want to ensure that you have a well-formed API. You want to make a valid SOAP Connector API but you should create an API that can be used and understood by others as well.

Here are some design recommendations to consider when you define a SOAP Connector API:

  • Most important, test your connector using the Test page after it’s created and at every update.

  • When setting the read and connection timeouts for the connector API, you should set them for a shorter duration than the API timeout. See API Timeouts.

  • Provide an HTTPS endpoint wherever possible.

  • When calling SOAP services protected with HTTP Basic Authentication, you should configure the appropriate security policies on the Security page and store credentials in a CSF key instead of providing the credentials from custom code.

  • While writing custom code to call SOAP Connector APIs, make use of the sample request and response payloads available in the Test page of the SOAP Connector API wizard. See Calling Connector APIs from Custom Code.

  • Keep the payload content relevant to the purpose of the connector, that is, don’t bloat the payloads by adding extraneous data. Include only pertinent data in the message body to facilitate quick transmission of the request or response.

  • When you're working with complex WSDLs, refer to How Does XML Get Translated into JSON? for a discussion of JSON translator limitations.

  • Date formats should follow the ISO-8601 International Standard for date and time: YYYY-MM_DD[THH:mm:ss.sss]Z. For example: 2014-10-07T18:35:50.123Z (see Date and Time Formats for a description of the standard).

How Does XML Get Translated into JSON?

The WSDL file, which describes the service that you want to access, is an XML-based protocol. The WSDL contains the XML schemas that define the structure of the SOAP XML requests and responses.

While XML is a standard means of defining SOAP messages, it’s cumbersome and not well-suited to data-interchange. JSON is the preferred format because it’s a lightweight and easy-to-read and write data interchange format (compared to XML). It’s much easier to handle JSON in (Node.js-based) custom code than XML. Here’s a comparison of XML and JSON features:

XML JSON

Human readable

Easier to read and write for developers and machines

Provides a structure to data making it more informative

Same as XML

Easily processed due to simplicity of data structure

Even simpler structure making it even easier to process

Structure of the data must be translated into a document structure

Structure is based on arrays and records

To make the transmission of data via SOAP Connector APIs possible, MCS uses a JSON translator. The JSON translator uses a set of mapping conventions when converting a JSON request into XML prior to passing the information to a remote service and translates the XML response back into JSON to be passed on to the mobile app.

MCS provides sample JSON messages that you can use as a template to construct JSON requests and process JSON responses. A sample payload (body), which gets created for you based on the information in the WSDL, is also translated into JSON.

If you choose to provide your own XML sample payload, then you should adhere to the mapping conventions of XML to JSON to ensure a successful translation. The next section demonstrates those mapping conventions.

XML - JSON Mapping Conventions

Oracle Mobile Cloud Service uses a XML - JSON mapping convention that is based on the Badgerfish convention. The following example shows the mapping of XML elements to JSON object properties:

XML JSON

... <Name>John</Name> ...

... { "Name" : "John" } ...

The next example shows how XML attributes are mapped to JSON object properties, with property names starting with the @ symbol:

XML JSON

<... archived="true">...</...>

... { "@archived" : true } ...

When elements have attributes defined in the XML schema, text nodes are mapped to an object property with the property name $. This is true even if at runtime the attributes do not occur:

XML JSON

... <Name archived="true">John</Name> ...

... { "@archived" : true, "$" : "John" } ...

Here you can see how nested XML elements become nested JSON objects:

XML JSON

...

<Address>

<City>Bangalore</City>

</Address>

...

{

...

"Address" : { "City" : "Bangalore" }

...

}

Here's how XML elements with maxOccurs > 1 in their schemas (that is, repeating elements) become JSON arrays:

XML JSON

...

<Name>John</Name>

<Name>Susan</Name>

...

... { "Name" : [ "John", "Susan" ] } ...

In the SOAP Connector, the Envelope root element is not required in the JSON message body. During the translation to JSON, XML root elements are dropped when converting to JSON. In the reverse direction, a root element is added when converting JSON to XML. This is done because JSON can have multiple top level object properties which would result in multiple root elements which are not valid in XML:

XML JSON

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Header>..</soap:Header>

<soap:Body>..</soap:Body>

</soap:Envelope>

{

"Header":{...}

"Body":{...}

}

This example shows you how the JSON data types (boolean, string and number) are supported. When converting XML to JSON, based on the type defined in the XML schema, the appropriate JSON type is generated:

XML JSON

...

<Integer>10</Integer>

<String>string-value</String>

<Boolean>true</Boolean>

...

{

...

"Integer" : 10,

"String": "string-value",

"Boolean": true

...

}

All namespace information (ns declarations and prefixes) is dropped when converting XML to JSON. On converting the JSON back to XML, the namespace information (obtained from the schema) is added back to the XML:

XML JSON

<RootElement xmlns="http://xmlns.oracle.com/test">

<Name>John</Name>

</RootElement>

{ "Name" : "John" }

If a property in an XML file has an empty value, the same property in the converted JSON file shows an empty string:

XML JSON

<Customer active="false">

<Name>John</Name>

<Address>

<City/>

<State>AK</State>

</Address>

</Customer>

{

"@active":"false",

"Name":"John",

"Address":{

"City":null,

"State":"AK"

}

}

In the reverse scenario, if a JSON file contains a null value, for example "City":null, the translation to XML shows an empty value: <City/>.

Mapping Limitations

The mapping is comprehensive but isn’t quite a one-to-one match. When creating a message body in JSON, there are some conditons that you should be aware of to ensure that the structure of the body is compliant with the JSON-XML mapping convention. The following constructs aren’t handled by the JSON translator.

  • A choice group with child elements belonging to different namespaces having the same (local) name. This is because JSON doesn’t have any namespace information.

  • A sequence group with child elements having duplicate local names. For example, <Parent><ChildA/><ChildB/>...<ChildA/>...</Parent>. This translates to an object with duplicate property names, which isn’t valid.

  • XML Schema Instance (xsi) attributes aren’t supported.

If you want to use a construct that isn’t supported by the translator, use XML and be sure to wrap your XML in a SOAP envelope. To learn about JSON, see Introducing JSON at http://json.org.

Using XML Instead of JSON

Using JSON isn’t required. You might prefer to use XML instead or you might encounter XML schema constructs that aren’t supported by the translator. You can still interact with the connector using XML requests and responses.

The response format is determined by the Accept header in custom code, which has a default value of application/json. To set the format of the request body, add the XML request body and set the contentType header in the custom code to application/xml; charset=utf-8. If you want the response in XML format, change the accept header value to application/xml. For example, 

/**
 *  The following example calls the 'CreateIncident' resource
 *  on a SOAP connector named '/mobile/connector/RightNow'.
 *  The request and response are in XML and not JSON.
 *
 */
var options = {
    contentType: 'appplication/xml;charset=UTF-8',
    accept: 'application/xml'
};

//Here we suppose an XML message has been
//stored in the XML variable
var body = xml;

req.oracleMobile.connectors.RightNow.post('CreateIncident', body, options).then(
  function(result){
    //result.result  contains  the response XML
    res.status(result.statusCode, result.result);
  },
  function(error){
    res.status(500, error.error);
  }
);

Remember to wrap your XML in a SOAP envelope. Your XML request must contain the entire SOAP envelope (including any SOAP headers):

<?xml version="1.0" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemad.xmlsoap.org/soap/envelope">

  <SOAP-ENV:Header>
    <!-- Add any SOAP headers here -->
  </SOAP-ENV>

  <SOAP-ENV:Body>
    <!-- Add the Body element here -->
  </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

If you configured a security policy on the connector that requires a SOAP header to be sent in the message, that header is added automatically to the envelope you provide so you don’t need to include it in your message. You can see an example of an XML request wrapped in a SOAP envelope in Testing Your Connector.

Security Policy Types for SOAP Connector APIs

You'll need to set a security policy to protect the information you want to send or receive unless the service you’re accessing isn't a secure service or doesn’t support security policies, in which case, you can’t set a security policy for the connector.

When determining what policies to set, consider whether connection to the service involves transmitting proprietary or sensitive information. A few reasons for adding security policies are:

  • Ensuring confidentiality by encrypting messages

  • Ensuring the integrity of the data transmitted by using digital signatures

  • Authenticating the source or destination

From the Security section, you can select one or more Oracle Web Services Manager (Oracle WSM) security policies, including SAML, Username Token, and HTTP Basic Authentication. Oracle WSM supports a wide range of security standards, including Authentication Policies and Authorization.

Security Policy Type Description

HTTP Basic Authentication

HTTP Basic authentication allows an HTTP user agent to pass a user name and password with a request. It's often used with stateless clients, which pass their credentials on each request. It isn't the strongest form of security though because basic authentication transmits the password as plain text so it should be used only over an encrypted transport layer such as HTTPS.

Security Assertion Markup Language (SAML)

SAML is an XML-based open standard data format that allows the exchange of authentication and authorization credentials among a client, an identity provider, and a service provider. The client makes a request of the service provider. The service provider verifies the identity of the client from the identity provider. The identity provider obtains credentials from the client and passes an authentication token to the client, which the client then passes to the service provider. The identity provider verifies the validity of the token for the service provider and the service provider responds to the client.

Username Token

A username token is supplied by a web services client as a means of identifying the requestor by using a user name, and optionally by using a password or password-equivalent to the web services provider.

Ask yourself the following questions to determine what kinds of security policies you need:

  • What are the basic requirements of your security policy? Do you need to authenticate or authorize users? Do you require only message protection, do you need both?

  • If you need only authentication, do you need a specific type of token and where will the token be inserted?

  • If you need both authentication and message protection, will message protection be handled in the transport layer?

For a list of supported security policies, see Security Policies for SOAP Connector APIs.

For descriptions of security policy properties that you can override, see Security Policy Properties.

CSF Keys and Web Service Certificates

Depending on the security policy that you selected, you may be able to override a property that sets a CSF key or a Web Service Certificate. In MCS, the Oracle Credential Store Framework (CSF) is used to manage credentials in a secure form. A credential store is a repository of security data (credentials stored as keys) that certify the authority of users and system components. A credential can hold user name and password combinations, tickets, or public key certificates. This data is used during authentication and authorization.

CSF lets you store, retrieve, update, and delete credentials (security data) for a web service and other apps. A CSF key is a credentials key. It uses simple authentication (composed of the user name and the password for the system to which you’re connecting) to generate a unique key value. You can select an existing CSF key or create one through the Select or Create a New API Key dialog. To select or create a CSF key, see Setting a CSF Key.

A Web Service Certificate allows the client to securely communicate with the web service. It can be a trusted certificate (that is, a certificate containing only a public key) or a certificate that contains both public and private key information. Web Service Certificates are stored in the Oracle WSM keystore. You set the overrides by selecting an alias from the drop-down list for the following properties:

  • keystore.recipient.alias: The alias for this property is used to identify the certificate in the keystore.

  • keystore.sig.csf.key: The alias for this property is mapped to the alias of the key used for signing. If no value is selected, the default value, orakey, is used (for this release, the only valid value for this property is orakey).

  • keystore.enc.csf.key: The alias for this property is mapped to the alias of the private key used for decryption. If no value is selected, the default value, orakey, is used (for this release, the only valid value for this property is orakey).

Not all security policies contain all three properties. When you select a policy, you can see which properties are listed in the Policy Overrides. For example, if you selected wss11_username_token_with_message_protection_client_policy, you’ll see that you need to set only keystore.recipient.alias . However, if you selected wss10_username_token_with_message_protection_client_policy, you’ll need to set all three properties.

Note:

It isn’t necessary to set all the overrides for a policy; however, you should be familiar enough with the security policies that you’ve selected to know which overrides to set for each policy.

CSF keys, certificates, and their respective values are specific to the environment in which they’re defined. That is, if there are multiple environments, A and B, and you’re working in environment A, then only the CSF keys and certificates for the security policies in use by artifacts in that environment are listed in the CSF Keys dialog. A different set of keys and certificates will be displayed in environment B. It is also possible for keys with the same key name but with different values to exist in multiple environments.

A CSF key can be deployed to another environment, however, because CSF keys are unique to an environment, only the key name and description are carried over to the target environment. You won’t be able to use that key in the new environment until it’s been updated with user name and password credentials by the mobile cloud administrator.

Editing a SOAP Connector API

If you need to change some aspect of a connector API, you can as long as it’s in the Draft state. After you publish an API, the API can’t be changed.

To edit a SOAP Connector API:
  1. Make sure that you’re in the environment containing the SOAP Connector API that you want to edit.
  2. Click side menu icon and selectApplications > Connectors from the side menu.
    Since at least one connector API exists, the Connectors page is displayed.
  3. Select the draft SOAP Connector API that you want to edit and click Open.
    You can filter the list by version number or status. You can also sort the list alphabetically by name or by last modified date.
  4. Edit the fields for general information, ports, and security policies as needed.

    Remember you can always click Save and Close to save your current changes and finish the rest of your changes later.

  5. Save your changes if you didn't select the option to always save the configuration before testing when you created the API.
  6. Test your changes.

Your edited version is still in a Draft state and you can continue to edit your connector API until you’re satisfied with the configuration. At that point, you’re ready to publish your connector API. A published connector API can’t be changed. If you need to make changes, you can create a new version of the connector API. To create a new version, publish, and deploy your connector API, see Connector Lifecycle.

Your edited version is still in a Draft state and you can continue to edit your connector API until you’re satisfied with the configuration. At that point, you’re ready to publish your connector API. A published connector API can’t be changed. If you need to make changes, you can create a new version of the connector API.

Using Your Connector API in an App

To use a connector in a mobile app, you need to have a custom API that can call the connector API. Such a custom API could also contain additional logic to process the data returned from the call to the connector.

The syntax for a call to a connector API is the same as you would use when calling any other API from custom API implementation code. See Calling Connector APIs from Custom Code.

Description of connector-calling1.png follows
Description of the illustration connector-calling1.png

When you implement a custom API, you can view the available connectors in the API Catalog tab in the API Designer. While creating your custom API, you might find it beneficial to open the Test page of the connector API so that you can refer to any headers, parameters, and schemas that you’ve configured for the connector API.

Troubleshooting SOAP Connector APIs

System message logs are great sources for getting debugging information. Depending on your role, you or your mobile cloud administrator can go to Administration in the side menu and click Logs to see any system error messages or click Request History to view the client (4xx) and server (5xx) HTTP error codes for the API's endpoints and the outbound connector calls made within a single mobile backend.

Sometimes a connection fails because the service URL provided is untrusted. You can add the URL to the list of trusted URLs at trustedsource.org. To learn more about what happens if you provide an untrusted URL and other common errors that can occur when configuring your connector API, see Common Custom Code Errors.

By default, only TLSv1.1 and TLSv1.2 protocols are used for outbound connections. If you need to use an older version of a SSL protocol to connect to an external system that doesn't support the latest versions of SSL, you can specify the SSL protocol to use for the connector by setting the Security_TransportSecurityProtocols environment policy. The policy takes a comma-separated list of TLS/SSL protocols, for example: TLSv1, TLSv1.1, TLSv1.2. Any extra space around the protocol names is ignored. You can use the SSLv2Hello protocol to debug connectivity issues with legacy systems that don't support any TLS protocol. Note that this policy can’t be used to enable SSLv3 endpoints. See Environment Policies and Their Values for a description of the policy and the supported values. Be aware that this policy must be manually added to a policies.properties file that you intend to export.

Caution:

Be aware when setting the policy that older protocols are vulnerable to security exploits.

SOAP Connector API Scope

To be sure you’re creating a valid SOAP Connector API in MCS, keep in mind the following WSDL constraints:

  • Only SOAP version 1.1 and WSDL version 1.2 are supported.

  • Only the WS-Security standard is supported. Other WS-* standards, such as WS-RM or WS-AT, aren’t supported.

  • Only document style and literal encoding are supported.

  • Attachments aren’t supported.

  • Of the possible combinations of input and output message operations, only input-output operations and input-only operations are supported. These operations are described in the Web Services Description Language (WSDL) Version 1.2 specification.