Editing a Cloud Connector Service for a REST-Based Provider
Editing a cloud connector service for a REST-based provider consists of specifying the resource, the type of processing for requests or responses, the headers to include in the service, send a multipart/form-data payload which contains either a file, or text, or a document type, input/output signature that determines how the user interacts with the service, default values for parameters included in the input/output signature, and descriptive comments or usage notes, if any. You edit a cloud connector service using the service editor in Software AG Designer.
Keep the following points in mind when editing a cloud connector service:
webMethods CloudStreams provides a default connector virtual service for policy enforcements, called WmCloudStreams.RestVS. If this service does not meet the needs of your
CloudStreams project, ensure that an appropriate connector virtual service has been created for your project. For more information about
CloudStreams connector virtual services, see
Administering webMethods CloudStreams.
In pipeline, document, and input/output validation, the data validation applies
constraints to its variables. Constraints are the restrictions on the structure or content of variables. For more information about icons for constrained variables, see
Viewing the Constraints Applied to
Variables.
To edit a cloud connector service for a REST-based provider
1. Open Software AG Designer if it is not already open.
The service opens in the cloud connector service editor.
3. On the Resource tab, do the following:
a. From the Connector Virtual Service list, select the connector virtual service to be used for policy enforcements.
For more information about CloudStreams connector virtual services, see Administering webMethods CloudStreams.
b. Click 
next to Resource Name. Software AG Designer displays the Resource and Business Object Configuration wizard. c. Select the REST resource you want the cloud connector service to process, and then click Next.
When you change a resource, Software AG Designer clears all the metadata that were associated with the previously selected resource, including the headers, parameters, and data types of fields. You can select the metadata that the updated resource requires in the next steps.
Note:
Software AG Designer displays the appropriate pages of the Resource and Business Object Configuration wizard depending on whether the selected resource requires metadata, such as a business object, fields, and data types of fields. Further, Software AG Designer displays different Business Object panels based on the scenarios mentioned in the Single or Multiple Resources and Multiple Business Objects with dependencies section.
Single or Multiple Resources with Multiple Business Objects with dependencies
Designer displays different Business Object panels based on the following scenarios:
Note:
Examples of Interactions (resources) are Create, Update, Upsert, and Delete. Examples of Objects are Contact, Account, and so on. Requires are dependencies, that is, a business object is dependent on another business object.
Single Resource has a single Business Object - This panel appears if a resource has only a single business object. The resource has neither multiple interactions nor has records. Only the object is displayed in the panel. An example of a single resource and a single object can be a "create" resource that contains only the "contact" business object.
Single Resource has multiple Business Objects - This panel appears when a single resource has multiple business objects. The panel has an
optional Record Number column (may not appear for some resources) and an Objects column. An example of a single resource with multiple business objects can be a "create" resource that contains two business objects, "contact" and "account".
Single Resource has multiple Business Objects with dependencies - This panel appears when a single resource has multiple business objects and some of the business objects may have dependencies on other business objects. The panel has Record Number, Objects, and the Requires columns. Here, you can set dependencies on the records appearing at a lower level, for example, record 3 can be dependent on (requires) record 1 or record 2.
Multiple Resources have multiple Business Objects - This panel appears when multiple resources have multiple business objects. The panel has an
optional Record Number column (may not appear for some resources), an Interactions column, and an Objects column. For example, the "create" and "update" resources can act on the "account" and "contact" business objects respectively.
Multiple Resources have multiple Business Objects with dependencies - This panel appears when multiple resources have multiple business objects and some of the business objects may have dependencies on other business objects. The panel has the Record Number, Interactions, Objects, and Requires columns. For example, the "create" and "update" resources can act on the "account" and "contact" business objects respectively. Also, you can set dependencies on the records appearing at a lower level, for example, record 3 can be dependent on (requires) record 1 or record 2.
d. In the Select the Business Object page, select a business object and click Next.
Note:
Software AG Designer displays nested, hierarchical, or multi-level business objects if the resource is designed to support nested business objects. You can expand the nested business objects to display the child-level objects.
e. In the Select Fields page, specify the fields or parameters to use in the request/response body for the object.
The mandatory fields or parameters for the business object are selected by default, and cannot be cleared.
f. You can add new custom fields as a String, String list, String Table, Document, Document list, Document reference, Document reference list, Object, and Object list by clicking 
and entering the custom field details in the Add a new custom field dialog box. You can add custom fields only for the operations that support custom fields. Custom field names should be unique within the available fields. While adding a custom field as the child of another custom field, the field name must be unique among all the children of the parent field. The following table lists the different toolbar buttons available in the Select Fields page: Select... | To... |
| Collapses all of the expanded fields. |
| Add a new custom field. |
| Edit a custom field. |
| Delete a custom field. |
| Move a custom field down in the list. |
| Move a custom field up in the list. |
| Promote a custom field in the hierarchy (that is, move the field one level up in the hierarchy). |
| Demote a custom field in the hierarchy (that is, make the selected custom field a child of the preceding parent custom field). |
g. If you want to configure concrete types for the abstract types in the resource you selected, click Next. If the resource you selected does not have any abstract type field, click Finish.
h. In the Configure Data Types of Fields page, select a value from the list of values next to the abstract type to configure concrete types for the abstract types in the resource.
i. Click Finish. Software AG Designer displays a confirmation message. Click OK to update the resource. Software AG Designer replaces the existing resource and associated metadata with the updated or default information.
j. In the Request Processing section, select an appropriate parsing type. The parsing type determines how the service accepts the input.
Option | Meaning |
Document | Builds the request message as an IS document type. Select this option when the provider’s XML file includes a schema or specification describing the content of the request. |
Binary Stream | Builds the request message as a binary stream. Select this option when you expect the pipeline to contain an input stream for which no document type exists or when it is not practical to provide a schema description of the content. For example, the content that is posted for the Salesforce.com “createBatch” resource has a complex structure of fields and rows. A batch of new accounts can be created, and each account can have dozens of fields with precise formatting requirements (for example, date fields). Attachments can even be included in the batch file. The stream option is the best option for this type of resource. |
Note:
If the resource you selected does not contain any requests or responses, the Request Processing or Response Processing fields are not available.
k. In the Response Processing section, select an appropriate serialization type. The serialization type constructs the output signature of the cloud connector service and determines how the cloud connector service should return data to the user.
Option | Meaning |
Document | Formats the response message as an IS document type. Select this option when the provider’s XML file includes a schema or specification describing the content of the response. |
Binary Stream | Formats the response message as a binary stream. Select this option when you expect the pipeline to contain an output stream for which no document type exists or when it is not practical to provide a schema description of the content. Note:
This option works in conjunction with the response’s parsing type property. If you select Stream as the response’s serialization type, Software AG Designer also selects Stream as the response’s parsing type. |
Note:
If the resource you selected does not contain any requests or responses, the Request Processing or Response Processing fields will not be available.
4. On the Headers tab, Software AG Designer displays the default HTTP transport headers for the resource, along with their default values. At run time, while processing the headers, webMethods CloudStreams substitutes values as necessary, for example, replaces the “cn.sessionToken” value in the X-SFDC-Session header with the actual runtime session ID. In order to customize the headers, do the following:
a. To specify a default value for the header variable, click the Default Value box to the right of the variable and type or paste the new value. If the variable is null in the input pipeline, this value will be used at run time. If the variable has an existing default value defined in the cloud connector descriptor, this value will overwrite the existing value at run time. However, if the existing default value is of type “fixed default”, the overwrite will fail as mentioned earlier.
b. To add a custom header to the service’s input pipeline, in the Input section of the tab, click . Type a name for the header and provide a default value if desired. c. To move a header up in the list, select the header and click 
. To move a header down in the list, select the header and click 
. d. To include a header as part of the service signature, select the Active check box next to the header.
e. To delete a custom header that you added, select the header and click 
. Note:
You cannot delete the resource’s required headers.
f. Repeat the above steps in the Output section of the tab to select the HTTP transport protocol headers whose contents you want to add to the service’s output pipeline.
Note:
A provider’s response headers only appear in the pipeline signature if they are added as active output headers in the Output section. Any unspecified headers returned by the native provider will not be included in the pipeline.
5. On the Parameters tab, Software AG Designer displays the configured resource parameters. In order to customize the parameters, do the following:
a. Review the details about the resource parameters. Software AG Designer displays the parameter name and description, the data type used to represent the kind of information the parameter can hold, the parameterization style of the request, and the dynamic default value needed to access the resource.
For information about the supported parameter styles, see the section Understanding REST Parameters in the document Administering webMethods CloudStreams.
b. To specify a default value for the parameter, click the Default Value box to the right of the parameter. Then, type or paste the default value. The default value is used at run time, if the parameter value is not explicitly specified in the input pipeline. Also, this default value will overwrite any existing default value that is defined in the cloud connector descriptor, at run time. However, if the existing default value is of type “fixed default”, the overwrite will fail as mentioned earlier.
Note:
You cannot specify a default value for a parameter with data type as Record.
6. On the Attachments tab, Software AG Designer displays the configured parts to be sent to the service provider. You can send a multipart/form-data payload which contains either a file, or text, or a document type.
Note:
All options including the Add Part option are disabled if the resource is not of type multipart/form-data. Currently, multipart/form-data payload is supported only at the request level, that is, only in the input signature.
a. To add a part, click the Add Part icon . b. In the Part Configuration dialog box, select the part type.
File - Represents a part of a multipart/form-data payload whose content will be the content of a file. To upload a file, you will normally use this part. In the
Name field, type the name of the file part as documented in the SaaS provider API documentation. The
Name field is mandatory. In the
Content Type field, type the content type of the file you are uploading. If you do not give any value, the default value will be set as application/octet-stream. In the
File Name field, type the file name by which you want the file to be uploaded. If you do not give any value, the default value will be set as attachment.
Text - Represents a part of a multipart/form-data payload whose content will be text. You can use this part to send raw text data as the content of a part, in a multipart request. In the
Name field, type the name of the file part as documented in the SaaS provider API documentation. The
Name field is mandatory. In the
Value field, type the value of the part. If you do not give any value, an empty string will be set as the default value.
Document - Some back ends expect application/json or application/xml content in the part body. To create such parts, select the
Document type part. In the
Name field, type the name of the file part as documented in the SaaS provider API documentation. In the
Content Type field, type the content type of the body part that you want your document to be serialized and sent to the back end. For the
Document field, first create a document that matches the payload and then select that document. The
Name,
Content Type, and
Document fields are mandatory.
c. Click Finish to create the part. The part will appear in the Attachments panel.
d. Select the Active check box next to the part to include it as a part of the service signature.
e. To move a part up in the list, select the part and click . To move a part down in the list, select the part and click . f. To change the Part ID for a part, click the Part ID box and type or paste the new value.
g. To delete a part that you added, select the part and click . Note:
To show the fields with fixed values in the input signature, select the Show variables with fixed values option in the Preferences screen in Service Development (Service Development perspective > Window > Preferences > Software AG > Service Development).
Example
If you want to send a payload of type multipart/form-data containing a file and text to a SaaS provider, do the following:
a. See the SaaS provider API documentation to get the part information and then define the parts that can be sent to invoke the file upload API of the SaaS provider. Name the parts as:
files of type
File.
folder_paths of type
Text.
b. Open Software AG Designer and create a cloud connector service.
c. On the Attachments tab, add the parts according to the type and select the Active check box next to the parts to include the parts as part of the service signature.
d. Run the cloud connector service to send the multipart/form-data payload to the SaaS provider.
Note:
For more information about the multipart feature, see the Administering webMethods CloudStreams document.
7. On the Connection tab, select Use inline connection to run the cloud connector service by passing connection details that are different than the connection details configured in the connection configuration page in webMethods Integration Server Administrator. For example, you have two accounts X and Y in a SaaS provider and you have configured a connection using the details of account X. Also, you have a cloud connector service which uses this connection (account X). You can run the same cloud connector service by using the details of account Y instead of creating a separate connection.
While designing the cloud connector service, select the Use inline connection option to enable the Connection panel. Then select the fields you want to include in the cloud connector service input signature in the Connection panel. When you select the fields, the cloud connector service input signature will be automatically updated based on your selections. Only the fields that are part of the signature gets mapped as the input request. You can override their values at run time. Default values will be used for other fields for creating the connection. The details specified in the Connection panel takes precedence over the details specified in the connection configuration page in webMethods Integration Server Administrator.
Note:
All
required and encrypted fields, for example, user name and password are selected by default and all
encrypted fields, for example, Password appear shaded in the
Connection panel.
Required fields appear in normal text and optional fields appear in bold text. If a field is selected, you can still edit its default value.
Encrypted fields do not have a value in the default value column. You can select or clear all fields except the encrypted fields.
You cannot clear an
encrypted field. Further, you cannot enter a value for encrypted fields. You can enter the values for encrypted fields only while running the cloud connector service.
In the cloud connector service input signature (Input/Output panel),
$Connection fields having default values are shown with the blue triangle icon.
While running the cloud connector service, if you have provided both the connection alias and the inline connection details,
CloudStreams reads the data from the connection alias and merges the connection alias data with the data provided in the inline connection, without modifying the existing configuration of the connection alias.
While running the cloud connector service, if you pass incorrect values in the inline connection section, the service execution will fail as it will not consider any existing connections.
While running the cloud connector service with connection alias and inline connection, and if you pass incorrect values to the inline connection or in the connection alias, the service execution will fail.
Some back ends, for example, SuccessFactors, expect the same session ID to be passed while invoking two operations, for example, query and queryMore. For such back ends, dynamic authentication is not supported.
8. On the Input/Output tab, do the following:
a. To have the server validate the input to the service against the service input signature, select the Validate input check box.
b. To have the server validate the output to the service against the service output signature, select the Validate output check box.
c. Review the service’s input and output signature and make any necessary changes as follows:
To change the... | Go to the... |
List of headers in the requestHeaders or responseHeaders section, or their default values | Headers tab |
Default value of a parameter in the parameters section, or their default values | Parameters tab |
The requestBody and responseBody sections are derived from the REST resource you selected on the Resource tab. The value of $connectionAlias is derived from the connection pool you specified when you first created the cloud connector service. The status, statusMessage, and fault values are derived from the resource response. You cannot change these values in the editor.
9. On the Logged Fields tab, do the following:
a. Select the check boxes next to the fields you want to log at run time.
b. If you want to create an alias for a logged field to make it easier to locate in Software AG Designer, click the Alias box next to a field and type the alias name.
For more information about logged fields, see the section on logging input and output fields in Designer.
10. On the Summary tab, review the details about the cloud connector service.
11. On the Comments tab, enter descriptive comments or usage notes, if any.
12. Click File > Save to save your changes.
