Web Service Consumer object

The Web Service Consumer object is used to request and process information or activity from a provider through the use of request messages. How this request message must be structured should be made available to you by the actual provider of that service.

CIC currently supports both SOAP/WSDL and REST methods. The WSC object using REST references a single Service.

Web Service Consumers and the API Consumer Endpoint (in Cockpit)

API Consumer Endpoints are auto-generated in the CIC Cockpit when Web Service (WS) Consumer objects are created in CIC Studio and deployed to the Integration Server. Multiple WS Consumer objects referencing the same host and vault alias value are combined into a single API Consumer Endpoint, which can be viewed from the Jobs page. See API Consumer Endpoint for more information.

How to create a Web Service Consumer (REST)

When creating a Web Consumer (REST) object, you define different options and settings. This includes the URL location of the service, as well as the HTTP methods to be used. Once saved the Web Service Consumer object can be called as a Business Process task.

Create a Web Service Consumer to create and configure the objects that are used to request and process information or activity from a provider through the use of request messages.

1. Select File > New > Web Service Consumer from the main menu.
2. Select a Web Service Consumer type - currently, the only choice is REST. Click Next to proceed.
3. Select Source folder, Package, and Name.

   Note: Since the name you select here will also be the name of the service to be provided, it is good practice to include descriptive naming (while following recommended Naming Conventions).

4. Click Finish. An editor appears.

How to define a Web Service Consumer (REST)

Defining this object identifies the active service made available by a provider using the REST protocol, and allows you to configure settings on how the service is to be consumed.

1. Under the Settings section, enter the URL. This indicates the actual location of the service.

   If you are connecting to a secure (HTTPS) URL you may need to import the certificate for the URL you are connecting to the CIC Studio Keystore prior to connecting.

   Note: You can also type a Substitution Variable - a place holder for all or part of the url path. The actual url will be supplied at runtime by a Business Process. An example of partial replacement may be just replacing...

   https://api.bestbuy.com/v1/products/${productId}.json

   where...

   ${productId}

   ...gets substituted with an actual product id at runtime.

2. Select the HTTP Method. This indicates the type of REST operation (GET, POST, PUT, DELETE) to perform when accessing a URL.
3. Use the Timeout field to determine exactly when a connection attempt to an external Web Service provider will be terminated if a response is not received.
4. Use the Retry Count field to determine the number of times the Web Service consumer will attempt to reconnect.
5. Use the Retry Delay field to determine the amount of time between each retry attempt.
6. Determine payload behavior by using the Transfer Type field. Two options are available.
   1. Chunked: The payload will be divided into smaller units and sent one at a time.
   2. Content-Length: The entire payload will be sent.
7. Enter the name of the Alias into the Vault Entry Alias field to have this object to use a vault entry. See Secure Authorization of Web Service Requests using the Server Vault for more details.
8. Under the Default Request HTTP Headers section, click the Add button to provide and define any HTTP Headers you plan to use with the REST consumer. This optional table allows you to send additional headers to the remote server when the REST consumer is executed. The values specified in the HTTP headers are the default values sent out, however, these values can be modified when the REST Consumer is used by the Business Process at runtime.

   Note: These new REST interfaces are also available in the Web Service Consumer editor so you can change these values after the Web Service Consumer is created.

Once you've completed these steps (and saved your changes), the Web Service Consumer object is available as a task to be used in a Business Process. 

Configuring API Proxy for API Consumers

CIC must often connect to a customer’s internal system and their APIs that aren’t exposed to systems and users outside of their network. API Proxy support for API Consumers can be used in these circumstances.

You can use the CIC Studio (v5.2.13 or above) to configure a Proxy for API Consumers so that the internal APIs can be accessed through an Access Point. The steps below describe this. 

1. From CIC Cockpit> Network > Access Point, create an Access Point (if one doesn't already exist).
2. From CIC Studio (v5.2.13 or above), open the API Consumer for which the Proxy needs to be set. 
3. From the AccessPoint section of the Web Service Consumer editor (shown here), select either the new Access Point that was created or an existing Access Point to be used.
   
4. Save changes and close the editor.
5. Deploy the API Consumer. 

Result:  when the API Consumer object is invoked, the CIC will use the Access Point to connect to the internal API endpoint. 

Notes:

• Providing an Access Point is optional; the field can be left blank if not needed.
• API Proxy support is available for both REST and SOAP Consumers.

Web Service Provider (SOAP/WSDL)

This Web Service Provider (SOAP/WSDL) object generates a WSDL when activated. The WSDL (Web Service Definition Language) file contains definitions of the operations/services available and the schemas that the consumer needs in order to form their request message and understand the provider's response message. Using the Web Service Provider (SOAP/WSDL) editor, you define the services (Name, External Address, and Port) and operations to be available, and specify the request XML Schema (Input Schema) and response XML Schemas (Output Schema), if necessary.

Notes:

• You must have a request XML Schema and optionally a response XML Schema. XML Schemas must be created from XSDs in the XML Schema Wizard.
• You will want to modify your Business Process(es) to disassemble the request XML message, including any internal operations to gather the information requested by the consumer and then assemble a response XML message. The SendSoapReply task used for that response message is pre-supplied in the Business Process. See Business Process tasks that support Web Services.

WS-Security-based Authentication for SOAP Web Service Consumer

To use WS-Security-based authentication for SOAP Web service consumers, please follow the following steps prior to the step invoking the consumer:

1. Create a manual auth vault of Basic type. 
2. In the BPS file, add a new step and select Process Environment - Set Value.
   1. Create a new variable for the property Environment Variable Name with the initial value, addWSSecurityHeader as shown below.
   2. Create a new variable for the property Environment Variable Value with the initial value, true as shown below.