Cloud Application Integration (On-Premises) : Administering CloudStreams : Creating Custom Cloud Connectors : Configuring Custom SOAP Cloud Connectors : Creating Run-Time Connections (SOAP)
Creating Run-Time Connections (SOAP)
You need to create one or more run-time connections to the SaaS provider.
To create a run-time connection (SOAP)
1. Start Software AG Designer and open the CloudStreams Development perspective by clicking Window > Open Perspective > Other > CloudStreams Development.
2. In the CloudStreams Connectors view, expand your CloudStreams Provider project and click the cloud connector you just created (as described in Creating Custom SOAP or REST Cloud Connectors).
The Overview page is displayed, showing the general information you defined in the New Cloud Connector wizard.
3. Click the Connections link in the Connector Content section of the page (or click the Connections tab at the bottom of the page).
The Connections Configuration page is displayed.
4. Create a run-time connection by right-clicking the Connections node, selecting Add Connection and assigning a name and optional description to the connection. The name cannot contain special characters.
CloudStreams creates the connection in the Connections node, and by default it will contain a Groups node.
5. Right-click on the Groups node and click Add Group. The New Group window appears. Select one or more groups in the New Group window that should be allowed to access the connection.
The Groups node contains a default group called connection. You cannot select any other types for the connection group in the Configuration page. The Type, Name, and Description of the groups are also displayed. Select the Groups, click OK, and then complete the following fields in the Configuration section of the page.
Field
Description
Name
The group name. You may rename this group.
Connection group names cannot have spaces or use special characters reserved by Integration Server or Designer. For more information about the use of special characters, see the Service Development online help.
Group Type
You can select only one instance of each group type shown below for a provider connector's connection configuration.
*oauth: This group will be used if you configure 'OAuth Tokens' in the Integration Server > CloudStreams > Administration > OAuth Tokens section.
*oauth_v10a: Indicates that the group is defined with the details of OAuth V1.0a authentication scheme.
*oauth_v20: Indicates that the group is defined with the details of OAuth V2.0 authentication scheme.
*protocol: Indicates that the group is defined with the HTTP transport protocol that the connection will use.
*connection: Indicates that the group is defined with the login endpoint to initiate communication with the SaaS provider.
*requestHeaders: Indicates that the group is defined with the names of the HTTP request headers to include when sending the login request.
*credentials: Indicates that the group is defined with a user account on the SaaS provider that the connection will use to connect to the SaaS provider.
*aws_v2: Indicates that the user will use Signature Version 2 to sign Amazon Web Services Query API requests.
*aws_s3: Indicates that the group is defined for the Amazon S3 authentication scheme and it uses the Access Key and the Secret Key of the client to authenticate the requests.
*aws_v4: Indicates that the user will use Signature Version 4 to sign Amazon Web Services Query API requests.
*custom: A user-defined group.
Description
Optional. Type a description for the connection group.
Fields
Based on the group type you selected above, CloudStreams displays the applicable fields for which you should specify values. Required fields are marked with an asterisk. Refer to the table below.
Based on the group type you selected above, CloudStreams displays the applicable fields for which you should specify values, as follows:
If the group type is...
The available fields are...
oauth
OAuth Config Alias: The alias of a configured OAuth token.
oauth_v10a
*Consumer ID: The 'Consumer Key' issued by the Service Provider and used by the consumer to identify itself to the Service Provider.
*Consumer Secret: A secret used by the Consumer to establish ownership of the 'Consumer Key'.
*Access Token: A value used by the Consumer to gain access to the Protected Resources on behalf of the User, instead of using the User's Service Provider credentials.
*Access Token Secret: A secret used by the Consumer to establish ownership of a given 'Access Token'.
oauth_v20
*Consumer ID: A 'client identifier' issued to the client to identify itself to the authorization server.
*Consumer Secret: A secret matching to the 'client identifier'.
*Access Token: A token used by the client to make authenticated requests on behalf of the resource owner.
*Instance URL: Optional field, used to specify a runtime host, if applicable. This may be required in some back ends like Salesforce.
*Refresh Access Token: Option to refresh the 'Access Token'. OAuth 2.0 access tokens typically have a very short lifetime. When an access token expires, the OAuth profile does not automatically refresh the expired access token. Select this option if you want an expired access token to be refreshed automatically. If you select this option, you must also specify the relevant refresh parameters.The access token is refreshed whenever the session expires. Session expiration is handled according to the setting of the Session Management property in your connection. Note that if Session Management is set to "none", then you must manually modify the access token in the OAuth alias. (The Refresh Access Token option will not be applicable in this case.). Default is 'false'. If you want to refresh the 'Access Token' automatically, set Session Management to either 'fixed' or 'idle'. The Timeout value should be based on the backend settings.
*Refresh Token: A token used by the client to obtain a new access token without having to involve the resource owner.
*Refresh URL: The provider specific URL to refresh an 'Access Token'. This is required when 'Refresh Access Token' is enabled, that is, configured to 'true', and the Refresh URL Request is configured to 'URL Query String' or 'Body Query String'.
*Refresh URL Request: Options for sending the parameters in the 'Access Token' refresh request.The options are 'URL Query String', 'Body Query String', and 'Custom ESB Service'. Default is 'Body Query String'.
*URL Query String: The refresh request parameters, for example, refresh_token, grant_type, and so on, and their values are sent as query strings in the URL of the POST request. Example:
www.examplebackend.com/o/oauth2/token?grant_type=refresh_token&
client_id=842428530070-pubfebfgfqkgj6t54m4ns6&client_secret=
4adQT95cAtUxWINbDxGP9SJ4&refresh_token=
1%2Fn072P4BXpuNObjCLUtiZTc4fMH6YersmxBIv8QN3bhw
*Body Query String: The refresh request parameters, for example, refresh_token, grant_type, and so on, and their values are sent as query strings in the body of the POST request. Example:
POST /o/oauth2/token HTTP/1.1
Host: accounts.backend.com
Content-length: 163
content-type: application/x-www-form-urlencoded

client_secret4adQT95cAtUxWINbDxGP9SJ4&grant_type
=refresh_token&refresh_token=1%2Fn072P4BXpuNObjC
LUtiZTc4fMH6YersmxBIv8QN3bhw&client_id=
407408718192
*Custom ESB Service: If the backend requires the refresh request in a custom format, for example, requests which need more parameters than the ones specified by OAuth v2.0, or the backend uses some custom way of organizing parameters, or expects some other HTTP method request (other than POST), use the "Custom ESB Service" option.
Refresh Custom ESB Service: User implemented service for refreshing the 'Access Token'. This is required when the 'Custom ESB Service' option is selected as the 'Refresh URL Request'. This service must strictly conform to the specification:
- wm.cloudstreams.service.common.lookup.specs:
oauthTokenRefreshServiceSpec
Authorization Header Prefix: The prefix to be used with the 'Access Token' in the Authorization header. Options are 'Bearer' and ‘OAuth’. Default is 'Bearer'.
protocol
*Element Character Set: The encoding to use for the HTTP request line, headers, etc.
*HTTP Content Character Set: The encoding to use for the request message.
*HTTP Protocol Version: The HTTP version (HTTP/0.9, HTTP/1.0 or HTTP/1.1. The default value for the connection factory is HTTP/1.1.
*User Agent: The value to the connection configuration will send for the User-Agent request header.
*Use Expect Continue: If true, use the Expect/Continue HTTP/1.1 handshake and send the Expect request header.
*Wait For Continue Time: The number of milliseconds that the connection factory's client connection should wait for a "100 Continue" response from the server.
*Strict Transfer Encoding: If true, the connection factory connection raise an exception if the "Transfer-Encoding" header is invalid.
*Use Chunking: If true, use HTTP/1.1 chunking, using a chunk size that matches the socket buffer size.
*Follow Server Redirects: If true, follow server redirects.
*Server Redirect Maximum Tries: Maximum number of times to follow a server redirect.
connection
*Server URL: The native provider endpoint target for the connection configuration. The default configuration field provided with the connection factory is cn.providerURL.
*Min Pool Connections: The minimum number of socket connections to reserve for a connection configuration alias.
*Max Pool Connections: The maximum number of socket connections to reserve for a connection configuration alias.
*Connection TimeOut: The number of milliseconds a connection attempt will wait before giving up. (0 will wait indefinitely.)
*Socket Read Timeout: The number of milliseconds in which the the client must read a response message from the server. (0 will wait indefinitely.)
*Use Stale Checking: If true, the connection factory performs additional processing to test the socket to see if it is still functional each time it is used.
*Connection Retry Count: How many times should the connection factory attempt to execute a failed invocation.
*Retry On Response Failure: If true, the retry mechanism will be used for failed responses even if the request was sent successfully.
*Use TCP NoDelay: If true, do not use Nagles algorithm as a socket optimization technique.
*Socket Buffer Size: The size of the read and write socket buffers, in bytes.
*Socket Reuse Address: If true, the socket will be reused even if it is in TIME_WAIT due to a previous socket closure.
*Session Token: Session token for a stateful session.
*Proxy Server Alias: The alias to a web proxy server configuration in Integration Server.
*Trust Store Alias: Alias for the Integration Server trust store configuration.
*Hostname Verifier: Fully qualified class name that implements the Apache HC org.apache.http.conn.ssl.X509HostnameVerifier interface; helps guard against "man-in-the-middle" attacks. Also set the IS property watt.security.cert. wmChainVerifier.trustByDefault to false and ensure the outbound connector's connection configuration property Hostname verifier is set to its default value, org.apache.http.conn.ssl.StrictHostnameVerifier.
*Socket Linger: Determines how quickly a socket should close.
requestHeaders
*Request Header Names: An array of request header names to include for this connection configuration. The value should be a comma-delimited list of header names; for example Content-Type,SOAPAction.
*Request Header Values: An array of request header values to include for this connection configuration. The value should be comma-delimited list of values in the same order as the header names; for example, text/xml,login.
credentials
*Username: The username credentials for the current connection configuration.
*Password: The password credentials for the current connection configuration
*Preemptive Auth: If true, basic auth credentials will be included when a request is sent. (It will not wait for a 401 response challenge.)
Note:  
While using connections with basic auth credentials, it is recommended to set the value of Preemptive Auth field as “true”. This will send the required headers and it may not be required to handle a response challenge.
*Authorization Type: The string identifying the authentication protocol scheme to use for the connection configuration.
*Domain Name: The domain/security realm for the current connection configuration.
*Keystore Alias: Alias for the Integration Server key store configuration.
*Client Key Alias: Alias to reference a key inside a key store file.
custom
User-defined fields of a custom group.
Connection Management Properties
*Enable Connection Pooling: Whether connection pooling is enabled for a connection. Valid values: true: Connection pooling is enabled for this connection. false: Connection pooling is disabled for this connection. Default: true.
*Initial Pool Size: The minimum number of connection objects that remain in the connection pool at all times, if connection pooling is enabled. When the connector creates the pool, it creates this number of connections. Default: 1.
*Maximum Pool Size: The maximum number of connection objects that can exist in the connection pool if connection pooling is enabled. When the connection pool has reached its maximum number of connections, the connector will reuse any inactive connections in the pool, or, if all connections are active, it will wait for a connection to become available. Default: 10.
*Pool Increment Size: The number of connections by which the pool will be incremented, up to the maximum pool size, if connection pooling is enabled and connections are needed. Default: 1.
*Block Timeout (msec): The number of milliseconds that Integration Server will wait to obtain a connection with the SaaS provider before the connection times out and returns an error. For example, you have a pool with Maximum Pool Size of 20. If you receive 30 simultaneous requests for a connection, 10 requests will be waiting for a connection from the pool. If you set the Block Timeout to 5000, the 10 requests will wait for a connection for 5 seconds before they time out and return an error. If the services using the connections require 10 seconds to complete and return connections to the pool, the pending requests will fail and return an error message stating that no connections are available. If you set the Block Timeout value too high, you may encounter problems during error conditions. If a request contains errors that delay the response, other requests will not be sent. This setting should be tuned in conjunction with the Maximum Pool Size to accommodate such bursts in processing. Default: 1000.
*Expire Timeout (msec): The number of milliseconds that an inactive connection can remain in the pool before it is closed and removed from the pool, if connection pooling is enabled. The connection pool will remove inactive connections until the number of connections in the pool is equal to the Initial Pool Size. The inactivity timer for a connection is reset when the connection is used by the connector. This setting should be tuned in conjunction with the Initial Pool Size to avoid excessive opening/closing of connections during normal processing. Default: 1000.
*Startup Retry Count: The number of times that the system should attempt to initialize the connection pool at startup if the initial attempt fails. The retry mechanism is invoked only when the connection is configured correctly, but the target server URL cannot be reached or a network issue occurs while attempting to initialize the connection. Default: 0 (a single attempt).
*Startup Backoff Timeout (sec): The number of seconds that the system should wait between attempts to initialize the connection pool. This value is ignored if Startup Retry Count is 0. Default: 10.
*Session Management: The type of timeout for the connection session. Select the type of session management that fits the requirements of your SaaS provider backend. It is recommended that you set this field to idle if you want the CloudStreams server to manage the session. Valid values: none: The CloudStreams server does not manage session timeout. The session times out based on the settings of the SaaS provider backend.
idle: If no activity happens for the time specified in Session Timeout, the session times out. If the session is not idle (it is used actively), the session will not timeout.
The CloudStreams server takes into account the idle timeout. For example, if the session is idle for the time specified in Session Timeout, the server renews the session before making the service call.
fixed: The session will timeout at a fixed time interval (specified in Session Timeout) irrespective of the session usage or current activity. The CloudStreams server renews the session as soon as the fixed timeout value expires.
*Session Timeout (min): The maximum number of minutes a session can remain active (in other words, how long you want the server to wait before terminating a session). The value should be equal to the session timeout value specified at the SaaS provider backend.
6. Add additional connection groups, if desired, by right-clicking the Connections folder and selecting Add Group.
7. If your provider requires a Login Sequence, configure it as follows:
a. Right-click the Login Sequence node and select Add Operation. The Login Sequence/Logout Sequence will be enabled for SOAP based connections only if you have configured any Login/Logout Operation under Services. The Login Sequence/Logout Sequence will be enabled by default for REST based connections.
b. Right-click the login operation under the Login Sequence node and select Add Mapping
c. In the Configuration section of the page assign a name to the sequence (for example XYZSoapService:login), select the Login operation and optionally enter a description.
A Mapping node is added under the login operation.
d. Now the Configuration section of the page shows the document types that were generated for the login service WSDL for the request and response messages. Define the mappings by inserting values into the request message or extracting values from the response message as needed. For the Salesforce.com connector, for example, the username and password values are inserted into the request message by selecting the configured values that are defined in the managed connection page. Then, the session token and a server URL are extracted from the response message to be inserted into special connection factory fields. These fields are used when invoking any of the Simple or Complex operations.
e. Right-click a request message field you want to map (for example, HDR1:username) and select Set configuration.
f. In the Set Configuration dialog that appears, complete the following fields.
Field
Description
Name
Assign a name to the mapping.
Type
Select the data source type:
*Cookie: HTTP cookies. For example, the Salesforce.com connector inserts the session token from a valid login in the SOAP header of the business operations to be executed. Other providers do the same thing; however, the token is managed via cookies instead of the SOAP header.
*Header: Request or response HTTP transport headers for the support connection factory implementation.
*IData: IData is a variable name that is associated with the connection instance when the service is invoked. It is a subset of those configuration fields from the selected groups. Not all fields are eligible for use as a mapping step since their values may not be changed or have any useful meaning in this context.
*Literal: A constant value.
*Parameter: Primarily used for REST handlers.
*Service: The Service type applies to the source, not to the target. Select Service if you want the source to call a given service to perform certain tasks and to map the output of the service to a target. The service must adhere to wm.cloudstreams.service.common.lookup.specs:mapServiceSpec. If an error occurs related to service validation or execution, CloudStreams throws a Mapping Exception.
*XPATH: Enables you to define an XPath expression.
Value
If you selected the Service type, the Value field's drop-down list will display all services that conform to the specification wm.cloudstreams.service.common.lookup.specs:mapServiceSpec. When you choose a service, the Formatter Service Arguments Configuration dialog appears, where you can add/delete/reset the input details specified in the service and specify arguments.
If you selected a different type, choose the appropriate value from the drop-down list (for example, the connection user name key field cr.username).
g. Click OK.
A green check mark is shown next to the request message field you just mapped.
8. Configure a Logout Sequence step in a similar manner. The Login Sequence/Logout Sequence will be enabled for SOAP based connections only if you have configured any Login/Logout Operation under Services. The Login Sequence/Logout Sequence will be enabled by default for REST based connections.
9. Next, configure your cloud connector services, as described below.
Copyright © 2015- 2017 Software AG, Darmstadt, Germany. (Innovation Release)

Product LogoContact Support   |   Community   |   Feedback