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.

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.