Web Service Provider object

The Web Service Provider (WSP) object can detect incoming requests and then process responses based on the specific configurations within your integration. Use the CIC Studio to create and configure these objects to request and process information or activity from a provider through the use of request messages.

These objects must be deployed to operate. Currently, this object supports REST only.

API Endpoints in the CIC Cockpit

Once a WSP has been created in CIC Studio and deployed to the Integration Server, API Provider Endpoints can be created in the CIC Cockpit. APIs are made available to the API Provider Endpoint in the CIC Cockpit. Multiple WSPs that reference the same host and vault alias value are combined into a single API Endpoint; this can be viewed from the Jobs page in CIC Cockpit. See API Provider Endpoint for more information.

How to Create a Web Service Provider (WSP)

1. Select File | New | Web Service Provider from the CIC Studio main menu.
2. 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).

3. Click Finish. An editor appears.

How to Configure the Web Service Provider (WSP)

In CIC Studio, use the WSP editor to define the active service made available (using the REST protocol) and set how the service is to be consumed. Fields to be defined include:

• Resource Name
• Path
• API
• Async (checkbox)
• Business Process
• Authorization Type

Resource Name

The name of the resource which forms part of the URL. An example could be GetCosmetics.
The actual resource path appears like this: 

https://<hostname>/<API>/<Path>/<Resourcename>

While this is an auto-generated field with the default value of <wsProviderFileName>+Rest, it can be edited.

Path (optional)

An additional part or sub-path of the resource path. See the resource path above. Path is part of the URL:

https://<hostname>/<API>/<Path>/<Resourcename>

This optional field can be used for creating a unique endpoint, and also provides meaningful segregation of endpoints. For example, consider this Beverages-related Endpoint URL:

Path: GetBeverages
https://<hostname>/<API>/<Path>/<Resourcename>
https://cleointegration.cloud/beverages/getBeverages/GetBeersInventoryWSPRest
Path: postBeverages
https://cleointegration.cloud/beverages/postBeverages/PostBeersInventoryWSPRest

API

This is a custom name for a group of APIs. API grouping allows for multiple APIs to use the same authorization credentials, and also allows for one particular consumer to consume multiple APIs. 

In the CIC Cockpit, a list of API Groups for a selected Endpoint will be displayed.

If this field is left blank, then the default security group will be selected for the Web Service Provider.

Async

Enabling this checkbox allows you to create an asynchronous API Provider so that the callers of the API won't have to wait for the response. This capability is only available in CIC Studio (v5.2.13 or above).  
These steps describe how to configure an asynchronous API Provider.

Important!

1. Authorization Type and Async are executed at the API level (not at the object level). All Web Service Providers using the same API must have consistent Auth Type and Async. They cannot have synchronous (default) and asynchronous behavior together. Deployment errors will result if there is a discrepancy.  For example, if two Web Service Providers are already deployed (and API fields left blank by default), and the Async feature is enabled for just one of the objects, then an error will be thrown at deployment.
2. The HTTP response status message for an async-enabled WSP will be '202 Accepted' with the job ID in the payload.

To configure an asynchronous WSP

1. From the CIC Studio, open the WSP you wish to make asynchronous. 
2. Enable the Async flag setting in the editor.

   

3. Save changes and close the editor.
4. Deploy the API Provider.
5. From the CIC Cockpit > Network > Endpoint page, select the API Provider when creating your API Endpoint.

   Confirmation that the API is asynchronous is displayed on the API Endpoint. 

   

   When this API Endpoint is invoked, the response is immediate and a Job is created in the Cockpit.

Business Process

This should be pre-populated, as CIC Studio automatically creates a corresponding package containing a Business Process, which is pre-configured with the Web Service Provider object just defined in this task. The Business Process contains two tasks: SendRestReply, which sends the response message to a consumer, and SetExitStatus, which sets the Business Process’s Exit Status to true. All task parameters are pre-populated.

Additional configuration is required.

Any additional tasks will need to be added and defined to the Business Process. For example, some additional tasks might include determining the requested purchase order number (using GetProperty), gathering the data, and generating an e-mail (SendEmail).

Authorization Type

Here you configure Authentication Validation for this WSP. Options include:

• OAuth2_Client_Credentials
• Basic Authentication
• Key Authentication
• Custom Authentication

  Note: Selecting this type causes your API to automatically associate with the Default API Provider Endpoint and it will be unable to associate with any other API Endpoints.

Configure Headers

Under the Default Response HTTP Headers section, include any additional Header information required as part of the consumer request.

HTTP header fields are components of the message header of requests and responses used in HTTP. They define additional information about the request to and response from the service provider. This additional information may be sent with the status codes. They can be used to override common headers or create custom ones.

URL Construction and Prerequisites

When configuring the fields in the Web Service Provider, it is important to understand the relationship between the API and Authorization Type fields; a wrong combination can result in deployment errors.

Multiple WSP objects may use the same API (API field name/security group) but have different Authorization Types. This scenario will result in failed deployment. A boundary conditions table, below, provides information that can help avoid this occurrence.

Constructed URL: https://hostname/<api>/<path>/<resource>

Following are the boundary conditions for creating the WSP.

Consider these two scenarios:

No APIs are deployed:

• Once the API has been deployed with a default API group name with a defined authorization type then no other API group name (default or non-default) can be deployed with any other auth type.

API is already deployed:

• If a deployed Project contains a WSP object with the API field defined as internal and the AuthorizationType field defined as OAuth2_Client_Credentials, then no other WSP Project with an API field defined as internal and Authorization Type of Basic Authentication or Custom Authentication can be deployed.

  If you wish to deploy this latter Project then you must un-deploy the first Project (noted above); before you can deploy the WSP Project containing the required API field name and Authorization Type combination.

• The first time you un-deploy an existing WSP with a given API group must be done before a new auth type can be associated with the given API group.