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.

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.

b. Click

next to Resource Name. Software AG Designer displays the Resource and Business Object Configuration wizard.

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.

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.

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.

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.

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.

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.

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

e. To delete a custom header that you added, select the header and click

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.

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.

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.

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

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.

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

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

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:

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.

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.

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.

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.

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.