Getting started

This article is your guide to working with the 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.

Please note that BlueDolphin OData supports only basic authentication. Using the Anonymous method is not advised. If, however, you have used Anonymous authentication, you must clear the cache to be able to use the service (again).

Currently, OData for BlueDolphin only supports GET operations or requests.

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 encoded value of the character (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	Filters can be set to limit the number of objects returned from BlueDolphin. For example, get-bdrelation -filter "Name eq 'accesses'" Returns all relationships named "accesses". (Typically, when using the Name property, the result will contain 1 direction only)
$orderby	By default, the BlueDolphin OData feed doesn’t use any ordering. Add this parameter to use a specific sorting method for your query. Note: When using a $skip-and-$top sequence to get all data, you must specify the $orderby parameter, such as by ID.
$select	Used to specify which properties (fields) of an entity should be returned. For example, $select {"Id", "title"}
$skip	it is used to implement pagination when retrieving data through a GET method. Its purpose is to identify a subset of entities in a collection by skipping a specified number of items.
$top	for example, if the value = 10, then it returns the first top 10 items.
$count	Only applicable to the history endpoint

Sample query with $filter and $select combined

https://{tenantname}.odata.bluedolphin.app/objects?$filter=Definition eq 'Capability(CA)' and Status eq 'Accepted' &$select=Title,Definition,Status

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.

Filter functions

Without filter, BlueDolphin returns all the objects but filters can be set to limit the number of objects returned.

Parameters:

Strings need to be enclosed with single quotes ('')
-filter "<property> <operator> <'string'>"

-filter "<property> <operator> <true/false>"

For example, to return all objects of the Business Process with a test in the title,

C:\PS> get-bdobject -filter "Definition eq 'Business Process' and contains(Title,'test')"

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 specifications, see the official OData documentation.

Objects

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

The resource destination URL is https://{tenantname}.odata.bluedolphin.app/objects, where {tenantname} is unique to your tenant.

Response properties

Property	Type	Description
ID	string	The 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	The 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	The timestamp of the creation in ISO 8601 UTC format
CreatedBy	string	The name of the user who created the object
ChangedOn	string	The timestamp of the change in ISO 8601 UTC format. Not filled if an object is only created.
ChangedBy	string	The name of the user who made the 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	The 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.

The resource destination URL is https://{tenantname}.odata.bluedolphin.app/relations, where {tenantname} is unique to your tenant.

Response properties

Property	Type	Description
Id	string	Unique identifier for the relationship
RelationshipId	string	Unique identifier for the object combination
BlueDolphinObjectItemId	string	Unique identifier for the object from which the relationship goes. Use this ID to connect to an object ID.
RelatedBlueDolphinObjectItemId	string	Unique identifier for 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 for the relationship definition
RelationshipDefinitionName	string	The name of the relationship as shown in the field "Name" in UI
BlueDolphinObjectWorkspaceName	string	The name of the workspace where the "from" or "source" object resides
BlueDolphinObjectDefinitionName	string	The name of the definition for the "from" or "source" object
RelatedBlueDolphinObjectWorkspaceName	string	The name of the workspace where the "to" or "target" object resides
RelatedBlueDolphinObjectDefinitionName	string	The name of the definition for the "to" or "target" object
Type	string	The type of the relationship as shown in the field "Based on" in UI
Name	string	The 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. Possible values are: Unknown (0) Proposed (1) Accepted (2) Declined (3) Disabled (4) Archived (5)
Remark	string	The 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	The timestamp of the creation in ISO 8601 UTC format
ChangedBy	string	The name of the user who made the change
ChangedOn	string	The timestamp of the change 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.

The resource destination URL is https://{tenantname}.odata.bluedolphin.app/history, where {tenantname} is unique to your tenant.

Response properties

Main properties

Property	Type	Description
Id	string	History id
TargetId	string	Id of the object
ChangedBy	string	The name of the user
Action	string	Specifies the action performed. Possible values are: added changed deleted officialized published saved as shared with or unshared with
Category	string	Object_relationship Object_general object_questionnaire
Timestamp	string	last changed date
FieldId	string	For Object_relationship: relationship id Object_general: property fields name object_questionnaire: id of the question

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.

The resource destination URL is https://{tenantname}.odata.bluedolphin.app/information, where {tenantname} is unique to your tenant.

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)