500 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

PUT http://host:port/app/api/json/collection/{actionName}/{id}

since 11.12

PUT http://host:port/app/api/json/collection

Legacy endpoint:

http//host:port/app/_plugins/WXM_RESTAPI/page/collection/add.jspz

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

{
  "actionName": "mycollection",
  "response": {
    "createdId": "35"
  },
  "status": 201,
  "time": 433
}

The endpoint response call contains the identifier of the newly created resource (createdId field).

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

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