Versions Compared

Old Version 3

changes.mady.by.user Jules DELEUZE (Unlicensed)

Saved on

compared with

New Version 4

changes.mady.by.user Jules DELEUZE (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Anchor
Introduction
Introduction
300 Create Or Modify

The endpoints of this service allow createation or modification of the object instances. It is required to configure the service like for the views.


Anchor
Configuration
Configuration
300 Create Or Modify

Each action is associated to an identifier and a configuration JSON.

JSON example

Code Block
{
  "objectname": "name of the object",
  "create": true, // indicates if new instances creation is allowed
  "patch": false, // indicates if partial modification of properties is allowed
  "workflow": true, // indicates if workflow modification (per action) is allowed
  "props": { // List of modifiable properties and their configurations
    "name of the property": null
  }
}


Properties and sections

  • objectname: String - Name of the object (type)

  • description: String - Short description of action

  • 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. hereafter for the configuration detail.

  • create: A boolean to allow creation

  • patch: A boolean to allow the modification of some specific properties (by default all configured properties shall be filled)

  • workflow: A boolean that allows to modify the workflow (thru workflow actions)

  • lock: A boolean that allows to lock or unlock objects

  • since 11.11reportprops: an array of properties of the created object that you want to include in the response

  • since 11.12updatequery: An optional selection request following JSON type specific language used within "create or update" mode. The values of the key properties (or others) are configurable in the query by the syntax ${<variable identifier>}:

    • to reference a key property, use its name as identifier
      example: ${name}

    • to reference the associated property in the clause, simply use a question mark (?)
      example: ${?}

    • to reference any parameter of the http request, prefix the name of parameter with "par:".
      example: ${par:p_activated}

    For example:

    Code Block
    {
  "product": "${?}",
  "businessunit": "${?}"
}


Properties configuration

It is possible to configure the assignment of a value to a property by defining a configuration object for the property.
If no configuration is defined, a null object shall be defined:

Code Block
"props": {
  "name": null
}


Depending on the data types, several configuration can be done: the indicators which are not corresponding to the available properties will be ignored. The configuration is split in 4 sections:

  • check: verification

    • pattern: allows the indication of a regular expression that value must verify (works with character string: text, data/word, sentence, html, image access path and file path (in this case backslashes should be considered as slashes) For example:

      Code Block
      "file": {
  "check": {
    "pattern": "^.*\\.(docx|doc)$"
  }
}


    • min: allows the definition of a minimal value included in the interval (works with numbers: integer, floating, currencies) For example:

      Code Block
      "nbr": {
  "check": {
    "min": 1
  }
}


    • max: allows the definition of a maximal value included in the interval (works with numbers: integer, floating, currencies) For example:

      Code Block
      "Quarter": {
  "check": {
    "min": 1,
    "max": 4
  }
}


    • values: Allows the indication of a list of value (table), among which the assigned value must be available (works for character string and numbers) For example:

      Code Block
      "code": {
  "check": {
    "values": ["ARPA","TEGA","GOBA","NBPC"]
  }
}


  • format: formating

    • trim: allows deletion of useless white spaces

      • right: delete right white spaces For example:

        Code Block
        "value": {
  "format": {
    "trim": "right"
  }
}


      • left: delete left white spaces For example:

        Code Block
        "value": {
  "format": {
    "trim": "left"
  }
}


      • true: delete right and left white spaces For example:

        Code Block
        "value": {
  "format": {
    "trim": true
  }
}


        replace: allows replacement of some part of a character strings. Value is an object with two properties

      • pattern: a regular expression

      • replace: the replacing string

      For example, to put all numbers between parenthesis except if they already are:

      Code Block
      "value": {
  "replace": {
    "pattern": "(?<!\\()(\\d++)(?!\\))", "replace": "($1)"
  }
}


    • case: to change the case

      • upper: to go uppercase

      • lower: to go lowercase

      • sentence: to have the full sentence in lowercase and only the first letter in uppercase

      • word: to have all characters in lowercase except the first letter of each word that will be in uppercase

  • i18n: localization

    By default whenever a localized property is modified, the property corresponding to the language of the request is modified (lang parameter).
    For example, if a property value (i18n), value_fr (i18n of value), value_en (i18n of value)

    1. If the request local is en

    2. If we modify value, then value_en is modified

    3. If we modify value_fr, then value_en is modified

    This configuration property allows to modify this default behavior.

    • true: the hereinabove rules are applied

    • false: the specified property is modified. If we keep the same examples:

      • (3) If we modify value, then value is modified

      • (4) If we modify value_fr, then value_fr is modified

    So if false then we only modify specified property else we check if the property is in the correct local; if true the correct local is directly modified; if default we raise an exception.

  • since 11.11byvalue: a boolean to enabled relational relationships assignation or creation by value (see create). Default to false. When this option is set to true, for relational properties, values can be passed instead of object identifiers. The corresponding object is searched for and if it does not exist, it is created with the specified value as its name. Finally, it is the object identifier that is affected. Use formatting options to limit the creation of duplicates.

  • since 11.11valueProperty: if relational relationships assignation is selected, indicates the name of property used to find the object corresponding to the value. it is possible to specify an array of properties if the object must be created or selected in relation to several values: in that case, the value of the parameter must be a json object, with all properties and their respective value.

  • since 11.11create: a boolean to enabled creation by value (see byvalue). Default to true.

  • since 11.18lockCaptureTimeout: the timeout value to capture a lock used with "by value" mode to handle simultaneous access (in seconds)

  • since 11.18lockAcquireTimeout: the timeout value to acquire a lock used with "by value" mode to handle simultaneous access (in seconds)

  • since 11.11pathseparator: a regular expression to break the paths into names. Default is \ (example of value: Europe \ Great Britain \ England \ (Greater) London \ City of London \ Hampstead).When assigning by value (see byvalue), it is possible to manipulate tree-like data by specifying a path, consisting of several successive names. The division of the value into names of the different objects is done according to this regular expression.

    For example:

    Code Block
    "metadatalocation": {
  "byvalue": true,
  "format": {
    "trim": true,
    "case": "sentence"
  },
  "pathseparator": "\|"
}


  • force: a boolean to force the modification of status property. By default, it is not possible to modify the assignment of position 7 property (status): a workflow action is required. But for ascending compatibility with the former workflow system, it is possible to modify the status by a value assignment via this property.

  • since 11.12key: a boolean to set this property as key for the "create or update" mode. This feature is not yet supported for children or collection properties.

EndPoints

There are seven endpoints available

  • To modify, partially modify or create

  • To modify a workflow by an action

  • To get the list of workflow actions

  • To get the list of available actions

  • To get object locks

  • To lock objects

  • To unlock objects

EndPoint: modify

since 11.14

Code Block
PUT http://host:port/app/api/json/update/{actionName}/{id}
PATCH http://host:port/app/api/json/update/{actionName}/{id}


since 11.12

Code Block
PUT http//host:port/app/api/json/update
PATCH http//host:port/app/api/json/update
PUT http//host:port/app/api/json/update
PATCH http//host:port/app/api/json/update




Legacy endpoint:
Code Block
http//host:port/app/_plugins/WXM_RESTAPI/page/update.jspz


Supported methods: PUT, PATCH

The difference between the two methods is that PUT imposes the modification of all configured properties whereas PATCH allows the modification of some properties

Parameters

  • actionName: Character string, action identifier

  • id (or form_id): Identifier of the current instance

  • prop_<x>: the value to assign to the x property (cf. hereafter properties values assignment)

  • since 11.12rawValues Boolean - Indicates if we apply the localization (false by default) in reported properties

  • since 11.12headers: Boolean - Indicates if headers are required (Cf. hereafter, response format) (false by default)

  • since 11.12report: Boolean - Indicates if properties of the created object must be reported (if configured so) (true by default)

Security

The update action of the RESTAPI domain allows the management of the endpoint call authorisation.
There are two parameters:

  • surfer: surfer

  • actionName: the action identifier

Errors codes

HTTP CodeAPI CodeDefinition

404

404/200

Unknown action

403

403/201

Forbidden modification

403

403/202

Forbidden partial modification

403

403/204

The user grants doesn’t allow to modify an object

403

403/205

The user grants doesn’t allow to modify this object

403

403/206

Forbidden to modify a property

404

404/900

Object not found

400

400/900

Missing content

since 11.11 400

400/900

Not allowed value

since 11.11 400

400/900

Not allowed to creae value

since 11.11 500

500/901

Cannot create value (server error)


EndPoint: create

since 11.14

Code Block
POST http://host:port/app/api/json/create/{actionName}


since 11.12


Code Block
POST http://host:port/app/api/json/update


Legacy endpoint:


Code Block
http//host:port/app/_plugins/WXM_RESTAPI/page/update.jspz


Supported method: POST

Parameters

  • actionName: Character string, action identifier

  • prop_<x>: The value assigned to the x property (cf. hereafter properties values assignment)

  • since 11.11rawValues Boolean - Indicates if we apply the localization (false by default) in reported properties

  • since 11.11headers: Boolean - Indicates if headers are required (Cf. hereafter, response format) (false by default)

  • since 11.11report: Boolean - Indicates if properties of the created object must be reported (if configured so) (true by default)

Response format

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

Code Block
{
  "actionName": "asset",
  "response": {
    "createdId": "10004"
  },
  "status": 201,
  "time": 1435
}


Security

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

  • surfer: surfer

  • actionName: the action identifier

Errors codes

HTTP CodeAPI CodeDefinition

404

404/200

Unknown action

403

403/200

Forbidden creation

403

403/202

Forbidden partial modification

403

403/203

The user grants doesn’t allow to create an object

400

400/900

Missing content

since 11.11 400

400/900

Not allowed value

since 11.11 400

400/900

Not allowed to creae value

since 11.11 500

500/901

Cannot create value (server error)


EndPoint: Apply workflow action

since 11.14

Code Block
PATCH http://host:port/app/api/json/workflow/{actionName}/{id}


since 11.12
Code Block
PATCH http://host:port/app/api/json/workflow


Legacy endpoint:
Code Block
http//host:port/app/_plugins/WXM_RESTAPI/page/workflow/do.jspz


Supported method: PATCH

Parameters

  • actionName: Character string, action identifier

  • id (or form_id): Identifier of current instance

  • action: Identifier or name of the action to be applied

Security

The workflow_do action of RESTAPI domain allows the management of the endpoint call authorization.
There are two parameters:

  • surfer: surfer

  • actionName: the action identifier

Errors codes

HTTP CodeAPI CodeDefinition

404

404/200

Unknown action

403

403/207

Forbidden workflow modification

403

403/208

Forbidden workflow action


EndPoint: list of available workflow actions

since 11.14

Code Block
GET http://host:port/app/api/json/workflow/{actionName}/{id}
HEAD http://host:port/app/api/json/workflow/{actionName}/{id}


since 11.12


Code Block
GET http://host:port/app/api/json/workflow


Legacy endpoint:

Code Block
http//host:port/app/_plugins/WXM_RESTAPI/page/workflow/actions.jspz


Supported methods: GET, HEAD

Parameters

  • actionName: Character string, action identifier

  • id (or form_id): Instance identifier for which we want to know the available actions

  • rawValues: Boolean that indicates if we need to localize terms (false by default)

  • onlyAllowed: Boolean, optional, to get only allowed action by the user (false by default)

Response format

Code Block
{
  "response": {
    "data": {
      "Action identifier": "action label, or action name in rawValues mode"
    }
  },
  "status": 200,
  "time": 11121
}


Security

The workflow_actions action of RESTAPI domain allows the management of the endpoint call authorization.
There are two parameters:

  • surfer: surfer

  • actionName: the action identifier

EndPoint: obtain the status of object locks

since 11.14

Code Block
GET http://host:port/app/api/json/lock/{actionName}/{id*}
HEAD http://host:port/app/api/json/lock/{actionName}/{id*}


since 11.12


Code Block
GET http://host:port/app/api/json/lock


Legacy endpoint:
Code Block
http//host:port/app/_plugins/WXM_RESTAPI/page/getlocks.jspz


Supported methods: GET, HEAD

Parameters

  • actionName: Character string, action identifier

  • id (or form_id): The identifier of the instance to be locked (multiple possible values)

Response format

Code Block
{
    "actionName": "asset",
    "response": [
        {
            "id": "1444",
            "locked": true,
            "owner": "user122"
        },
        {
            "id": "1051",
            "locked": false,
            "owner": null
        },
    ],
    "status": 200,
    "time": 44
}


Anchor
Security
Security
300 Create Or Modify

The locks_get action of RESTAPI domain allows the management of the endpoint call authorization.
There are two parameters:

  • surfer: surfer

  • actionName: the action identifier

Errors codes

HTTP CodeAPI CodeDefinition

403

403/210

Forbidden action


EndPoint: put locks on objects

since 11.14

Code Block
POST http://host:port/app/api/json/lock/{actionName}/{id*}


since 11.12


Code Block
POST http://host:port/app/api/json/lock


Legacy endpoint:
Code Block
http//host:port/app/_plugins/WXM_RESTAPI/page/lock.jspz


Supported methods: POST

Parameters

  • actionName: Character string, action identifier

  • id (or form_id): The identifier of the instance to be locked (multiple possible values)

  • duration: Number, optional, lock duration in seconds

Response format

Code Block
{
    "actionName": "asset",
    "response": [
        {
            "id": "104",
            "locked": true,
            "status": "locked",
            "info": "user133"
        },
        {
            "id": "105",
            "locked": true,
            "status": "lock extended",
            "info": "user133"
        },
        {
            "id": "222",
            "locked": false,
            "status": "already locked",
            "info": "user122"
        },
        {
            "id": "477",
            "locked": null,
            "status": "error",
            "info": "Can't find object with id 477"
        }
    ],
    "status": 200,
    "time": 44
}


The locked property indicates if you get the lock (true) or not (false). The status property indicates the status of the object, and info specifies this status:

  • in case of error, the status is error and info is the error message. The current lock status is null if the error occurred when querying the current lock status.

  • if the instance was not locked and becomes locked, the status is locked and the info is the name of the owner of the lock (the user who is invoking the service)

  • if the instance was already locked by the calling user, the lock is extended, and the status is lock extended

  • if the instance was locked but by another user, the status is already locked and info is the current owner’s name

Security

The lock action of RESTAPI domain allows the management of the endpoint call authorization.
There are two parameters:

  • surfer: surfer

  • actionName: the action identifier

Errors codes

HTTP CodeAPI CodeDefinition

403

403/211

Forbidden lock action


EndPoint: remove locks on objects

since 11.14

Code Block
DELETE http://host:port/app/api/json/lock/{actionName}/{id*}


since 11.12


Code Block
DELETE http://host:port/app/api/json/lock


Legacy endpoint:
Code Block
http//host:port/app/_plugins/WXM_RESTAPI/page/unlock.jspz


Supported methods: DELETE

Parameters

  • actionName: Character string, action identifier

  • id (or form_id): The identifier of the instance to be locked (multiple possible values)

Response format

Code Block
{
    "actionName": "asset",
    "response": [
        {
            "id": "124",
            "locked": false,
            "status": "not locked",
            "info": null
        },
        {
            "id": "118",
            "locked": false,
            "status": "unlocked",
            "info": null
        },
        {
            "id": "222",
            "locked": true,
            "status": "not owner",
            "info": "user122"
        },
        {
            "id": "477",
            "locked": null,
            "status": "error",
            "info": "Can't find object with id 477"
        }
    ],
    "status": 200,
    "time": 44
}




The locked property indicates if the object is still locked (true) or not (false). The status property indicates the status of the object, and info specifies this status:

  • in case of error, the status is error and info is the error message. The current lock status is null if the error occurred when querying the current lock status.

  • if the instance wasn’t locked, the status is not locked and the info is null.

  • if the instance was locked by the calling user, the status is unlocked the info is null

  • if the instance was locked but by another user, the status is not owner and info is the current owner’s name

Security

The unlock action of RESTAPI domain allows the management of the endpoint call authorization.
There are two parameters:

  • surfer: surfer

  • actionName: the action identifier

Errors codes

HTTP CodeAPI CodeDefinition

403

403/210

Forbidden lock view

403

403/211

Forbidden lock action

403

403/212

Forbidden unlock action

403

500/200

Cannot lock object


EndPoint: list of available actions

since 11.12

Code Block
GET http://host:port/app/api/json/catalog/update


Legacy endpoint:

Code Block
http//host:port/app/_plugins/WXM_RESTAPI/page/catalog/updateaction.jspz




Supported methods: GET, HEAD

Parameters

  • actionName: Character string, an option regular expression filter (by default, all actions are accessible)

  • headers: Boolean indicates if headers are required or not (cf. hereafter, response format) (false by default).

Response format

Code Block
{
  "catalog": "List of modification action, creation and workflow actions",
  "request": {
    "parameters": {
      "headers": "true"
    }
  },
  "response": {
    "data": [ {
      "name": "name of the action",
      "actions": [ // Possible actions (create, update, patch, workflow)
        "update",
        "workflow"
      ],
      "view": "default view to get the properties",
      "properties": [ "name of property 1", "name of property 2", "name of property 3" ],
      "headers": {
        "name of the property": {
          "name": "localized label of the property",
          "type": "type of the property"
        },
        "name ot the resource type property": {
          "name": "localized label of the property",
          "type": "resource",
          "attachment": true, // true or false if the file is in attachment or not
        }
      }
    }
    ],
    "links": {
      "href": "http://host:port/app/_plugins/WXM_RESTAPI/page/catalog/updateaction.jspz?headers=true"
    },
    "status": 200,
    "time": 131
  }
}


Anchor
Security
Security
300 Create Or Modify

The catalog action of RESTAPI domain allows the management of the endpoint call authorization.
There are two parameters:

  • surfer: surfer

  • endPoint: the endpoint identifier, with update value.

Errors codes

HTTP CodeAPI CodeDefinition

403

403/209

Actions catalog not reachable


Assigning property values

To assign a value to a property, please pass the prop_ prefixed property name as a parameter, as well as its value.
For instance, to assign the value Example to the name property: prop_name=Example

Character strings

Just indicate the value. For a null value, we shall use #NULL.
Examples:

Code Block
prop_name=Example   (to assign the "Example" value)
prop_name=#null     (to assign the NULL value)
prop_name=          (to assign the Void value)


Numbers

Just mention the value. For a float number, we shall use decimal point (.) to set the decimal position. For a null value, use a void value.
Examples:

Code Block
prop_val=42
prop_val=3.14159
prop_val=


booleans

True stands for the true logical value, false for the false one or nothing for null.
Examples:

Code Block
prop_activated=true
prop_activated=false
prop_x=


dates

Dates are passed either as timestamps (UTC unix time), or in ISO format
Examples:

Code Block
prop_date="20160317T123000"
prop_date="2016-03-17T12:30:00"
prop_date=1458169200000


children (object)

Children are referenced through their ID. It is not possible to assign a non existing object.
Example:

Code Block
prop_link=10070


multiple children (array)

To assign several values we shall mention the parameter on several times.
Examples:

Code Block
prop_links=10070                                     (to assign an ID)
prop_links=10070&prop_links=10071&prop_links=10072   (to assign three IDs)
prop_metadatacategory=Manufacturing                  (to assign by value)
prop_metadatacategory={"category":"Manufacturing","subcategory":"Small appliances"}  (to assign by value, multiple values)
prop_metadatacategory={"id":123}  (to assign by value, directly with id)


files

Binary file content is passed in multipart mode (multipart/form-data). It is possible to indicate a replacement name for the file by passing it as a parameter.
We can to follow through a download by indicating an identification number via the parameter. The appropriate method to follow-up download progress is similar to the one detailed here.

since 11.12 It is possible also to pass an URL as value. To set the name, pass a json value like in this example :

Code Block
prop_image={"url":"http:8080//myimageserver/logos/brandsimplelogo.png","name":"myimage.png"}


Anchor
Create or update mode
Create or update mode
300 Create Or Modify

It is possible to configure an action to operate in "create or update" mode. By default, a POST on the endpoint "create" creates a new object instance and a PUT on the endpoint "modify" modifies a time point designated by its identifier (parameter id).

With "create or update" mode, with all endpoints, we first determine if the object exists: if it exists, it is modified, otherwise it is created.

This mode is activated as soon as a property is designated as key, with the key configuration property. We search for the object instance (or instances) whose key values are equal to those passed as parameters: if it exists, it is modified, otherwise a new instance is created.

It is possible to use a specific query to search for the object instance by the updatequery configuration property.