Here we describe the steps for creating a new object definition. Any time there is a need within an organization to extend the convention model, this can be achieved by adding a new definition to the repository.
Note: It is not possible to add new BPMN object definitions via the API.
HTTP responses
HTTP response status code | Interpretation |
201 OK | Object definition created successfully |
400 Bad Request | One or more parameters are missing or incorrect |
401 Unauthorized | Invalid or missing API key secret and/or tenant |
403 Forbidden | The user is not allowed to create this object definition |
Prerequisites
Before you can start working with object definitions, make sure that available object templates and their IDs are available upfront.
To be able to add new definitions, you will also need a list of roles and their IDs. Then, from this list select those that will be enabled for a specific object definition. To access the list of available roles and their IDs, use the SCIM endpoint Get groups, where groups in SCIM are equivalent to roles in BlueDolphin.
To create a new object definition, make a POST request to the /object-definitions endpoint specifying:
Resource/endpoint destination URL
The header for your API request
The request body, which must include:
Parameter | Required | Type | Description |
name | ✓ | string | The name of the object definition. It must be unique in the tenant and contain at least one and not more than 256 characters. |
object_template_id | ✓ | string | Unique identifier for a template based on which the definition is created. |
roles | ✓ | array | A list of role IDs for which the definition has been enabled. |
Here is an example API request which shows how to create a new object definition with the name New Application of the template type Application Component.
curl -L 'https://public-api.eu.bluedolphin.app/v1/object-definitions' \
-H 'x-api-key: YOURAPIKEYSECRET' \
-H 'tenant: yourtenantname' \
-H 'Content-Type: application/json' \
-d '{
"name": "New Application",
"object_template_id": "6194ff942e86804e0c21c649",
"roles": [
"63f61f77d32a6efc5d8630a3", "63f61f77d32a6efc5d8630c6"
]
}'Response properties
Property | Type | Description |
id | string | Unique identifier for the object definition |
name | string | The name of the object definition |
type | object | Object type that the object definition is based on |
type[].id | string | Unique identifier for the object type |
type[].name | string | The name of the object type |
type[].name_internal | string | The internal name of the object type |
type[].category | string | The category of the object type |
type[].category_internal | string | The internal category of the object type |
type[].color | string | The hexadecimal color code of the object definition or object in lists and views. For example, the color blue (#1EAAF0) is used for application layer. |
status | number | The status of the object definition, which is always 0 (enabled) after creation |
object_properties | array | A list of object properties |
object_properties[].name | string | The name of the object property |
object_properties[].value | string | The value of the object property |
related_boem | array | A list of related object questionnaires |
related_boem[].id | string | Unique identifier for the related object questionnaire |
related_boem[].name | string | The name of the related object questionnaire |
A successful call returns a response with a 201 OK HTTP status code and the following body:
{
"id": "64a42dc72539a230838f9d22",
"name": "New Application",
"type": {
"id": "6194ff942e86804e0c21c649",
"name": "Application Component",
"name_internal": "application_component",
"category": "Applicationlayer",
"category_internal": "application_layer",
"color": "#1EAAF0"
},
"status": 0,
"object_properties": [
{
"name": "Name",
"value": ""
}
],
"related_boem": []
}
A new object definition with the id 64a42dc72539a230838f9d22 has now been created.
The response also includes the location response header that indicates the URL to the newly created object definition. So, the location header for the previous example would be http://public-api.eu.bluedolphin.app/v1/object-definitions/64a42dc72539a230838f9d22.