Using the OData feed – BlueDolphin

Getting started

This article is your guide to working with data available through the BlueDolphin OData service. It includes detailed descriptions and explanations of parameters, allowable operations, and special characters commonly encountered in responses.

To be able to make use of the BlueDolphin OData feed, the first step is to connect to the service. Please follow the steps described in this article to make a connection.

Field naming

Below is a table showing the syntax for creating field names in BlueDolphin.

Field type

Structure

System fields

Immutable and always present

Variable properties

Object Properties_{property_name} for EN tenants

Objecteigenschappen_{property_name} for NL tenants

Variable questionnaires

{questionnaire_name}_{field_name}

Allowed and special characters in field names

Here, we will outline which characters are stored in their original form and which ones will be encoded.

Character	Allowed	Replaced by	Example
Alphanumeric	Yes	No changes	No changes
Underscore (_)	Yes	No changes	No changes
Dash (-)	No	Underscore (_)	"General - Business Process" with the field "Description" is translated to "General___Business_Process_Description"
Whitespace ( )	No	Underscore (_)	"General - Business Process" with the field "Business Process owner" is translated to "General___Business_Process_Business_Process_owner"
Any other character	No	The character’s encoded value (hex value in xXX format).	"General - Business Process" with the field "More info..." is translated to "General___Business_Process_More_info_x2Ex2Ex2E"

For an extensive list of hexadecimal values, visit this page.

Field value rules

For the questionnaire fields that are marked as sensitive, the values will be hidden and replaced by:

Field type	Replaced by
Dropdown/Multiple select	******
Dropdown/Radio	******
Hyperlink	******
Multiple text lines	******
Text	******
Formatted text	******
Checkbox	Empty string
Date	Empty string
Number	Empty string
Currency	Empty string

Any HTML tags will be ignored (not converted) in a response.
The questionnaire fields of the type "Multiple text lines" and "Text" return a newline character "\n" for every new line in a response. For example:

will be presented in OData as

 This is the response.\nThis is the next line.

Query parameters

These parameters specify a subset of properties to include in a response.

Parameter	Note
$filter
$orderby	By default, BlueDolphin OData feed doesn’t use any ordering. Add this parameter to use a specific sorting method for your query.
$select
$skip
$top
$count	Only applicable to the history endpoint

Any other operation is not allowed, for example $expand, $format, $skiptoken, or $deltatoken. If you use any of the unsupported operations, the system returns an error ‘The query specified in the URI is not valid’ accompanied with a specific error.

Query functions

Below are the query functions that are allowed when working with the BlueDolphin OData feed.

Function
ends.With
starts.With
contains

Any other function is not allowed, for example length, indexof, substring, tolower, toupper, trim, year, month, day, hour, minute, second, fractionalseconds, date, time, round, floor, ceiling, isof, cast, any, or all.

Query logical operators

Here are the allowed logical operators to be used in your queries.

Logical operator	Description
And	Logical and
Eq	Equal
Gt	Greater than
Ge	Greater than or equal
Lt	Less than
Le	Less than or equal
Ne	Not equal
Or	Logical or

Note: Please note that the use of arithmetic operators such as add, sub, mul, div, and mod is not supported.

For more information about the conventions and technical specification, see the official OData documentation.

Objects

Below is a table listing the properties you can expect when requesting the collection of objects.

Response properties

Property	Type	Description
ID	string	Primary key of the object. Only stored in the database and not visible in UI. To gain insights into how the object is connected to another object, you need to link this ID with "BlueDolphinObjectItemId" and also link this ID with "RelatedBlueDolphinObjectItemId".
Title	string	Primary key of the object. Also visible in UI.
Completeness	integer	Returns the completion percentage of questionnaire fields marked as 'Use in completeness calculation' that have been filled.
CreatedOn	string	Creation timestamp in ISO 8601 UTC format
CreatedBy	string	The name of the user who created the object
ChangedOn	string	Change timestamp in ISO 8601 UTC format. Not filled if an object is only created.
ChangedBy	string	The name of the user who made a change. Not filled if the object is only created.
ArchivedOn	string	Only filled if the object is deleted. The status of the object must be 'Archived'.
ArchivedBy	string	Only filled if the object is deleted. The status of the object must be 'Archived'.
ArchimateType	string	The name of the underlying ArchiMate® type (that the object definition is based on). Cannot be changed in BlueDolphin.
Definition	string	Your own custom name of the ArchiMate type
Category	string	The category of the object. Cannot be changed in BlueDolphin.
ConditionalColor	string	Hexadecimal color code of the object. A random code is assigned at creation, but it can be edited at any point.
Status	string	Specifies whether the object is 'Accepted' or 'Archived'. If you want to retrieve the current information, select 'Accepted'. If you want to retrieve deleted objects, select 'Archived'.
Workspace	string	The name of the business unit. If the business units functionality is not enabled, the value is always the same - the company name displayed in UI.
Object_Properties_Name	string	If the property starts with "Object_Properties", it is the information of "Object Properties" and not of "Questionnaire".
General___Application_More_Info_x2Ex2Ex2E	Depends on the type of the field: Checkbox: boolean Currency: number Number: number Date: string in ISO 8601 UTC format Everything else: string

Relationships

Below is a table listing the properties you can expect when requesting the collection of relationships.

Response properties

Property	Type	Description
Id	string	Unique identifier of the relationship
RelationshipId	string	Unique identifier of the object combination
BlueDolphinObjectItemId	string	Unique identifier of the object from which the relationship goes. Use this ID to connect to an object ID.
RelatedBlueDolphinObjectItemId	string	Unique identifier of the object to which the relationship goes. Use this ID to connect to an object ID and find the related object.
RelationshipDefinitionId	string	Unique identifier of the relationship definition
RelationshipDefinitionName	string	Name of the relationship as shown in the field "Name" in UI
Type	string	Type of the relationship as shown in the field "Based on" in UI
Name	string	Name of the relationship. There are two possible values for each relationship type, for example 'aggregates' and 'aggregated by'.
IsRelationshipDirectionAlternative	boolean	Specifies if the direction of the relationship is alternative. Possible values are TRUE or FALSE, but FALSE is usually used.
Status	string	Specifies the status of the relationship. The only possible value in a response is accepted (2).
Remark	string	Label of the relationship
Description	string	Returns an empty string in a response
CreatedBy	string	The name of the user who created the relationship
CreatedOn	string	Creation timestamp in ISO 8601 UTC format
ChangedBy	string	The name of the user who made a change
ChangedOn	string	Change timestamp in ISO 8601 UTC format

History

Depending on the category you select, the expected response should contain the values for the main properties plus the properties from the selected category. You can expect the rest of the fields to return empty strings. The groups and belonging properties are listed in the tables below.

Response properties

Main properties

Property	Type	Description
Id	string
TargetId	string
ChangedBy	string
Action	string	Specifies the action performed. Possible values are: added changed deleted officialized published saved as shared with or unshared with
Category	string
Timestamp	string
FieldId	string

Objects

Objects general fields

Property	Type
GeneralFieldName	string
GeneralFieldInput	string
GeneralFieldInputOld	string

Object relationship fields

Property	Type
Relationship	string
RelationshipOld	string
Label	string
LabelOld	string
ToObject	string
ToObjectOld	string
ToObjectId	string
ToObjectOldId	string

Object questionnaire fields

Property	Type
QuestionFieldName	string
QuestionFieldNameOld	string
QuestionFieldInput	string
QuestionFieldInputOld	string
QuestionnaireId	string
QuestionnaireName	string

Views

Actions

Property	Type
ActionsDescription	string
ActionsValue	string
ActionsValueOld	string

Objects

Property	Type
ObjectsObject	string

Relationships

Property	Type
RelationshipsRelationship	string
RelationshipsFrom	string
RelationshipsTo	string

Data objects

Property	Type
DataobjectTermsKeysDataObject	string
DataobjectTermsKeysTerm	string
DataobjectTermsKeysKey	string
DataobjectTermsKeysKeyOld	string

Data connections

Property	Type
DataconnectionsFromObject	string
DataconnectionsFromObjectOld	string
DataconnectionsToObject	string
DataconnectionsToObjectOld	string
DataconnectionsFrom	string
DataconnectionsFromOld	string
DataconnectionsTo	string
DataconnectionsToOld	string

Lines

Property	Type
LinesLine	string
LinesLineOld	string
LinesFrom	string
LinesFromOld	string
LinesTo	string
LinesToOld	string
LinesText	string
LinesTextOld	string

Shapes

Property	Type
ShapesShape	string
ShapesText	string
ShapesTextOld	string

Information

This endpoint returns the basic information about a tenant in BlueDolphin. It is primarily used to test the OData connection before starting to work with real resources.

Response properties

Property	Type	Description
Name	string	The name of the tenant in the database
Customername	string	The friendly name of the tenant that is displayed in UI
Language	string	Specifies whether the language of the tenant is English (EN) or Dutch (NL)