Item IDs

All items retrieved from underlying providers have a unique ID with which they can be referenced.

The ID is a compound of the Integration ID and the remote provider's item ID.

An item's WorkAPI ID can be determined by concatenating them (with a colon as separator) and encoding to a strict Base64 string: <integration_id>:<remote_id>.

Extracting the remote item ID using the SDK

This is handled under the hood when using the SDKs.

The SDKs will enable the developer to call item.integration_id and item.remote_id to retrieve the underlying IDs.

Example

item = LivilApi::Email.new(id: 'aW50ZWdyYXRpb25fMTIzOmVtYWlsX3h5eDo6')
item.integration_id # => 'integration_123'
item.remote_id # => 'email_xyz'

Building the WorkAPI ID using the SDK

Conversely, when setting item.integration_id and item.remote_id manually, the WorkAPI ID is calculated automatically:

Example

item = LivilApi::Email.new(remote_id: 'email_xyz', integration_id: 'integration_123')
item.id # => 'aW50ZWdyYXRpb25fMTIzOmVtYWlsX3h5eDo6' 

# Note: as mentioned, this is padded to avoid '==' on the base64 string
#       Without paddding, the Base64 output is 'aW50ZWdyYXRpb25fMTIzOmVtYWlsX3h5eA=='
#       Both strings will be handled in the same way by the API

Working with IDs outside of the SDK

Without using the SDK, the ID can be generated as follows:

Example

remote_id = 'email_xyz'
integration_id = 'integration123'

encoded_id = Base64.strict_encode64("#{integration_id}:#{remote_id}")
encoded_id # => 'aW50ZWdyYXRpb25fMTIzOmVtYWlsX3h5eDo6'

And the inverse

Example

id = 'aW50ZWdyYXRpb25fMTIzOmVtYWlsX3h5eDo6'

decoded_id = Base64.strict_decode64(id)
integration_id, remote_id = decoded_id.split(':')

integration_id # => 'integration123'
remote_id # => 'email_xyz'