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

EndPoint: delete all elements of a collection

since 11.14

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

since 11.12

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

Legacy endpoint:

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

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).

{
  "actionName": "mycollection",
  "response": {
    "notDeleted": ["3","12","35"]
  },
  "status": 202,
  "time": 433
}

or 200 status if all elements are deleted

{
  "actionName": "mycollection",
  "response": {
    "notDeleted": []
  },
  "status": 200,
  "time": 421
}

or 404 status if there are no elements

{
  "actionName": "mycollection",
  "response": {
    "notDeleted": []
  },
  "status": 404,
  "time": 12
}

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