Element Builder Overview

You can use Element Builder to create custom integrations to API providers and build your own element. You can build elements for REST, SOAP, and OData APIs and even database applications. Publish finished elements to the Elements Catalog while automatically generating interactive API Documentation. You can combine services by creating a new hub or mapping your new element to an existing hub. You can also use the normalized resources that we have already organized into hubs, and leverage the same resources across any other element that you build.

Anyone building elements should be familiar with APIs, JavaScript, and JSON. To create an element we recommend that you have a thorough understanding of:

  • API authorization concepts
  • Any setup required with the API provider
  • JavaScript
  • The API of the API provider that you are connecting to
  • The API provider's API documentation
  • The Cloud Elements Hub APIs

Tip: Take a look at our Hello World Element Builder example project.

Before You Begin

Before you begin, here is a sampling of questions you need to know the answers to. You can find most of the information needed in the API provider's documentation

  • Where is the API documentation?
  • What kind of API? REST, SOAP, database?
  • What kind of authentication? OAuth 1.0 or 2.0? Basic? AWS V2 or V4?
  • Do you need to create a connected app?
  • Does the endpoint support events or bulk?
  • Do OAuth 2.0 tokens expire?
  • What resources do you want to connect? Accounts, contacts, lists, leads?
  • In which Hub should you categorize the element?
  • Have you set up an application to integrate with the API provider? Do you have the authentication information for it?

Custom Element Checklist

After you build an element, we recommend that you review the checklist below:

Each GET resources includes CEQL (the where clause) and pagination.

The element includes an informative description.

If building an OAuth 2.0 element in different Cloud Elements environments, confirm that the API providers supports all environments.

Check pagination — pageSize and Pagination type — to ensure correct information.

POST and PATCH resource bodies include the correct object data type and models.

Map an authenticated element instance to a virtual data resource data resource.

For polling events, confirm the correct configuration of dates, using the same format as the API provider. Also ensure that the time zone format matches.

For bulk, confirm the dates are configured using the same format as the API provider.

Element Conventions

To align your custom elements with those created by Cloud Elements, we recommend that you follow our conventions:

  • Resource names: Lowercase the name and use the plural form.
    • Correct: /contacts
    • Incorrect: /contact
  • Spaces in paths: Replace spaces with dashes.
    • Correct: /hubs/finance/sales-receipts
    • Incorrect: /hubs/finance/sales_receipts
  • Spaces in configuration or parameter names: Use camelCase.
    • Correct: /hubs/finance/sales-receipts/{salesReceiptId}/details
    • Correct: /hubs/crm/contacts/{contactId}/notes
    • Incorrect: /hubs/finance/sales-receipts/{salesreceiptId}/details
    • Incorrect: /hubs/crm/contacts/{contact-Id}/notes
  • Descriptions by method:
    • GET — "Search for resources." Or, if no CEQL query was configured for the endpoint, use "List all resources".
    • GET/{id} — "Retrieve a(n) resource".
    • POST — "Create a(n) resource".
    • PATCH — "Update a(n) resource".
    • DELETE —"Delete a(n) resource"
  • where parameter descriptions: Following the default "The CEQL search expression." add an example for the specific element.
    • Example: The CEQL search expression, or the where clause, without the WHERE keyword, in a typical SQL query. For example, to search for contacts last modified on or after ‘Jan 15, 2014’, the search expression is where=LastModifiedDate>=’2014-01-15T00:00:00.000Z’. When this parameter is omitted, all contacts are returned in a paginated fashion.