Element Builder - GET {objectName}/metadata

This document describes the metadata properties that the Cloud Elements platform expects when doing GET /object/{objectName}/metadata. The GET /{object/{objectName}/metadata endpoint has strict formatting requirements to power our VDRs and also to keep consistency in object structure for the consumption of metadata. If not implemented properly, this can cause VDR's to fail, and cause the GET /object/{objectName}/metadata endpoint to fail. 

Goals of implementing /object/{objectName}/metadata

  • Provide a unified metadata experience across the platform
  • Use javascript as necessary to convert from vendor meta format to CE format
  • Provide users with as much data describing the API as the vendor makes available
  • Power VDR's for all those gooooood transformations.


Watch Out! Your API needs to return data formatted exactly correct or the /object/{objectName}/metadata API fails. We recommend creating a copy /object/{objectName}/metadata_copy which doesn't have the same backend restrictions. Once you complete your resource, copy the hook over to the main API and let it take care of the validation for you

Best Practices

Below you will find a full list of acceptable properties for /object/{objectName}/metadata and the usage, however, in practice, we often will only implement a fraction. This is usually due to the vendor not making things available, but you may also need to abstract something out that the platform doesn't support and is deemed unnecessary. 

Always Include

  • vendorPath

  • mask
  • format
  • type

Sometimes Include 

When to include: nice-to-haves, if vendor provides property then implement it, but don't get caught up looking for them or doing insane parsing unless required

  • vendorDisplayName
  • vendorNativeType
  • vendorReadOnly
  • vendorRequired
  • filterable
  • createable
  • updateable
  • description
  • custom

Seldom Include

When to include: Only implement these properties if a customer requires it, or you're just feeling really excited about having rich metadata

Path

primaryKey

custom

updateable

nullable

type

reference

picklistValues[] 

restrictedPicklist[]

relations

precisiondefaultValue

displayName

readOnly

filterable

method 

description

conditionallyRequired

vendorDisplayName

vendorRequired

filterableNames[] 

name 

length

subFormat

vendorNativeType

vendorReadOnly

filterableOperators[] 

response

minLength 

sampleValue

required

hidden

createable 

request



Dictionary

CE Metadata Property NameDataTypeDescription/Usage

conditionallyRequired

String

when is this field required (dependency)… Invoice if CC provided, also need cvv. Mostly present in swagger

createable

Boolean

can be created, usually in a POST

custom 

Boolean

true if is custom field

defaultValue

Object

if no value provided, value defaults to X

description

String

description of what field does

displayName

String

label seen in vendor UI ** not used much

filterable

Boolean

searchable in where clause

filterableNames[] 

List<String>

if prop filterable by other name, list filter options here. 

filterableOperators[] 

List<String>

logical operators supported in filtering 

format

String

int64

hidden

Boolean

 we don’t know what this means but vendors do it maybe hidden in UI

length

Integer

max length of field

mask

String

formatting dates — usually only for dates

method

List<ObjectMetadataFieldMethod> 

 name - HttpMethod in caps, GET POST PATCH …..

 response - true/false does this field show up

 request - true/false can it be used in a request

minLength

Integer

min length of field

nullable

Boolean

 most fields are nullable (default true). This field can/cannot be set to null (required)**

path

String

dot notation path***not really used

picklistValues[] 

List

Array of picklist values for enums

precision

String

how precise is a value, $1.00 has precision of 2

primaryKey

Boolean

has this property if property is a primary key

readOnly

Boolean

CE read only immutable operations

reference

String

 foreignKey of object

relations

List

foreign key reference to other metadata?

required

Boolean

 CE required ** not usually used

restrictedPicklist

Boolean

 If enum is restricted (no other values other than picklist); or perhaps gross amount of values

sampleValue

Object

 sample data to put in payload

subFormat

String

in general, don’t bother unless customer required

type

String

 type of object (https://cl.ly/11b77390824a)

updateable

Boolean

can be updated, usually in PATCH or PUT

vendorDisplayName 

String

label seen in vendor UI

vendorNativeType

String

Type in vendor system (nice to have)

vendorPath

String

 dot notation path

vendorReadOnly

Boolean

 vendor read only immutable operations

vendorRequired

Boolean

use this for required fields

Types and Formats