Handle Collections

Introduction

This service is used to create object instances by linking them as collection elements, or to delete all instances related to a given object.

Object collections, or collection objects can be handled.
For instance for the given object:

foo
- id
- name
- item   (collection relationship attribute to object of type bar)

bar
- id
- name

The foo object is called collection root.

Configuration

For each action, there is a corresponding identifying name, and its configuration JSON.

JSON example

{
  "Objectname": "the object and collection name",
  "Field": "the name of the collection type collection object property (on itself)",
  "Rootobjectname": "a possible object name that has a collection type property that is not the nature of this collection (the root object)",
  "Rootfield": "the name of the collection property on objectname of the rootobjectname object (the root object collection type object property)",
  "clear": true, // indicates whether it is allowed to delete all the collection elements related to a given object
  "props": { // list of changeable properties, and their configuration
    "Property name": null
  }
}

Properties and sections

objectname: String - Object name (type) (shall have a collection type property)
description: String - Short description of action
Field: Name of the collection type property towards objectname
rootobjectname: Name of the object that has a collection type property on objectname
rootfield: The name of the collection of rootobjectname
props: Section properties An object which properties are property names that should be exported. It is possible to configure some options, and some formating action or value validation. But it has limitation for a complex rule, the trigger should be used. (Cf. Properties configuration)

EndPoints

There are two endpoints available

To add an element to the collection
To delete all elements of the collection related to an instance (and recursively all elements related to those elements)

To delete an element in collection use endpoint delete.

EndPoint: add an element to a collection

since 11.14

since 11.12

Legacy endpoint:

Available method: PUT

Parameters

actionName: Character string, action identifier
id (or form_id): Current instance identifier
prop_<x>: Value to assign the x property
root: Boolean that indicates if the instance is the root object (true), or a collection element (false)

Response format

Security

The collection_add action of RESTAPI domain allows to manage the endpoint call authorization. There are two parameters:

surfer: surfer
actionName: used action identifier

Errors codes

HTTP Code	API Code	Definition

HTTP Code	API Code	Definition
404	404/400	Unknown action
403	403/401	Forbidden addition
403	403/403	The user grants doesn’t allow to add
422	422/400	Impossible to modify (configuration problem)

EndPoint: delete all elements of a collection

since 11.14

since 11.12

Legacy endpoint:

Available method: DELETE

Parameters

actionName: Character string, action identifier
id (or form_id): Current Instance identifier
root: Boolean that indicates if the instance is the root object (true) or a collection element (false)

Response format

The endpoint call response contains the potential items identifiers that aren’t deleted (202 status).

or 200 status if all elements are deleted

or 404 status if there are no elements

Security

The collection_clear action of RESTAPI domain allows to manage the endpoint call authorization. There are two parameters:

surfer: surfer
actionName: used action identifier

Errors codes

HTTP Code	API Code	Definition

HTTP Code	API Code	Definition
404	404/400	Unknown action
403	403/401	Forbidden addition
403	403/403	The user grants doesn’t allow to add
422	422/400	Impossible to modify (configuration problem)