Web Service Provider object

Use the Web Service Provider (WSP) object to expose a REST API from Cleo Integration Cloud. A WSP listens for incoming requests, runs a Business Process you design, and returns the response to the caller. It is the building block for turning an integration into an API that partners, applications, and internal teams can call.

Quick Notes

• Protocol: REST only
• Max Payload: 10 MB.
• ASYNC Support: CIC Studio v5.2.13+
• Required: These objects must be deployed to operate.

In this article

• How a WSP works end-to-end
• Create a WSP
• Configure a WSP (fields reference)
• Example: a synchronous order-status API
• Asynchronous WSPs
• Authorization types and calling your API
• API group and authorization rules (avoid deployment errors)
• Common use cases
• Troubleshooting
• Best practices

How a WSP works end-to-end

Building an API with a WSP involves three places in the platform:

1. CIC Studio: you create and configure the WSP, and edit the Business Process that does the work.
2. Deployment: WSP objects must be deployed to the Integration Server before they can receive requests.
3. CIC Cockpit: once deployed, you create an API Provider Endpoint in the Cockpit to make the API available to consumers. Multiple WSPs that reference the same host and vault alias value are combined into a single API Endpoint, which you can view from the Jobs page in the Cockpit.  See API Provider Endpoint.

Each incoming call runs the WSP's Business Process as a job, so you get the same visibility, retry, and troubleshooting tooling you already use for the rest of your integrations.

Create a WSP

1. In CIC Studio, select File | New | Web Service Provider.
2. Choose the Source folder, Package, and Name. The name also becomes the name of the service you provide, so use a descriptive name that follows the recommended naming conventions.
3. Click Finish. The WSP editor opens.

Configure a WSP (fields reference)

In the WSP editor you define the REST service and how it is consumed. The fields are:

Resource Name, Path, and API: how the URL is built

These three fields combine to form the URL your consumers call:

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

Use Path to separate read operations from write operations, or to group endpoints by domain. For example, a beverages inventory service might expose:

# Read
Path: getBeverages
https://cleointegration.cloud/beverages/getBeverages/GetBeersInventoryWSPRest

# Write
Path: postBeverages
https://cleointegration.cloud/beverages/postBeverages/PostBeersInventoryWSPRest

Here beverages is the API group, getBeverages and postBeverages are paths, and the final segments are the resource names.

Business Process

CIC Studio creates a package with a Business Process already wired to your WSP. It contains two pre-configured tasks:

• SendRestReply sends the response message back to the consumer.
• SetExitStatus sets the Business Process exit status to true.

This skeleton returns a reply but does no real work yet. Add your own tasks between request and reply. Typical additions include GetProperty to read a value from the request (such as a purchase order number), tasks that gather or transform data, and SendEmail to notify someone.

Default Response HTTP Headers

Use this section to add headers to every response, override common headers, or define custom ones. Typical examples are cache-control directives, CORS headers for browser-based consumers, or a custom header that carries a version identifier.

Example: a synchronous order-status API

This walkthrough builds a simple endpoint that returns the status of a purchase order, using the fields above.

1. Configure the WSP

2. Extend the Business Process

Between the start of the process and SendRestReply, add tasks to:

1. Read the order number from the incoming request (GetProperty).
2. Look up the order in your system of record (for example, through a Web Service Consumer or database task).
3. Set the response body so SendRestReply returns the result.

3. Deploy, then create the endpoint

Deploy the project to the Integration Server, then create an API Provider Endpoint in the CIC Cockpit (Network > Endpoint) and select your API provider.

4. Call it

curl -u "<username>:<password>" \
  "https://<hostname>/partner-api/orders/GetOrderStatusRest"

The URL follows the <hostname>/<API>/<Path>/<ResourceName> pattern. Each call appears as a job in the Cockpit.

Asynchronous WSPs

Enable Async when the work behind the API takes too long for a caller to wait: large file processing, multi-step orchestration, or calls to slow downstream systems. The caller gets an immediate answer and the Business Process runs in the background.

Configure an asynchronous WSP

1. In CIC Studio, open the WSP you want to make asynchronous.
2. Enable the Async flag in the editor.
3. Save your changes and close the editor.
4. Deploy the API Provider.
5. In the CIC Cockpit, go to Network > Endpoint and select the API Provider when you create your API Endpoint. The endpoint shows confirmation that the API is asynchronous.

When the endpoint is invoked, the response is immediate and a Job is created in the Cockpit.

What the caller sees

curl -i -X POST -u "<username>:<password>" \
  -H "Content-Type: application/json" \
  -d @large-order-batch.json \
  "https://<hostname>/partner-api/orders/SubmitOrderBatchRest"

HTTP/1.1 202 Accepted
...
(payload includes the job ID)

Your consumer should treat 202 as "received," not "finished." Store the job ID so you can trace the request in the Cockpit if something goes wrong.

Authorization types and calling your API

Authorization is validated for each WSP according to the type you select:

API group and authorization rules (avoid deployment errors)

Because auth type is enforced per API group, a wrong combination of the API and Authorization Type fields causes deployment to fail. Plan your API groups before you build.

If no APIs are deployed yet

Once an API is deployed under the default API group name with a defined Authorization Type, no other API group name (default or non-default) can be deployed with a different auth type.

If an API is already deployed

Suppose a deployed project contains a WSP whose API field is internal and whose Authorization Type is OAuth2_Client_Credentials. You cannot deploy another project that uses the internal API field with Basic Authentication or Custom Authentication.

To deploy the second project, first un-deploy the original project, then deploy the one with the API field and Authorization Type combination you want. The same applies any time you want to change the auth type for an existing API group: un-deploy first, then associate the new auth type.

Common use cases

• Order and shipment status lookups. Expose a read-only endpoint that trading partners call instead of emailing or phoning for updates.
• Inbound transaction intake. Accept purchase orders, ASNs, or invoices as JSON over REST and hand them to a Business Process that maps and routes them to ERP or EDI flows.
• Long-running batch submission. Use an async WSP so a partner can submit a large batch, get a 202 and job ID immediately, and not hold a connection open.
• Internal service APIs. Wrap an existing integration as an API so internal apps can trigger it on demand, using a separate internal API group with its own auth.
• Partner-specific access. Use API groups to issue different credentials per consumer or per product line, while a single consumer can still access multiple APIs in its group.

Troubleshooting

Best practices

• Design API groups first. Decide your groups, auth types, and sync/async behavior up front. Changing them later means un-deploying.
• Keep sync APIs fast. If a Business Process can run long, make it async.
• Use meaningful paths. Separate read and write operations, and keep resource names descriptive.
• Mind the 10 MB limit. Plan for large payloads before consumers hit it.
• Test in the Cockpit. Every call is a job, so review job details when validating a new endpoint.

Related articles

• API Provider Endpoint
• Web Service Consumer object
• Using Basic Authentication with API Endpoints
• Naming Conventions
• Cleo Developer Documentation