Creating Run-Time Connections (REST)
You need to create one or more run-time connections to the SaaS provider.
To create a run-time connection (REST)
1. Start Software AG Designer and open the CloudStreams Development perspective by clicking Window > Open Perspective > Other > CloudStreams Development.
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).
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 the connection will contain a Groups node.
5. Right-click on the Groups node and click Add Group to 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 complete the fields in the Configuration section of the page as follows.
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 Designer Service Development online help. |
Group Type | Only one instance of each group type shown below may be selected 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 authentication type OAuth V1.0a. oauth_v20: Indicates that the group is defined with the details of authentication type OAuth V2.0. 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_v4: Indicates that the user will use Signature Version 4 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. 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 an OAuth token that was configured in Integration Server Administrator. For details, see webMethods Integration Server Administrator’s Guide. |
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 (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%2Fn072P4BXpuNOb
jCLUtiZTc4fMH6YersmxBIv8QN3bhw&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. Flow 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 Linger: Determines how quickly a socket should close. |
| 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. |
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. |
aws_v2 | Signing Algorithm: Explicitly specify the signing algorithm (e.g. HMAC-SHA1 Signatures) used to sign the message. Access Key: This is a username. It is an alphanumeric text string that uniquely identifies the user who owns the account. No two accounts can have the same AWS Access Key. Secret Key: This key plays the role of a password. It is called secret because it is assumed to be known only by the owner. When you type the secret key, it is displayed as asterisk or dots. Region: An area-specific value. |
aws_s3 | Access Key: This is a username. It is an alphanumeric text string that uniquely identifies the user who owns the account. No two accounts can have the same AWS Access Key. Secret Key: This key plays the role of a password. It is called secret because it is assumed to be known only by the owner. When you type the secret key, it is displayed as asterisk or dots. Region: An area-specific value. |
aws_v4 | Access Key: This is a username. It is an alphanumeric text string that uniquely identifies the user who owns the account. No two accounts can have the same AWS Access Key. Secret Key: This key plays the role of a password. It is called secret because it is assumed to be known only by the owner. When you type the secret key, it is displayed as asterisk or dots. Region: An area-specific value. |
custom | User-defined fields of a custom group. |
You can create additional connection groups by right-clicking the Connections node and selecting Add Group.
6. If your provider requires a Login Sequence, configure one as follows:
a. Right-click the Login Sequence node, select Add Resource, select the Type Login, and click Next. 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. Configure a Login resource by completing the following fields.
Field | Description |
Name | Specify a name for the Login resource. |
Document Reference | Click Browse and select a Document Reference. |
Content Type | Specify the Content-Type of the Document Reference. |
c. Click Next.
d. Create a Request for the Login resource by completing the fields as follows.
Field | Description |
Name | Specify a name for the Request. |
Document Reference | Click Browse and select a Document Reference, for example myConnector_v1.customDoctypes:docTypeRef_LoginInput. |
Content Type | Specify the Content-Type of the Document Reference, for example, application/xml. |
e. Click Next.
f. Create one or more Responses for the Login resource by completing the fields as follows.
Field | Description |
Name | Specify a name for the Response. |
Document Reference | Click Browse and select a Document Reference, for example myConnector_v1.customDoctypes:docTypeRef_LoginOutput. |
Code | Specify a code for the Response, such as 201 or 400. Response codes should be comma separated. |
Content Type | Specify the Content-Type of the Document Reference for example, application/xml. |
g. Click Next.
h. Create one or more parameters for the Login resource by completing the fields as follows.
Field | Description |
Name | Specify a name for the parameter. |
Active | Specifies whether the parameter is active. If the Active option is disabled, CloudStreamswill not include the parameter in the input/output signature at runtime. |
Parameter Type | Select the parameter's type which determines how the parameter should be used, for example, URI_CONTEXT, QUERYSTRING_PARAM, CFG_PARAM, and so on. For a list of the supported parameter types, see Parameter Types. |
Default Value | Specify a default value for the parameter. In pipeline, and input/output validation, the data validation applies constraints to its variables. Designer displays small symbols next to a variable icon to indicate validation constraints. For more information about icons for constrained variables, see Viewing the Constraints Applied
to Variables. |
Description | Optional description of the parameter. |
i. Click Finish.
j. Define the input/output mappings for the Login Sequence by right-clicking the Login Sequence name, selecting Add Mapping, and completing the fields as follows.
Field | Description |
Parameter Type | Select IN or OUT. |
Mapping fields | For example, for input fields, you might enter the display names Username and Password, and the values cr.username (the connection user name key field) and cr.password, respectively. And for output fields, you might enter the following display names and values: Server URL (with value cx.serverUrl). Provider URL (with value cn.providerUrl). Session Token (with value cn.sessionToken). Fault String (with value cx.faultString). |
7. Configure a Logout Sequence in a similar manner.
8. Next, configure your cloud connector services, as described below.
