Attribute

Properties of an attribute.

Name	Type	Description
id	int	Unique ID of the attribute.
name	string	Unique name within your user account
execute_always	bool	Even if the date is past, the entry belonging to this attribute will always be executed once per API-Key (when the date isn't more than 60 days past)
no_db	bool	Entries created for this attribute won't be saved in the database. They are only sent once over the socket server
rights	string, RO	Readonly: Specifies the rights of the currently authenticated token for entries created with this attribute. This field can contain the values read, write and all
default_right	string	Default access rights for this attribute if the right is not overwritten by a specific token. Available values are read, write, all and none. Defaulting to all. It does overwrite the global token rights only if it is set to all or the attribute ones are set to none
sort_order	int	Indicates the ascending sort order of the attributes in all responses
exec_response	bool	Deprecated: The response of the execution is returned to the client. no_db is always true for this type. The entry will be executed immediately
icon	string	SVG icon of the attribute
execution_response	ExecResponse	The response of the execution is returned to the client. See the below description of the object Exec Response for more information
parameters	AttributeParameter	Available parameters for this attribute. See the below description of the object Attribute parameter for more information

Exec Response

With the field execution_response you are able to receive an execution response for your script execution. This contains the messages written to stdout and stderr and the exit code. Take a look at Create single entry for an example response.

Name	Type	Description
enabled	bool	Weather this feature is enabled
default_timeout	int	The default time to wait for an execution response in seconds (0 - 60 seconds). If no response of the clients is received, an error is returned
allowDelayedExecution	bool	By default, the attribute must be of type no_db and the execution is performed immediate. This field disables these two "restrictions". Please take in mind that you may not receive an execution response as a result of entry creation

Attribute parameter

An entry can be created with up to six parameter values. The number of available parameters and these settings are managed over this object.

Name	Type	Description
id	int	Unique ID of the parameter
name	string	Unique name of the parameter in the context of an attribute
position	int	Position of the parameter while calling a program
type	string	Data type of the parameter. Available values are text, number, boolean
force_preset	bool	The entry has to use one of the predefined values and cannot provide a value by itself
presets	ParameterPresets[]	Predefined parameter presets for this parametes

Parameter presets

To make the management of available parameter values for an entry easier, predefined values can be specified for an attribute that the entry may use. These are always created in the context of a specify attribute and cannot be reused across other attributes.

Each parameter contains the following fields.

Name	Type	Description
name	string	The unique name of the parameter within the attribute. This name will also be displayed in the client as the parameter
name_short	string	A short abbrevation name where the full parameter name would be too long (e.g. for the fast overview)
value	string	The value of the parameter which will be used for executing the program
sort_order	int	Indicates the ascending sort order of the parameters in which they are returned to the client

Warning

Even though all fields of the parameters can be updated, it is not recommended to remove or update the name of a parameter. This could lead to problems for existing entrys because the paraemter cannot be resolved anymore.

Attribute parameter (old, deprecated)

To make the management of available parameter values for an entry easier, predefined values can be specified for an attribute that the entry may use. These are always created in the context of a specify attribute and cannot be reused across other attributes. Even though the parameters can be updated it is not recommended to remove or update the name of a parameter. This could lead to problems for existing entrys because the paraemter cannot be resolved anymore.

The following additional fields are available for attributes (deprecated).

Name	Type	Description
force_parameter	bool	The entry has to use one of the predefined values and cannot provide a value by itself
parameter	Parameter[]	The available parameter values for this attribute

Parameter properties (deprecated)

Each parameter contains the following fields.

Name	Type	Description
name	string	The unique name of the parameter within the attribute. This name will also be displayed in the client as the parameter
name_short	string	A short abbrevation name where the full parameter name would be too long (e.g. for the fast overview)
value	string	The value of the parameter which will be used for executing the program
sort_order	int	Indicates the ascending sort order of the parameters in which they are returned to the client

Get all attributes (GET /attribute)

Details

Returns all attributes of a user. Attributes for which the token has no rights are ignored from response.

Request parameters

In the request parameters you can filter after specific fields. These are concanated with a logical AND.

Name	Type	Description
id	int, optional	Filter for field value
name	string, optional	""
execute_always	bool, optional	""
no_db	bool, optional	""
exec_response	bool, optional	""
righs	string, optional	""
ignore_rights	bool, optional	By default only attributes for which the token has rights for (read, write, all) are returned. With this option, all available attributes will be returned. The user has to be priveledged for this action
withIcon	bool, optional	Weather to include the SVG icon in the response. Defaulting to false
fields[]	mixed, optional	Fields to included in the response

Response

[
   {
      "id": 2,
      "name": "Notification",
      "execute_always": true,
      "no_db": false,
      "rights": "all",
      "default_right": "none",
      "parameters":[
         {
            "id": 2,
            "name": "Message",
            "position": 1,
            "type": "text",
            "force_preset": false,
            "presets": []
         },
         {
            "id":128,
            "name":"Receiver",
            "position":2,
            "type":"text",
            "force_preset":true,
            "presets":[
               {
                  "name":"Günther",
                  "name_short":null,
                  "value":null,
                  "sort_order": 0
               },
               {
                  "name":"Linus",
                  "name_short":null,
                  "value":null,
                  "sort_order": 0
               },
               {
                  "name": "Olaf",
                  "name_short": null,
                  "value": null,
                  "sort_order": 0
               }
            ]
         }
      ],
      "execution_response":{
         "default_timeout": 15,
         "allow_delayed_execution": false,
         "enabled": false
      },
      "sort_order": 2,
      "force_parameter": false
   }, 
   {
      "id": 23,
      "name": "Beauty attribut",
      "execute_always": false,
      "no_db": false,
      "rights": "all",
      "parameters":[
         {
            "id": 9,
            "name": "1. Parameter",
            "position": 1,
            "type": "text",
            "force_preset": false,
            "presets": [ ]
         }
      ],
      "execution_response":{
         "default_timeout": 15,
         "allow_delayed_execution": false,
         "enabled": false
      },
      "sort_order": 9,
      "exec_response": false,
      "force_parameter": false,
      "parameter":[ ]
   }, // etc ...
]

Response codes

• 200 Attributes returned
• 204 when no attributes were found
• 400 Invalid field or field values
• 401 Authentication failed

Get single attribute (GET /attribute/{id}[/{field}])

Details

Returns a single attribute. Attributes for which the token has no rights cannot be fetched (unless the user is priveleged).

Request parameters

Name	Type	Description
{id}	int	The unique ID of the attribute
{field}	string, optional	Single field to return in response. For icon, this will return the icon directly instead of a JSON response
fields[]	mixed[], optional	Fields to included in the response
withIcon	string, optional	Weather to include the SVG icon in the response

Response

{
    "id": 23,
    "name": "Beauty attribut",
    "execute_always": false,
    "no_db": false,
    "rights": "all",
    "parameters":[
        {
            "id": 9,
            "name": "1. Parameter",
            "position": 1,
            "type": "text",
            "force_preset": false,
            "presets": [ ]
        }
    ],
    "execution_response":{
        "default_timeout": 15,
        "allow_delayed_execution": false,
        "enabled": false
    },
    "sort_order": 9,
    "exec_response": false,
    "force_parameter": false,
    "parameter":[ ]
}

Response codes

• 200 Attribute returned
• 400 Invalid ID or fields supplied
• 401 Authentication failed
• 412 The token used to fetch the attribute has no right on this attribute

Create attribute (POST /attribute)

Details

Creates an attribute.

Request body

See properties for values, example:

{
   "name": "New Attribute",
   "execute_always": true
}

Response body

See action get single attribute for a response body.

Response codes

• 201 Attribute created
• 400 Invalid values for fields supplied
• 401 Authentication failed
• 409 An attribute with the same name already exists
• 404 The given attribute was not found

Delete attribute (DELETE /attribute/{id})

Details

Deletes a single attribute.

Request parameters

Name	Type	Description
{id}	int	The unique ID of the attribute

Response codes

• 200 Attribute deleted
• 400 Invalid ID supplied
• 401 Authentication failed
• 404 The attribute was not found
• 412 The token used to fetch the attribute has no right on this attribute

Update attribute (PUT /attribute/{id})

Details

Updates an attribute.

Request parameters

Name	Type	Description
{id}	int	The unique ID of the attribute

Request body

See properties for values and Create attribute for an example.

Response

See action Get single attribute for a response body.

Response codes

• 200 Attribute updated
• 201 Attribute was not updated because nothing was changed
• 400 Invalid ID supplied
• 401 Authentication failed
• 404 The attribute was not found
• 412 The token used to fetch the attribute has no right on this attribute (for attribute update the rights all or write are needed)

Patch sorting of attributes (PATCH /attribute/sort)

Details

Patches the sorting of all provided attributes.

Request body

Only the properties id and sort_order are available for patching the attributes. For The Attribute Parameters you have to specifiy the field name to identify the parameter.

[
    {
        "id": 123,
        "sort_order": 3,
        "parameter": [
            {
                "name": "Name",
                "sort_order": 0
            }
        ]
    }
]

Response codes

• 201 The sorting was updated
• 400 Invalid values for fields supplied
• 401 Authentication failed
• 412 The token used to update the sorting was not priveledged

Patch sorting of attribute (PATCH /attribute/{id}/sort)

Details

Patches the sorting of the given attribute.

Request body

Only the properties id and sort_order are available for patching the attributes. For The Attribute Parameters you have to specifiy the field name to identify the parameter.

{
    "id": 123,
    "sort_order": 3,
    "parameter": [
        {
            "name": "Name",
            "sort_order": 0
        }
    ]
}

Response codes

• 201 The sorting was updated
• 400 Invalid values for fields supplied
• 401 Authentication failed
• 412 The token used to update the sorting was not priveledged

Patch attribute (PATCH /attribute/{id})

Details

Patches an attribute.

See Update attribute for more information. At least one property of the attribute has to be specified.