300 Create Or Modify

Introduction

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

Configuration

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

JSON example

{
  "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:

  {
    "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:

"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:

    "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:

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

    
    

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

    "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": {
      "check": {
        "values": ["ARPA","TEGA","GOBA","NBPC"]
      }
    }

    
    

• format: formating

  • trim: allows deletion of useless white spaces

    • right: delete right white spaces For example:

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

      
      

    • left: delete left white spaces For example:

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

      
      

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

      "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:

    "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:

  "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

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

since 11.12

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:

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

EndPoint: create

since 11.14

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

since 11.12

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

Legacy endpoint:

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

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

• since 11.11

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

• since 11.11

• report: 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).

{
  "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

EndPoint: Apply workflow action

since 11.14

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

since 11.12

PATCH http://host:port/app/api/json/workflow

Legacy endpoint:

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

EndPoint: list of available workflow actions

since 11.14

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

since 11.12

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

Legacy endpoint:

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

{
  "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

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

since 11.12

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

Legacy endpoint:

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

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

Security

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

EndPoint: put locks on objects

since 11.14

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

since 11.12

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

Legacy endpoint:

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

{
    "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

EndPoint: remove locks on objects

since 11.14

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

since 11.12

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

Legacy endpoint:

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

{
    "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

EndPoint: list of available actions

since 11.12

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

Legacy endpoint:

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

{
  "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
  }
}

Security

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

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:

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:

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:

prop_activated=true
prop_activated=false
prop_x=

dates

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

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:

prop_link=10070

multiple children (array)

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

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 :

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

Create or update mode

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.