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, the 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 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 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. 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, 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: 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, Designer displays different Business Object panels based on the scenarios mentioned in the Single or Multiple Resources and Multiple Business Objects with dependencies section.
d. In the Select the Business Object page, select a business object and click Next.
Note: 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. Designer displays a confirmation message. Click OK to update the resource. 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 cloud connector service’s output signature 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, 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.
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.
4. On the Headers tab, 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, Designer displays the configured resource parameters. In order to customize the parameters, do the following:
a. Review the details about the resource parameters. 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.
Currently, three parameter styles are supported: URI_CONTEXT, QUERYSTRING_PARAM and CFG_PARAM.
For more 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 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.
7. 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 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.
8. On the Summary tab, review the details about the cloud connector service.
9. On the Comments tab, enter descriptive comments or usage notes, if any.
10. Click File > Save to save your changes.
