Configuring Cloud Connector Services (REST)

Cloud Application Integration (On-Premises) : Administering CloudStreams : Creating Custom Cloud Connectors : Configuring Custom REST Cloud Connectors : Configuring Cloud Connector Services (REST)

In this task, you will configure the cloud connector service you just created in the New Cloud Connector wizard. You need to create at least one cloud connector service for each REST resource on which the connector can operate.

To configure a cloud connector service (REST)

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 wizard.

3. Click the Services link in the Connector Content section of the page (or click the Services tab at the bottom of the page).

If you already defined a cloud connector service on page 2 of the New Cloud Connector wizard, the Services Configuration page will show your new service and the default node Resources.

If you did not define a cloud connector service on the New Cloud Connector wizard, define it now by right-clicking the Services node, selecting Add Service and specifying the SaaS provider's XSD that CloudStreams will use to generate the document types. For a description of the Document Type Package field, see Creating Custom SOAP or REST Cloud Connectors.

4. Define any necessary global mappings to be used by all the REST resources in the service. To do this, right-click the service, select Add Global Mapping and complete the fields as follows.

Field	Description
Name	Assign a name for the global mapping.
Description	Enter a description for the global mapping.
Parameter Type	Select IN or OUT.
Required	Specify whether this is a required mapping.
Fixed	A Fixed mapping means its values cannot be changed at run time.
Mapping Key- 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.
Mapping Key-Key	Enter the source mapping key. For example, if your source mapping type is IData, you might enter the source mapping key cn.sessionToken.
Mapping Value- Type	Select the target mapping type: Cookie Header IData Literal Parameter Service XPath
Mapping Value- Key	Enter the target mapping key. For example, if your target mapping type is Header, you might enter the target mapping key X-SFDC-Session.
Document Name	The document type, based on the XSD.

5. Add a REST resource by right-clicking the Resources node, selecting Add REST Resource and completing the following fields in the wizard.

Field	Description
Name	Assign a name for the resource.
Method	Select an available HTTP method (GET, PUT, POST, DELETE, and so on).
Path	Specify the path to the resource.
Description	Optional description for the resource.

6. Click Next.

7. Add a Request to a REST resource by completing the fields as follows.

Field	Description
Request Name	Specify the request name, for example tns:jobInfo.
Incoming Parsing Type	The Content-Type of the request, for example, application/octet+idataoref.
Outgoing Serialization Type	The Content-Type for the response, for example, application/xml.
Document Reference Type	Click Browse and select a document reference. For example, myConnector_v1.doctypes:docTypeRef_tns_JobInfo.
Exclude document root	Select this option to exclude the root element of the JavaScript Object Notation (JSON) document type, for REST resource’s request and response.

8. Click Next.

9. Add one or more Responses to a REST resource by completing the fields as follows.

Field	Description
Response Name	Specify the request name, for example tns:jobInfo.
Response Codes	Specify one or more codes for the response, such as 201 or 400. Response codes should be comma separated.
Incoming Parsing Type	For example, application/xml.
Outgoing Serialization Type	For example, application/octet+idataoref.
Document Reference Type	Click Browse and select a document reference. For example, myConnector_v1.doctypes:docTypeRef_tns_JobInfo or myConnector_v1.doctypes:docTypeRef_tns_Error.
Exclude document root	Select this option to exclude the root element of the JavaScript Object Notation (JSON) document type, for REST resource’s request and response.

10. Click Next.

11. Select the predefined input parameters for the REST resource as desired. Note that:

Mandatory parameters are selected by default and you cannot deselect them.

You can provide a default value for any parameter by typing a value in the Default Value field. If the variable is null in the input pipeline, this default value will be used at run time. The value given at run time always takes precedence over the default value. However, if the existing default value is of type "fixed default", the overwrite will fail.

Parameters have various data validation constraints that apply to them. These constraints are indicated by an icon next to each parameter. For information about these constraints, see Viewing the Constraints Applied to Variables.

12. Optionally create additional input parameters for the REST resource by clicking the Add button and completing the following fields.

Field

Description

Name

Specify a parameter name.

Description

Optional description of the parameter.

Required

Specifies whether the parameter is required.

Document Reference Type

For QUERYSTRING_PARAM type parameters only.

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.

Formatter Service

For QUERYSTRING_PARAM type parameters only.

If you have used a parameter formatter to format 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.

For details about parameter formatters, see Parameter Formatters for REST Connector Services.

Style

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 more information about the supported parameter types, see Parameter Types.

Default Value

Specify a default value for the parameter. If the variable is null in the input pipeline, this default value will be used at run time. The value given at run time always takes precedence over the default value. However, if the existing default value is of type "fixed default", the overwrite will fail.

Note:

13. Click Finish.

14. Define the local mappings for the REST resource by right-clicking the resource name, selecting Add Mapping and completing the fields as follows.

Field	Description
Name	Assign a name for the local mapping. This mapping will be used only by this particular resource.
Description	Enter a description for the resource.
Parameter Type	Select IN or OUT.
Required	Specify whether this is a required mapping.
Fixed	A Fixed mapping means its values cannot be changed at run time.
Mapping Key- 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.
Mapping Key-Key	Enter the source mapping key. For example, if your source mapping type is Literal, you might enter the key application/xml.
Mapping Value- Type	Select the target mapping type: Cookie Header IData Literal Parameter Service XPath
Mapping Value- Key	Enter the target mapping key. For example, if your target mapping type is Header, you might enter the key Content-Type.
Document Name	The document type, based on the XSD.

15. View the Manifest node, which shows read-only fields containing attributes whose values were captured from your cloud connector definition. The version of the CloudStreams CloudStreams Development Plug-in (Created-By) is also displayed. For imported plug-ins created in a Designer release prior to 9.7, this information is not shown.

Contact Support | Community | Feedback