Welcome to Cloud Blue Connect ™ Javascript SDK’s documentation!¶

Introduction¶

CloudBlue Connect is a supply automation platform that manages your products and services, contracts, ordering and fulfillment, usage and subscriptions.

It supports any product, from physical goods to cloud products, as well as any channel, including your direct and indirect sales channels and internal procurement.

With its flexible APIs, it can connect to any commerce platform.

Vendors can leverage CloudBlue Connect to:

Reduce the total cost of ownership for homegrown technology supporting their indirect channel
Standardize integrations with partners
Increase efficiencies and minimize redundancies by bridging their direct and indirect sales channels

Service providers can use CloudBlue Connect to:

Define, manage and distribute any type of product (omni-product) through any channel (omni-channel)
Transform perpetual licensed products into a subscription model
Onboard new products into their portfolio quickly to build and deliver unique solutions to end customers

The Cloud Blue Connect Javascript SDK helps developers to integrate your commerce platform with Cloud Blue Connect.

Table of contents¶

Getting started¶

Requirements¶

The Cloud Blue Connect Javascript SDK depends on the following 3rd party packages:

ramda version 0.26.1
node-fetch version 2.6.0

Installation¶

The current stable release of the Connect Javascript SDK is 19.2.0.

To install the Connect Javascript SDK at the command prompt enter:

$ npm install @cloudblueconnect/connect-javascript-sdk --save

Usage¶

The connect-javascript-sdk allow you to consume the Connect public API directly or using specialized methods to achieve tasks related to a specific workflow.

High-level Usage¶

const { ConnectClient, Fulfillment } = require('@cloudblueconnect/connect-javascript-sdk');
const client = new ConnectClient('<api_endpoint>', '<api_key>');
const fulfillment = new Fulfillment(client);

const response = await fulfillment.approveRequestWithTemplate('<request_id>', '<template_id>');

Low-level Usage¶

You can access the API endpoints directly through the ConnectClient.

The ConnectClient groups operations by the resource they access.

Create an instance of the ConnectClient class:

const { ConnectClient } = require('@cloudblueconnect/connect-javascript-sdk');

const client = new ConnectClient('<api_endpoint>', '<api_key>');

For example to invoke the search action for the Product resource:

client.products.search()
    .then(products => { console.log(products) });

Or if you prefer the async/await syntax:

const products = await client.products.search();
console.log(products);

API Reference¶

Client¶

class ConnectClient(endpoint, apiKey, adapter)¶

ConnectClient provides access to resouce endpoints of the Cloud Blue Connect Platform.

Creates a new instance of the Cloud Blue ConnectClient class. Configures the beforeRequest hooks to inject the API key in the Authorizaton header and prefixes the url with the API’s base url.

Arguments

endpoint (string) – The base URL for API access.
apiKey (string) – The API key to authenticate with Connect.
adapter (AbstractHttpAdapter) – An optional adapter.

Returns

ConnectClient – An instance of the ConnectClient class.

ConnectClient.accounts¶

type: AccountResource

Returns an instance of the AccountResource class to access the Account resource endpoint.

ConnectClient.assets¶

type: AssetResource

Returns an instance of the AssetResource class to access the Asset resource endpoint.

ConnectClient.conversations¶

type: ConversationResource

Returns an instance of the ConversationResource class to access the Conversation resource endpoint.

ConnectClient.fetch(url, options)¶

Fetch the URL and returns a response.

Arguments

url (string) – the URL to fetch.
options (Object) – the request options.

ConnectClient.hubs¶

type: HubResource

Returns an instance of the HubResource class to access the Hub resource endpoint.

ConnectClient.products¶

type: ProductResource

Returns an instance of the ProductResource class to access the Product resource endpoint.

ConnectClient.requests¶

type: RequestResource

Returns an instance of the RequestResource class to access the Request resource endpoint.

ConnectClient.tierAccounts¶

type: TierAccountResource

Returns an instance of the TierAccountResource class to access the TierAccount resource endpoint.

ConnectClient.tierConfigRequests¶

type: TierConfigRequestResource

Returns an instance of the TierConfigRequestResource class to access the TierConfigurationRequest resource endpoint.

ConnectClient.webhooks¶

type: WebhookResource

Returns an instance of the WebhookResource class to access the Webhook resource endpoint.

class AbstractHttpAdapter(fetch)¶

The AbstractHttpAdapter class allow a CloudBlue Connect SDK consumer to wrap a preferred http client library and adapt requests and responses to in order to work with this SDK.

Create a subclass of AbstractHttpAdapter

Arguments

fetch (function) – the fetch function used to make the actual http call.

AbstractHttpAdapter.beforeRequest¶: Get or set a list of beforeRequest hook functions.

Operations¶

class Fulfillment(client)¶

The Fullfilment class exposes specialized methods to help developers to achive common use cases for the fulfillment workflow.

Creates an instance of the Fulfillment class.

Arguments

client (ConnectClient) – An instance of the ConnectClient class.

Returns

Fulfillment – An instance of the Fulfillment class.

Fulfillment.approveRequest(id, request)¶

Updates the Request and set its status to ‘approved’.

Arguments

id (string) – The unique identifier of the Request object.
request (Object) – The request body.

Returns

Object – The updated Request object.

Examples:

// request body using a template id
{
  template_id: 'TL-827-840-476'
}

// request body using an activation tile
{
  activation_tile: '<rendered text>'
}

Fulfillment.approveRequestWithTemplate(id, templateId)¶

Updates the Request and set its status to ‘approved’ using an activation template.

Arguments

id (string) – The unique identifier of the Request object.
templateId (string) – The template id to use for Request approval.

Returns

Object – The updated Request object.

Fulfillment.approveTierConfigRequest(id, request)¶

Updates the TierConfigurationRequest and set its status to ‘approved’.

Arguments

id (string) – The unique identifier of the Request object.
request (Object) – The request body.

Returns

Object – The rendered template.

Examples:

// request body using a template id
{
  template: {
    id: 'TL-827-840-476'
  }
}

Fulfillment.approveTierConfigRequestWithTemplate(id, templateId)¶

Updates the TierConfigurationRequest and set its status to ‘approved’ using an template.

Arguments

id (string) – The unique identifier of the TierConfigurationRequest object.
templateId (string) – The template id to use for TierConfigurationRequest approval.

Returns

Object – The rendered template.

Fulfillment.createRequest(request)¶

Creates a new Request object.

Arguments

request (Object) – The Request object to create.

Fulfillment.createTierConfigRequest(request)¶

Creates a new TierConfigurationRequest object.

Arguments

request (Object) – The TierConfigurationRequest object to create.

Fulfillment.createUpdateTierConfigRequest(request)¶

Creates a new TierConfigurationRequest object of type=”update”.

Arguments

request (Object) – The TierConfigurationRequest object to create.

Fulfillment.failRequest(id, reason)¶

Changes the status of the Request object to ‘fail’.

Arguments

id (string) – The unique identifier of the Request object.
reason (string) – The reason for which the Request has been failed.

Returns

Object – The updated Request object.

Fulfillment.failTierConfigRequest(id, reason)¶

Changes the status of the TierConfigurationRequest object to ‘fail’.

Arguments

id (string) – The unique identifier of the TierConfigurationRequest object.
reason (string) – The reason for which the TierConfigurationRequest has been failed.

Fulfillment.getConnectionIdByProductAndHub(productId, hubId)¶

Search a connection by a product and a hub and if found returns the connection identifier otherwise returns null.

Arguments

productId (string) – The unique identifier of the Product.
hubId (string) – The unique identifier of the Hub.

Returns

string|null – The Connection identifier or null.

Fulfillment.getRequest(id)¶

Retrieve the Request object identified by its id.

Arguments

id (string) – The unique identifier of the Request object.

Returns

Object – The Request object.

Fulfillment.getTierConfigRequest(id)¶

Retrieve the TierConfigRequest object identified by its id.

Arguments

id (string) – The unique identifier of the TierConfigRequest object.

Returns

Object – The TierConfigRequest object.

Fulfillment.inquireRequest(id, request, params, note)¶

Updates the Request object to inquire the provider for ordering parameter. It updates the Parameter object value_error attribute and set the status of the Request to ‘inquire’.

Arguments

id (string) – The unique identifier of the Request object.
request (Object) – The request body.
params (Array) – An array of Parameter objects to update.
note (string) – An optional ‘note’ attribute for the Request.

Returns

Object – The updated Request object.

Examples:

// example of the params argument.
[
  {
     id: 'param_a', // id is required
     value_error: 'This address is already used. Try another.'
  }
]

// request body using a template id
{
  template_id: 'TL-827-840-476'
}

// request body using an activation tile
{
  activation_tile: '<rendered text>'
}

Fulfillment.inquireRequestWithTemplate(id, templateId, params, note)¶

Updates the Request object to inquire the provider for ordering parameter using an activation template. It updates the Parameter object value_error attribute and set the status of the Request to ‘inquire’.

Arguments

id (string) – The unique identifier of the Request object.
templateId (string) – The unique identifier of the Template object.
params (Array) – An array of Parameter objects to update.
note (string) – An optional ‘note’ attribute for the Request.

Returns

Object – The updated Request object.

Fulfillment.inquireTierConfigRequest(id, params, notes)¶

Updates the TierConfigRequest object to inquire the tier for ordering parameter. It updates the Parameter object value_error attribute and set the status of the TierConfigRequest to ‘inquire’.

Arguments

id (string) – The unique identifier of the Request object.
params (Array) – An array of Parameter objects to update.
notes (string) – An optional ‘notes’ attribute for the Request.

Examples:

// example of the params argument.
[
  {
     id: 'param_a', // id is required
     value_error: 'This address is already used. Try another.'
  }
]

Fulfillment.pendingRequest(id)¶

Updates the Request and set its status to ‘pending’.

Arguments

id (string) – The unique identifier of the Request object.

Returns

Object – The updated Request object.

Fulfillment.pendingTierConfigRequest(id)¶

Updates the TierConfigRequest and set its status to ‘pending’.

Arguments

id (string) – The unique identifier of the TierConfigRequest object.

Returns

Object – The updated TierConfigRequest object.

Fulfillment.searchRequests(query)¶

Returns a list of at most limit Request objects that match the provided filters. If no filter is passed, a page of Request in ‘pending’ status is returned.

See the RequestResource.list method for further information about the filters object.

Arguments

query (Object) – A RQL query.

Returns

Array – An array of Request objects that match the provided filters.

Fulfillment.searchTierConfigRequests(query)¶

Returns a list of at most limit TierConfigurationRequest objects that match the provided filters. If no filter is passed, a page of Request in ‘pending’ status is returned.

for further information about the filters object.

Arguments

query (Object) – A RQL query.

Returns

Array – An array of TierConfigurationRequest objects that match the provided filters.

Fulfillment.updateRequest(id, request)¶

Updates a Request object. Only a partial update can be performed on a Request object: developers can update only the note attribute of the Request and/or the asset parameters value or value_error attributes.

Arguments

id (string) – The unique identifier of the Request object.
request (Object) – The body of the request.

Returns

Object – The updated Request object.

Examples:

{
   note: 'Test Note',
   asset: {
     params: [
       {
         id: 'param_a', // id is required
         value: 'value_of_param_a',
         value_error: 'This address is already used. Try another.'
       }
     ]
   }
}

Fulfillment.updateRequestParameters(id, params, note)¶

Updates the asset parameters of a Request object.

Arguments

id (string) – The unique identifier of the Request object.
params (Array) – Array of Parameter objects to update.
note (string) – An optional note for the Request.

Returns

Object – The updated Request object.

Fulfillment.updateTierConfigRequest(id, request)¶

Updates a TierConfigurationRequest object. Only a partial update can be performed on a TierConfigurationRequest object: developers can update only the notew attribute of the TierConfigurationRequest and/or the config parameters value or value_error attributes.

Arguments

id (string) – The unique identifier of the TierConfigurationRequest object.
request (Object) – The body of the request.

Returns

Object – The updated TierConfigurationRequest object.

Examples:

{
   notes: 'Test Note',
   params: [
     {
       id: 'param_a', // id is required
       value: 'value_of_param_a',
       value_error: 'This address is already used. Try another.'
     }
   ]
}

Fulfillment.updateTierConfigRequestParameters(id, params, notes)¶

Updates the parameters of a TierConfigurationRequest object.

Arguments

id (string) – The unique identifier of the TierConfigurationRequest object.
params (Array) – Array of Parameter objects to update.
notes (string) – An optional notes for the TierConfigurationRequest.

Returns

Object – The updated Request object.

class Directory(client)¶

The Directory class exposes specialized methods to help developers to access the directory (assets, tier configs, tier accounts).

Creates an instance of the Directory class.

Arguments

client (ConnectClient) – An instance of the ConnectClient class.

Returns

Directory – An instance of the Directory class.

Directory.getAssetsByProductIdExternalId(productId, externalId)¶

Returns a list of Asset``objects based on the productId and the ``Asset externalId.

Arguments

productId (string) – The unique id of the Product related to this Asset.
externalId (string) – The external identifier of the Asset.

Returns

Array – An array of Asset objects.

Directory.getTierAccount(id)¶

Retrieve a TierAccount by its id.

Arguments

id (string) – The unique identifier of the TierAccount object.

Returns

Object – The TierAccount object.

Directory.searchTierAccounts(query)¶

Returns a list of TierAccount objects that match the provided (optional) query.

Arguments

query (Object) – The optional query to filter results.

Returns

Array – An array of TierAccount object optionally matching the provided query.

class Inventory(client)¶

The Inventory class exposes specialized methods to help developers to access the inventory (products, items etc).

Creates an instance of the Inventory class.

Arguments

client (ConnectClient) – An instance of the ConnectClient class.

Returns

Inventory – An instance of the Inventory class.

Inventory.getAssetParametersForFulfillmentByProduct(id)¶

Retrieves the list of parameters of scope asset and phase fulfillment configured for the product.

Arguments

id (string) – The unique product identifier for which retrieve the parameters.

Returns

Array – An array with the Parameter objects.

Inventory.getParametersByProduct(id)¶

Retrieves the list of parameters configured for the product.

Arguments

id (string) – The unique product identifier for which retrieve the parameters.

Returns

Array – An array with the Parameter objects.

Inventory.getProductAssetTemplates(id)¶

Returns the list of templates configured for a product with scope “asset”.

Arguments

id (string) – The unique identifier of the product.

Returns

Array – An array of Template objects.

Inventory.getProductTemplates(id)¶

Returns the list of templates configured for a product.

Arguments

id (string) – The unique identifier of the product.

Returns

Array – An array of Template objects.

Resources¶

class GenericResource(client, baseUri)¶

The GenericResource map a generic endpoint of the CloudBlue Connect API. Each API endpoint should extend this class and implements endpoint specific actions and subresources access.

Arguments

client (ConnectClient) – A ConnectClient instance.
baseUri (string) – The base URI of the resource

GenericResource.baseUri¶

type: string

Returns the base URI of the resource mapped by this class.

GenericResource.create(obj)¶

Create a new resource.

Arguments

obj (Object) – The resource to create.

Returns

Object – The created resource.

GenericResource.delete(id)¶

Delete a resource.

Arguments

id (string) – The unique identifier of the resource to delete.

GenericResource.fetch(url, options)¶

Fetch the URL and returns a response.

Arguments

url (string) – the URL to fetch.
options (Object) – the request options.

GenericResource.get(id)¶

Retrieve a resource by its unique identifier.

Arguments

id (string) – The unique identifier of the resource to retrieve.

Returns

Object – The resource.

GenericResource.search(query)¶

Search for a resource.

Arguments

query (Object) – The query to send to the server as a RQL object.

Returns

Array – An array of resources that match the provided filters.

GenericResource.update(id, obj)¶

Update a resource.

Arguments

id (string) – The unique identifier of the resource to update.
obj (Object) – The eventually partial resource to update.

Returns

Object – The updated resource.

class AccountResource(client)¶

The AccountResource class provides methods to access the accounts endpoint of the Cloud Blue Connect API.

Creates a new instance of the AccountResource class.

Arguments

client (ConnectClient) – An instance of the ConnectClient class.

Returns

AccountResource – An instance of the AccountResource class.

AccountResource.users(id)¶

Returns an instance of the AccountUserResorce class.

Arguments

id (string) – The account unique identifier.

Returns

AccountUserResource – An instance of AccountUserResource.

class AccountUserResource()¶: The AccountUserResource allow consumers of the CloudBlue Connect API to access information about Users related to an account.

class AssetResource(client)¶

The AssetResource class provides methods to access the assets endpoint of the Cloud Blue Connect API.

Creates a new instance of the AssetResource class.

Arguments

client (ConnectClient) – An instance of the ConnectClient class.

Returns

AssetResource – An instance of the AssetResource class.

class ConversationResource(client)¶

The ConversationResource class provides methods to access the conversations endpoint of the Cloud Blue Connect API.

Creates a new instance of the ConversationResource class.

Arguments

client (ConnectClient) – An instance of the ConnectClient class.

Returns

ConversationResource – An instance of the ConversationResource class.

ConversationResource.createMessage(id, msg)¶

Add a message to a Conversation object.

Arguments

id (string) – The unique identifier of the Conversation object.
msg (string) – The text of the message to post.

Returns

Object – The newly created Message object.

ConversationResource.getConversationsByObjectId(id)¶

Returns a list of conversations attached to the business object specified by its id.

Arguments

id (string) – The unique id of the business object attached to a conversation.

Returns

Array – A list of conversations attached to a business object.

class HubResource(client)¶

The HubResource class provides methods to access the hubs endpoint of the Cloud Blue Connect API.

Creates a new instance of the HubResource class.

Arguments

client (ConnectClient) – An instance of the ConnectClient class.

Returns

HubResource – An instance of the HubResource class.

class ProductResource(client)¶

The ProductResource class provides methods to access the products endpoint of the Cloud Blue Connect API.

Creates a new instance of the ProductResource class.

Arguments

client (ConnectClient) – An instance of the ConnectClient class.

Returns

ProductResource – An instance of the ProductResource class.

ProductResource.actions(id)¶

Returns an instance of the ProductActionResource for a Product.

Arguments

id (string) – The unique identifier of the Product.

Returns

ProductActionResource – An instance of the ProductActionResource for the product.

ProductResource.configurations(id)¶

Returns an instance of the ProductConfigurationResource for a ProductConfiguration.

Arguments

id (string) – The unique identifier of the Product.

Returns

ProductConfigurationResource – An instance of the ProductConfigurationResource for the product.

ProductResource.getConnections(id)¶

Returns the list of Connection objects configured for the Product.

Arguments

id (string) – The unique identifier of the Product.

Returns

Array – The list of Connection objects.

ProductResource.getItems(id)¶

Returns the list of ProductItem objects configured for the Product.

Arguments

id (string) – The unique identifier of the Product.

Returns

Array – The list of ProductItem objects.

ProductResource.getParameters(id)¶

Returns the list of Parameter objects configured for the Product.

Arguments

id (string) – The unique identifier of the Product.

Returns

Array – The list of Parameter objects.

ProductResource.getTemplates(id)¶

Returns the list of Template objects configured for the Product.

Arguments

id (string) – The unique identifier of the Product.

Returns

Array – The list of Template objects.

ProductResource.versions(id)¶

Returns an instance of the ProductVersionResource for a Product.

Arguments

id (string) – The unique identifier of the Product.

Returns

ProductVersionResource – An instance of the ProductVersionResource for the product.

class ProductActionResource()¶

The ProductActionResource class provides methods to access the Action objects for a product.

ProductActionResource.link(id, assetId)¶

Returns the ActionLink object for a product and asset.

Arguments

id (string) – The unique identifier of the Action.
assetId (string) – The unique identifier of the Asset.

Returns

Object – The ActionLink object.

class ProductConfigurationResource()¶: The ProductConfigurationResource class provides methods to access the ProductConfiguration objects for a product.

class ProductVersionResource(client)¶

The ProductVersionResource class provides methods to access the Version objects for a product.

Creates a new instance of the ProductVersionResource class.

Arguments

client (ConnectClient) – An instance of the ConnectClient class.

Returns

ProductVersionResource – An instance of the ProductVersionResource class.

ProductVersionResource.actions(id)¶

Returns an instance of the ProductActionResource class to access the Action objects configured for a specific version of a Product.

Arguments

id (string) – The unique identifier of the Version object for a Product.

Returns

ProductActionResource – The instance of the ProductActionResource class for a product/version.

class RequestResource(client)¶

The RequestResource class provides methods to access the Request endpoint of the Cloud Blue Connect API.

Creates a new instance of the RequestResource class.

Arguments

client (ConnectClient) – An instance of the ConnectClient class.

Returns

RequestResource – An instance of the RequestResource class.

RequestResource.approve(id, request)¶

Change the status of a Request to approved. To change the status of the Request to approved you must provide either a template id or a template tile.

Arguments

id (string) – The unique identifier of the Request object.
request (Object) – The request body.

Returns

Object – The updated Request object.

Examples:

// request body using a template id
{
  template_id: 'TL-827-840-476'
}

// request body using an activation tile
{
  activation_tile: '<rendered text>'
}

RequestResource.fail(id, reason)¶

Change the status of a Request to fail.

Arguments

id (string) – The unique identifier of the Request object.
reason (string) – The reason for which the Request has been failed.

Returns

Object – The updated Request object.

RequestResource.inquire(id, request)¶

Change the status of a Request to inquire. To change the status of the Request to inquire you must provide either a template id or a template tile.

Arguments

id (string) – The unique identifier of the Request object.
request (Object) – The request body.

Returns

Object – The updated Request object.

Examples:

// request body using a template id
{
  template_id: 'TL-827-840-476'
}

// request body using an activation tile
{
  activation_tile: '<rendered text>'
}

RequestResource.pending(id)¶

Change the status of a Request to pending.

Arguments

id (string) – The unique identifier of the Request object.

Returns

Object – The updated Request object.

class TierAccountResource(client)¶

The TierAccountResource class provides methods to access the tier accounts endpoint of the Cloud Blue Connect API.

Creates a new instance of the TierAccountResource class.

Arguments

client (ConnectClient) – An instance of the ConnectClient class.

Returns

TierAccountResource – An instance of the TierAccountResource class.

class TierConfigRequestResource(client)¶

The TierConfigRequestResource class provides methods to access the TierConfigRequest endpoint of the Cloud Blue Connect API.

Creates a new instance of the TierConfigRequestResource class.

Arguments

client (ConnectClient) – An instance of the ConnectClient class.

Returns

TierConfigRequestResource – An instance of the TierConfigRequestResource class.

TierConfigRequestResource.approve(id, request)¶

Change the status of a TierConfigurationRequest to approved. To change the status of the TierConfigurationRequest to approved you must provide a Template id.

Arguments

id (string) – The unique identifier of the TierConfigurationRequest object.
request (Object) – The request body.

Returns

Object – The rendered Template.

Examples:

// request body using a template id
{
  template: {
    id: 'TL-000-000-000'
  }
}

TierConfigRequestResource.fail(id, reason)¶

Changes the status of a TierConfigurationRequest to fail.

Arguments

id (string) – The unique identifier of the TierConfigurationRequest object.
reason (string) – The reason for which the TierConfigurationRequest has been failed.

TierConfigRequestResource.inquire(id)¶

Changes the status of a TierConfigurationRequest to inquire.

Arguments

id (string) – The unique identifier of the TierConfigurationRequest object.

TierConfigRequestResource.pending(id)¶

Changes the status of a TierConfigurationRequest to pending.

Arguments

id (string) – The unique identifier of the TierConfigurationRequest object.

class WebhookResource(client)¶

The WebhookResource class provides methods to access the webhooks endpoint of the Cloud Blue Connect API.

Creates a new instance of the WebhookResource class.

Arguments

client (ConnectClient) – An instance of the ConnectClient class.

Returns

WebhookResource – An instance of the WebhookResource class.

Errors¶

class HttpError(status, message)¶

HttpError wraps any http response which status is != 2xx.

Create a new instance of the HttpError class.

Arguments

status (number) – the http status code.
message (string) – an error message.

HttpError.status¶

type: number

The http status code.

class APIError(status, message)¶

APIError wraps CloudBlue Connect API errors. Provides convenient methods to obtains error code and error messages. The Cloud Blue Connect JSON error looks like:

Create a new instance of the APIError class.

Arguments

status (number) – the http status code.
message (string) – A JSON parseable object.

Examples:

{
   "error_code": "SYS_001",
   "errors": [
      "error message 1"
   ]
}

APIError.errorCode¶: Returns the error code.

APIError.errors¶: Returns an array of error messages.

APIError.json¶: Returns the JSON error object.

APIError.status¶

type: number

The http status code.

Indices and tables¶

License¶

The Connect Javascript SDK is licensed under the Apache License 2.0.