Creating a Resource Request Parameter
To add a request parameter
1. On the Resource Request pane, click the Parameter tab and then click Add... to add a resource parameter.
2. In the Create Resource Parameter dialog box, in the Style field, select the parameterization style of the request, which determines how the parameter should be used. Currently, five parameter styles are supported: Query, URI Context, Form Encoded, Record (as Query), and Internal. See the following section on Parameter Styles for more information.
CloudStreams REST connector services allow you to set parameters which become part of the outgoing request.
REST services rely on HTTP methods like GET, POST to make request to a SaaS provider, so the parameters are closely tied to these HTTP methods, where they are sent as part of these HTTP method requests.
The parameters are typically part of the HTTP URI which may be of the following format:
[scheme:][//authority][path][?query]
CloudStreams supports the following parameter styles:
Type | URI Scope |
Query | query - A simple query string parameter. |
URI Context | path - A parameterized URI context path parameter. |
Form Encoded | body - A form-encoded parameter sent as the request body. |
Record (as Query) | query - A complex record structure representation split into one or more query string parameters. |
Internal | authority - An internal configuration parameter. |
Query parameters are passed as the query component of a REST resource invocation request.
The following example demonstrates a typical HTTP GET request with parameters that form a query string of the resource URI.
GET /status?key1=value1&key2=value2 HTTP/1.1
Host: www.softwareag.com
Content-Length: 0
Notice that the parameters are added to the path after a "?", and specified as ampersand ( & ) separated list of key-value pairs, with the corresponding Content-Length set accordingly. The key and values passed as parameters are URL-encoded by CloudStreams.
A sample resource definition with Query parameter:
URI Context parameters are passed as the path component of a REST resource URI, and the parameter names correspond to the URI path variable names specified in the {} annotation. For example, a sample request might look like this:
services/async/25.0/job/{jobId}
In the above sample request, the URI path variable name jobId is specified as a parameter to the job resource. The annotation {} is set to the variable name jobId. At service run time, the variable is substituted with its runtime value to form the dynamic path.
A sample resource definition with URI Context parameter:
Parameters with style Form Encoded are passed in the body of a resource request during run time.
Note: If you create a parameter with style Form Encoded or change an existing parameter style to Form Encoded, all assignments and the document type in the request body will be removed and these changes cannot be restored.
A sample resource definition with Form Encoded parameter:
Record (as Query) is a complex record structure representation, split into one or more query string parameters.
The following is a sample resource definition with Record (as Query) parameter:
The following is a sample output of the selected query formatter after running the formatter service with the given document reference "doctypes.parameters:Filter":
Filter.FilterList.0.Name=key1&Filter.FilterList.0.Value=Value1&Filter.
FilterList.1.Name=key2&Filter.FilterList.1.Value=Value2&Filter.Name=instance-
type&Filter.Value.0=t1.micro&Filter.Value.1=m1.small
Internal parameters signify an internal contract between the connector tier and the connector-specific authentication scheme along with the virtual runtime layer.
The allowed set of parameter name, which can be specified as Internal, depends on the authentication scheme used for the connector definition.
Example
aws.bucketName is a parameter which is used by the Amazon Authentication Scheme version 3 for specifying the dynamic host based on the parameter value.
While executing a resource with such parameter, the service endpoint is prefixed with the appropriate bucket name.
3. Enter the parameter Name and the Value needed to access the resource. Select Required if you want the parameter to be made mandatory for users. Select Editable if you want the connector user to change the value.
4. If you select Record (as Query) as the parameterization style of the request, browse and select a document reference from the provider package and use the default formatter service.
a. If the parameter is a complex parameter involving indices where an IS document type is required, specify the fully qualified name of the IS document type in the Select Document Reference field.
b. If you want to add a custom formatter service, clear the Use default formatter service option and browse or type the Formatter Service name (which implemented the wm.cloudstreams.service.common.lookup.specs:formatterSpec) spec along with the name space. That is, if you have used a parameter formatter to format the input data into a custom format, specify your custom formatter service here, and then provide the input in the form of "key:value" pairs for the arguments specified in the service, if required. See Parameter Data Types and Formatters for information on parameter formatters. c. Click Next. In the Assign Parameter Formatter dialog box, if needed, enter the argument values for the parameter formatter. You can add a custom service argument by clicking the Add button. Select Preview to view a sample of the formatter service output.
5. Click Finish.
The request parameter will be added and will appear in the request parameter pane.