Versions Compared

Old Version 29

changes.mady.by.user Joël DRIGO

Saved on

compared with

New Version 30

changes.mady.by.user Joël DRIGO

Saved on

Key

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

Overview

The purpose of the plugin is to allow to set up a specific configuration for a Wedia portal application, by overriding a basic configuration provided by the product.

...

  • _portal

  • _portal@config

  • _portal@config@picker

The path _portal@$config@picker designates a configuration defined in 3 folders whose relative paths are successively :

...

GET /api/portalconfig/config (operation ID: configGet)

GET /api/portalconfig/config/merge (operation ID: configMerge)

The difference between the two endpoints is that the first one takes no parameters other than the mapping id (and debug). It is intended to retrieve the desired configuration for the requesting surfer (or no surfer). The second one is more for the configuration UX to get different views of the configuration depending on the parameters. The first one is not secured while the second one is.

...

GET /api/portalconfig/config/explain (operation ID: configExplain)

parameters

  • mappingID: string (mandatory), the mapping for which we want the configuration

  • wip: boolean (optional, false by default), activate the “wip” mode (if false, wip/inherit files are ignored, if true, wip/inherit files are taken into account

  • pathFilter, string/nodePath (optional, none by default), a pathfilter to select nodes (See Filtering)

  • pathFilterMode, string/enum (optional, FILTER by default), the filter mode (See Filtering)

  • nodesWithPath, boolean (optional, false by default), (See Filtering)

  • surfer, instance reference (optional, none by default), a substitute user/surfer to get the configuration that this surfer would have if he called the service. (See Instance reference parameter)

  • processorValues, json/map (optional, none by default), a processor/value association map to obtain the corresponding configuration

  • options JSON (optional)

    • xjson: boolean (options, false by default), true to get the configuration as an xjson

  • verbosity JSON, int or string/enum (optional), determines what information will or will not be exposed
    We can configure the verbosity

    • either by a numerical verbosity level (from 0 to 15)

    • or by one of the following words:

      • max

      • min

      • default

    • or by a json which lists the different properties and their values (none is mandatory, all have a default value)

    • or by a combination of both: in the json, the verbosity property is the level, the other properties allowing to select values different from those of the level.
      For example:

      Code Block
      languagejson
      {
   verbosity: default,
   includesVerbosity: true
}

    • if not specified, the verbosity is

      Code Block
      languagejson
      {
    "includesVerbosity": false,
	"includesLocation": true,
	"includesLayer": true,
	"includesOverrides": true,
	"locationVerbose": true,
	"locationRecursive": true,
	"pathVerbosity": true, 
  	"decomposePaths": false,
    "decomposePathsVerbose": true,
  	"includeNodePath": true,
	"includeJsonPath": true,
	"includeXJsonPath": true,
	"nameVerbosity": true,
	"includesIgnored": true,
	"groupsIgnoredInRoot": true,
	"ignoredLocationVerbose": true,
	"includesErrors": true,
	"groupsErrorsInRoot": true,
	"errorVerbose": true,
	"exceptionVerbose": true,
	"exceptionDepth": -1,
	"stackTraceVerbosity": 2
}

    • here is the default json for the verbosity (value default or 3)

      Code Block
      languagejson
      { 
  "includesVerbosity": false,
  "includesLocation": true,
  "includesLayer": true,
  "includesOverrides": true,
  "locationVerbose": false,
  "locationRecursive": false,
  "pathVerbosity": true,
  "decomposePaths": false,
  "decomposePathsVerbose": false,
  "includeNodePath": false,
  "includeJsonPath": false,
  "includeXJsonPath": false,
  "nameVerbosity": false,
  "simpleName": true,
  "includesIgnored": true,
  "groupsIgnoredInRoot": false,
  "ignoredLocationVerbose": false,
  "includesErrors": true,
  "groupsErrorsInRoot": false,
  "errorVerbose": false,
  "exceptionVerbose": false,
  "exceptionDepth": 0,
  "stackTraceVerbosity": 0
}

      The meaning of the properties

      • includesVerbosity, boolean (optional, default is false): If true, include the verbosity configuration in the response

      • includesLocation, boolean (optional, default is true): if true, locations are included in the response

      • includesLayer, boolean (optional, default is true): if true, layer (location root folder) are included in the response

      • includesOverrides, boolean (optional, default is true): if true, overridden elements are included in the response

      • locationVerbose, boolean (optional, default is true): if true, the locations are exposed with a maximum of information

      • locationRecursive, boolean (optional, default is true): if true, the locations are exposed with their parent, recursively

      • pathVerbosity, boolean (optional, default is true): if true, the paths of the locations are exported with a maximum of verbosity

      • decomposePaths, boolean (optional, default is false): if true,the path decomposition of the locations is exported (how these paths were built, in particular which postprocessors were used and their value)

      • decomposePathsVerbose, boolean (optional, default is true): if true, the path decomposition of the locations is in maximum verbosity

      • includeNodePath, boolean (optional, default is true): if true, the nodepaths of each element are exported

      • includeJsonPath, boolean (optional, default is true): if true, the JSONpaths of each element are exported

      • includeXJsonPath: boolean (optional, default is true): if true, the XJSONpaths of each element are exported

      • nameVerbosity, boolean (optional, default is false): if true, the names are exported in maximum verbosity (in particular, we get the details of the type of name: if it is a wip, an inherit, an array, etc)

      • simpleName, boolean (optional, default is true): if true, the name doesn’t include decorations( wip, inherit, array…).

      • includesIgnored, boolean (optional, default is true): if true, files found but ignored are exported, with the reason for ignoring them

      • groupsIgnoredInRoot, boolean (optional, default is true): if true, the ignored files are grouped at the root, if false, they are exported at the level where they were detected

      • ignoredLocationVerbose, boolean (optional, default is true): if true, ignored files are exported with maximum verbosity

      • includesErrors, boolean (optional, default is true): if true, the files or folders whose reading triggered an error are exported

      • groupsErrorsInRoot, boolean (optional, default is true): if true, the files in error are grouped at the root, if false, they are exported at the level where they were detected

      • errorVerbose, boolean (optional, default is true): if true, files with errors are exported with maximum verbosity

      • exceptionVerbose, boolean (optional, default is true): if true, the exceptions encountered are exported with a maximum of verbosity

      • exceptionDepth, int (optional, default is 0): defines the depth of the causes of the exceptions (0 corresponds to no cause)

      • stackTraceVerbosity, int (optional, default is 0): defines the verbosity level of the stack traces

...

GET /api/portalconfig/config/test also works, with the parameter explain (operation ID: configTest)

parameters

The parameters are a combination of the parameters found in the services config/merge, config/explain and xjson/to and xjson/from.

...

GET /api/portalconfig/postprocessors/list (operation ID: postProcessorsList)

parameters

  • mappingID: string (optional), designates a particular mapping (filter)

  • postProcessor: multiple strings or comma-separated (optional), designates a particular post processor, or a list of post processors (filter)
    (you can have several times the parameter, or list several postProcessor in the same parameter, separated by commas)

  • options: a JSON object (optional), defines options

    • withMappings: (default false) allows to have the list of mappings that use the postprocessor

    • withValues: (default false) allows to have the list of mappings that use the postprocessor

...

GET /api/portalconfig/postprocessors/value (operation ID: postProcessorsValue)

parameters

  • mappingID: string (mandatory) the mapping ID

  • postProcessor multiple strings or comma-separated (optional), designates a particular post processor, or a list of post processors (filter)
    (you can have several times the parameter, or list several postProcessor in the same parameter, separated by commas)

  • surfer:string, as UUID, UID, ID… (optional), a particular user for whom we want the resolution

  • options: a JSON object (optional), defines options

    • withMappings (false)

    • withValues (false)

...

GET /api/portalconfig/path/all (operation ID: pathAll)

parameters

  • mappingID string (mandatory), the mapping ID

  • options a JSON object (optional), defines options

    • explain boolean (optional)

      • true: gives the details of each part of the paths, with the source of the postprocessors and values that determined them

      • false (or absent): no details (default behavior)

    • withFileInfo (optional) boolean

    • sizeOfDirectory boolean (optional, default is true) if true, the size of a folder is calculated by adding the size of all the files in it. If false, it is the size of the file-folder.Files and directories

  • filter JSON object (optional)
    This filter allows you to select files according to criteria. It is defined as a JSON with the following properties:

    • withBase boolean (optional)

      • if true, base config is included in response

      • if false, base config is not included in response

      • if absent or null, has no effect

    • exists boolean (optional)

      • if true, configuration files that do not exist aren’t included in the response

      • if false, configuration files that exist aren’t included in the response

      • if absent or null, has no effect

    • postProcessors (optional) string, or array of strings (A list of post processor names)
      Only the paths that have been determined from the listed processors are included in the response.

    • postProcessorValues (optional) JSON object/map
      Allows to get only the paths that contain certain values of post processors.

      • keys are post processors names

      • values (string, or array) are the list of values from the post processors for which a path will be included in the response

...

GET /api/portalconfig/path/resolve (operation ID: pathResolve)

parameters

  • mappingID, string (mandatory): the mapping ID

  • options, JSON (optional)

    • explain boolean (optional, default is false) if true, expose details on each paths

    • withFileInfo boolean (optional, default is false) if true, informations on files are included (size and length)

    • sizeOfDirectory boolean (optional, default is true) if true, the size of a folder is calculated by adding the size of all the files in it. If false, it is the size of the file-folder.Files and directories

  • filter, JSON (optional)
    This filter allows you to select files according to criteria. It is defined as a JSON with the following properties:

    • withBase, boolean (optional, default is false)

      • if true, base config is included in response

      • if false, base config is not included in response

      • if absent or null, has no effect

    • exists boolean (optional, default is false)

      • if true, configuration files that do not exist aren’t included in the response

      • if false, configuration files that exist aren’t included in the response

      • if absent or null, has no effect

    • postProcessors (optional) string, or array of strings (A list of post processor names)
      Only the paths that have been determined from the listed processors are included in the response.

    • postProcessorValues (optional), JSON object
      Allows to get only the paths that contain certain values of post processors.

      • keys are post processors names

      • values (string, or array) are the list of values from the post processors for which a path will be included in the response

...

GET /api/portalconfig/mappings (operation ID: mappingsGet)

The configuration is stored in folders and files that will be merged to obtain a final configuration. A base is provided by the product and it is possible to create new files that will successively redefine this base.

...

GET /api/portalconfig/containers (operation ID: containersList)

parameters

  • pathMatcher (optional)
    A filter to select containers. See pathMatcher.

  • options, JSON (optional)

    • withRights, boolean, (optional, default is true)
      If true, we expose the writing rights in this container

    • onlyIfExists, boolean, (optional, default is false)
      If true, we expose that the containers that physically exist

    • withMappings, boolean, (optional, default is false)
      If true, we expose the list of mappings that include the layer stored in this container

    • withInfo, boolean (optional, default is false)
      If true, we expose some information about the container:

      • exists, a boolean: if true, the container physically exists

      • var, a boolean: if true, the container name has been calculated by postprocessors

      • restarting, a boolean: if true, the container name is relative (it has been cut by a $ during its resolution)

    • withFileinfo, boolean (optional, default is false)
      If true, we expose the last modification date and the size of the container (if it exists)

    • sizeOfDirectory, boolean (optional, default is false)
      If true, the size of the folder is the total size of all the files it contains (otherwise, this information is what the java.nio.file.Files.size() method returns)

    • outOfMappings, boolean (option, default is false)
      if true, also retrieves the containers that are not used by a mapping (so all folders created in the configuration storage folder)

...

GET/POST /api/portalconfig/diff (operation ID: jsonDiff)

Parameters

  • leftJson, JSON descriptor (mandatory), a JSON to compare to rightJson

  • rightJson, JSON descriptor (mandatory), a JSON to compare to leftJson

  • processorValues, JSON/map (optional), a default set of processor values

  • options, JSON (optional),

...

GET /api/portalconfig/fs/dir (operation ID: dir)

Parameters

  • path string (mandatory): the path of the desired container (a configuration path)
    for exemple, _portal@club-wed@role-4

  • subpath, string (optional): a path relative to the container
    for example, boardsview

  • verbosity, JSON (optional):

    • includesFileInfos, boolean (optional, default is true): exports dates and file sizes

    • includesFileCounters, boolean (optional, default is true): exports the number of files and folders

  • options, JSON (optional):

    • depth: int (optional, default is -1=infinite depth)

    • pathMatcher: (optional) defines a filter on paths and file names. The filter is applied to the relative path and name: if it matches one of the two, then the file or folder is exported, and those that do not match one of the two are not. See pathMatcher.

...

GET /api/portalconfig/fs/dir (operation ID: dirMerged)

Parameters

  • path: string, multiple (mandatory, if mappingID is not present): a list of paths (base or configuration containers). If mappingID is also present, it’s used as an inclusive filter. If mappingID is not present, it's the list of paths to get.

  • mappingID: string (mandatory, if path is not present), the mapping for which we want the configuration

  • wip: boolean (optional, false by default), activate the “wip” mode (if false, wip/inherit files are ignored, if true, wip/inherit files are taken into account

  • surfer, instance reference (optional, none by default), a substitute user/surfer to get the configuration that this surfer would have if he called the service. (See Instance reference parameter)

  • processorValues, JSON/map (optional, none by default), a processor/value association map to obtain the corresponding configuration
    For example,

    Code Block
    languagejson
    {
   "surferRole": "role-31"
}

  • maxLayers, int (optional, default is -1=infinite): only if mappingID present and resolve true, limits the numbers of paths

  • resolve, boolean (optional, default is true): only if mappingID present, if true, resolve the configuration layers against the context (so get only the involved paths), if false, get all possible paths

  • verbosity, JSON (optional):

    • includesErrors, boolean (optional, default is true): export the files or directories that caused read errors

    • includesIgnored, boolean (optional, default is true): export the files or directories ignored during the resolution of a mapping

    • includesNotFound, boolean (optional, default is true): export the configuration container folders that do not exist

    • includesFileInfos, boolean (optional, default is true): exports dates and file sizes

    • includesFileContent, boolean (optional, default is true): exports the content of files

  • options, JSON (optional):

    • depth: int (optional, default is -1=infinite depth)

    • pathMatcher: (optional) defines a filter on paths and file names. The filter is applied to the relative path and name: if it matches one of the two, then the file or folder is exported, and those that do not match one of the two are not. See pathMatcher.

...

Comming soon: locks per layer, by the container (or layer) parameter

lock

POST /fs/lock(operation ID: lockPut)

Put an exclusive access lock (if not already owned).

...

Http status

200

The lock has been obtained or extended

403

Unable to obtain a lock (already owned, or error)

503

Locks are unavailable

500

Other errors

unlock

DELETE /fs/lock(operation ID: lockDelete)

Delete the owned lock.

Response

Http status

200

Lock deleted

202

No lock

403

Lock not owned

500

Other errors

get lock

GET /fs/lock(operation ID: lockGet)

Test if lock is owned (and extend it)

...

  • name: string, mandatory (if missing, command is ignored, if not corresponding to an executable service, command is ignored), name of command. See the documentation of each service to have the associated command name (services that do not have one are not executable by this service).
    It is also possible to use the API operation ID.

  • parameters: mandatory, parameters for the command
    This can be

    • an object for which each property corresponds to a parameter (value of property is parameter name), and the associated value describes the values for that parameter

    • an array of objects with the following properties (values are grouped by identical name)

      • name: name of parameter

      • values: values of parameter

      • value: single value of parameter

...

Service to submit a command set

POST /fs/command(operation ID: commandSubmit)

parameters

commands, mandatory, description of commands (see above)

...

Service to get state of a command set

GET /fs/command(operation ID: commandStatus)

parameters

id, mandatory, command id

...

To patch a configuration layer with an XJSON, use

  • service: POST fs/config(operation ID: configWrite)

  • parameters

    • content (mandatory): the XJSON

    • container (mandatory): the layer container name

    • path (optional): an xjsonpath target subpath

...

To patch a configuration layer with delete files, use

  • service: DELETE fs/config (operation ID: configDelete)

  • parameters

    • content: none

    • container (mandatory): the layer container name

    • path (at least one): one or several xjsonpath

...

To patch a configuration layer with an XJSON, use

  • service: POST fs/config(operation ID: configWrite)

  • parameters

    • content (mandatory): the XJSON

    • container (mandatory): the layer container name

    • path (optional): an xjsonpath target subpath

    • options

      • merge: false

...

To patch a configuration layer with an XJSON, to delete configuration properties of the above layers or remove configuration properties from this layer, use

  • service: DELETE fs/config (operation ID: configDelete)

  • parameters

    • content (mandatory): the XJSON
      In that mode, the XJSON is not lenient, because arrays are used to specify the mode. In this array, specify the desired options among

      • DELETE (or D, or DEL, insentive case)
        to write a file with delete suffix

      • REMOVE (or R, or REM, insentive case)
        to remove the property

        for example:

        Code Block
        {
   a: [delete],
   b: [remove],
   c: [delete, remove]
}

        • the file a.delete will be created

        • all the files and directories for the property b will be removed

        • all the files and directories for the property c will be removed, then the file c.delete will be created

    • container (mandatory): the layer container name

    • path (optional): an xjsonpath target subpath

Service to write configuration

POST fs/config (operation ID: configWrite)

Command name: fs/config/write

...

Delete (erase or write delete files)

DELETE fs/configCommand (operation ID: configDelete)

Command name: fs/config/delete

  • container, (see Basic file operatirons/Parameters for details), mandatory
    denotes the configuration container

  • path, (see Basic file operatirons/Parameters for details), optional, can be single or multiple, depending on the presence of content
    specifies the relative xjsonpath (to the configuration container) where to write

  • content, string or file(multipart/formdata), optional
    The XJSON to write. If this parameter is not specified, multiple paths can be specified. If this parameter is specified, only one path or none can be specified (in this case, we write directly to the container).
    This XJSON is not lenient. Arrays are used to specify the operation (see details in the paragraph Delete configuration (write delete files and/or remove files) with a XJSON):

    • DELETE

    • REMOVE

  • wip, boolean, optional(default is false)⛔
    True to write to wip data

  • options, JSON with the following properties

    • deleteNotEmpty, boolean (optional, true by default)
      if false, REMOVE option is not applyed on not empty directories

    • mkContainers, boolean (optional, false by default)

...

GET/HEAD /api/portalconfig/fs/file (operation ID: fileGet)

This service allows you to read a file (its content). This service does not allow to retrieve the content of a folder (use the dir service for that).

...

DELETE /api/portalconfig/fs/file (operation ID: fileDelete)

This service allows you to delete files or directories.

...

Command name: fs/container/write (operation ID: containerWrite)

This service allows you to create one or several container (root configuration directories)

...

DELETE /api/portalconfig/fs/container (operation ID: containerDelete)

Command name: fs/container/delete

...

  • container: the name of the container

  • state: the state among:

    • INVALID: the container name contains invalid characters

    • BASE: the container name is identified as the base name (not deletable)

    • VARIABLE: the container name is identified as being dependent on variables (postprocessors)

    • NOT_FOUND: a container of this name hasn’t been found

    • DELETED: the container has been deleted

    • NOT_EMPTY: the container can’t be deleted because it’s not empty

    • ERROR: There was an error when deleting the container

Rename container

TODO

Convert JSON to XJSON

GET/POST /api/portalconfig/xjson/to (operation ID: xjsonTo)

Parameters

  • json: JSON or JSON file (multipart/form-data)

...

GET/POST /api/portalconfig/xjson/from (operation ID: xjsonFrom)

Parameters

  • json: JSON or JSON file (multipart/form-data)

  • lenient: boolean (optional, false by default). If true, non xjson structures (like arrays) do not cause errors.

...

POST /api/portalconfig/cache/flush (operation ID: cacheFlush)

Regenerate cache from current configuration directories state

...

GET /api/portalconfig/cache (operation ID: cacheStatus)

Get cache status

Info

GET /api/portalconfig/info (operation ID: info)

Get some information about the plugin.

...

Get the list of services and associated security actions by calling the GET /api/portalconfig/services service (only in tomcat administrator or developer role)

Links

The “Urls” page of the plugin gives access to the following links:

  • See the main log of the plugin

  • See the log concerning the access to the cache

  • See the security log

  • Debug Toolkit

  • Cache debugging

  • API Documentation (ReDoc)

  • Services
    The list of services (the available information is obtained from the service inventory).

JSP

Include configuration in your own JSP

You can include the configuration corresponding to a mapping using the URL /_plugins/wxm_config_resolver/page/config.jspz?mappingID=<mappingID>

...

Debug Toolkit

You can test the different conversion and detection methods via the JSP for testing these methods, at URL /_plugins/wxm_config_resolver/page/toolkit.jspz (login by backoffice user).

...

Note

It is a version 0 which does not manage progressive loading : all the tree structure is loaded at once

Cache debugging

This page displays the currently cached files. It allows you to

  • know the state of the cache (up to date, being generated, etc)

  • know the different variations (depending on the mappings, post processors, etc)

  • consult each cached file

  • refresh the cache

In a cluster, this is the cache for the current node.

List of services

** Procédure d’installation version test

...