Appendix1 (Configuration)

Owned by Jules DELEUZE (Unlicensed)
Last updated: Nov 09, 2022 by Joël DRIGO
14 min read

Configure the plugin

Here is the list of configuration properties available for the WXM_RESTAPI plug-in:

  • raisePluginStatusToEngine2022.1 : if true (default), the plugin status impacts the server status

  • tempdir: directory to store temporary files (volatile files)

  • workdir: directory to store temporary files for long working process (2021.5 see important notice)

  • restApiDirPurgeNode: the name of the node (in clustered mode) where to run the restapi SAN directory purge (if the current node name is different thant the value of this parameter, the purge is not done)

  • linksection: configure hateoas section

    • REMOTE (default)

    • LOCAL

    • OUTBOUND

    • FULLOUTBOUND

    • NONE

    • a component URI (pluginname:classname)

  • connectionListener: connection listener URI (pluginname:classname)

  • configHotUpdate: Enables automatic reloading of an endpoint configuration file if it changes on the disk.

    This option is required in cluster mode, if you change the configuration via the API Designer. When saving a configuration, it is modified in the cache of the current node and the file storing the configurations is modified but the other nodes do not update their cache if this option is not enabled.

    Possible values are:

    • true: activates the reloading of the cache when the file is modified

    • false : does not take into account file changes until the plugin is restarted

    • auto: activates the reloading of the cache only if the server is not in production mode

  • configPluginName: the name of of plugin to store service configurations (by default the name of this plugin is WXM_RESTAPI_CONFIG)
    If the plugin doesn’t exist or is not activated, the configuration plugin is the REST API plugin (WXM_RESTAPI)
    See https://crossmedia.atlassian.net/browse/WXM-6082

  • applicationObject: name of object used to store application tokens (by default restapiapp)

  • deployDamServices: if true, automatically deploy DAM services

  • exposeImageServerPath: in the responses to API calls, for a property that indicates the path of a file in a property of type file or image, we expose the path of the file (relative to the SAN), otherwise we expose only the file name

  • defaultETag: define the default ETag (See ETags within the REST API end points )

  • 2021.5 dynETag: disable supports of dynamic ETag

  • damEtag: activate (or deactivate) ETag for DAM Services

  • 2022.6 etagContextProperties: This is the list (a JSON array) of surfer properties that are taken into account to calculate the context of a surfer. The default value is an array with the property used The default value is an array that contains the property used by the security module to manage rights (roles): it is essential to keep it to work with the role configuration application.

  • useTriggerForEtagNotifications: On non cluster plateforme use trigger to handle instance change notifications for dynamic ETag (if false, dynamic ETag will be handled by notification - not available yet - si do not change this value until the feature is available)

  • etagVersionValue: the value for version value (see ETags within the REST API end points | Version ETag )

  • etagMaxAgeControl: allows the client (ie the browser to manage the MaxAge Cache Control)

  • aggTreeCount: a boolean (true by default) to enable the tree count option in the agregates calculation

  • aggAutoGeneration: a json to configurate aggregates autogeneration in non damobjects in DAM services

  • enableMassImportServices: activate mass upload/import services (true by default)

  • massImportItemObjectName: name of object to store tempory items to upload/import (default is massimportitem) 

  • massImportCreateWithJobOwner: if true (default), use job owner to create assets (or simulate). If false, use default job executor user

  • massImportRemoveItemAfterCreate: if true (default) remove item after asset creation while upload/import process

  • massImportSimuWithFaces: if true (default) compute and export faces in simulation

  • massImportJobConfig: json to configure thread pools for executing jobs (see Mass imports/uploads | Configuration (plug in) )

  • massImportSupportedFiles: intended for future use

  • massImportStoreCache 2022.1: if true (default) save mass import simulation and cache (and related data, as valid, haserror, haswarning, and datachanges (for fulltext search on mass import items)

  • massImportAsyncStoreCache: true enable asynchronous saving of the mass import simulation cache

  • massImportEnableDataChanges 2022.1: if true (default), information allowing fulltext search on mass import items is generated

  • massImportBlockingJobChangesQuery 2022.1: boolean, default is true(since 2022.2). If true activate long polling on job changes service

  • massImportBlockingJobChangesQueryTimeout 2022.1: long, timeout for long polling on job changes service

  •  massImportBlockingJobChangesQueryNotifyCondition2022.1: string, the type of the type of event that releases the long polling. Possible values are:

    • always: when the worker has finished, even if the command has failed

    • anydone: (default since 2022.2) when a command has been applied

    • alldone: when all commands have been applied

  • massImportSetChangesCompletionServiceEnabled 2022.1: boolean, default is true(since 2022.2). If it is true, the application of the commands of a job are applied to the items in an asynchronous system (if it is false, they are applied to the items one after the other). The setting of the asynchronous system is done by massImportJobConfig.

  • massImportJobOutstandingVirtual2022.2 : boolean, experimental, let this value to false.

  • massImportJobPurgeConfig2022.2: json to configure the mass import job and items cleaning process (see Mass imports/uploads | massImportPurgeConfig)

  • asyncZipBinaryExpiringTimeout2022.2: an integer (default is 120), the retention time in seconds of the progress of an asynchronous zip upload after it has finished processing.

  • asyncZipBinaryThreadPoolConfig2022.2: json object, configuration of the thread pool for asynchronous zip upload
    This is a JSON object. This is the default configuration:

    { "threadCount":3, "queueSize": 100, "idleTime": 300 "allowCoreThreadTimeOut": true }


    Here is the properties:

    • threadCount: the number of threads. You can use minThreadCount and maxThreadCount if you want to set a different minimum and maximum value.

    • queueSize: the size of the queue

    • idleTime: time (in seconds) before an idle thread is terminated

  • limitedChildren: if true (default), limits the number of children exported in DAM services

  • securedDamServices: if true (default), honors the security of the objectData domain in DAM services

  • securedAppSettingsServices2022.2 : if true (default), honors the security of the objectData domain in Application Settings services

  • canRetrieveCaption: if true (default is false), honors objectData/canRetrieveCaption for children in DAM services

  • checkSecurityCanViewEvenSimuCreateOrUpdate 2021.6 : Starting with version 2021.6 , objectdata/view security is disabled by default on the exposure of asset modification simulations in the context of mass import, to allow the implementation of facets. If the value of this parameter is set to true, then we return to the previous behavior (we can't see a result of a modification or creation simulation if the security refuses it, or crashes because the ID of an instance in creation simulation is 0).

  • damRelativeURLs: if true (default is false), exported URL are relatives (in DAM services responses)

  • authRelativeURLs: if true (default is false), exported URL are relatives (in auth services responses)

  • allowAccessIfActionDoesntExist: if true (false by default) do not check end point security if the corresponding action doesn’t exist

  • lazyDeployDamServices: if true, and not production mode, the configuration of dam services are automatically updated when the structures change

  • sessionAuth(obsolete): if true, allows authentication of invokation with the session surfer (avoid this because of XRSF attacks)

  • sessionAuth11.18 : default is false. If true, allows stateful surfer session surfer (shared with backoffice session)

  • allowSessionAuth 11.18 : default is true. If true, allows api client to work as sessionAuth mode, on demand, while getting a token.

  • sessionAuthReconnectMode 11.18 : default is false. If true, during a sessionAuth authentication, the surfer is reconnected (re-execution of surferservices among others)

  • sessionAuthBODisconnect 11.18 : default is false. If true, in sessionAuth mode, if we connect a new surfer, we force the disconnection of the surfer currently in session

  • sessionFul 2021.4 : default is false. If true, we connect in sessionful (see API Authentication & Connection Modes )

  • WWWAuthenticateFallBack : default is false. In case there is no authentication information in the request, we return a 401 Unauthorized. If this parameter is true, the WWW-Authenticate header is included in the response.

  •  allowJWTCookieAuth: default is true. Allows to request a connection in cookie mode (request parameter cookieauth=true)

  • JWTCookieSameSite: default is Strict. Value of the SameSite attribute of the REST API cookies.

  • JWTCookieSameSiteLocal: no default. Value of the SameSite attribute of the REST API cookies in developpement mode. If no value is indicated, we use JWTCookieSameSite

  • JWTCookieShare 2021.4: default is false. If false attribute Path of API cookies is /api. If true, its /, thus, the cookie is transmitted for all urls including the BO, thus allowing to connect to the whole solution via the Portal. This is not useful in sessionful mode, because the session is shared between BO and API.

  • DXMDomain2021.4: Value of the cookie attribute Domain (necessary for DXM access in the Portal), if you want to indicate a specific value different from the value automatically assigned if DXM is enabled.

  • JWTCookiePathDependsOnRequest: default is false. If true, the value of the Path attribute of the cookie is determined from the request that is doing the signin, otherwise it is determined from the system variables. This parameter is ignore if JWTCookieShare is true.

  • JWTCookieLongLife: Default is true. If true, the lifetime of the JWT cookie is the lifetime of the refresh token, otherwise it is the lifetime of the access token.

  • 2022.6 csrfTokenControl: boolean, default is false, activates CSRF token checks in the API call when cookie is used for authentification

  • 2022.6 csrfTokenControlExcludes: a white list (JSON Array) of IP for which the token control is disabled (event csrfTokenControl is true)

  • 2022.6 csrfTokenControlExcludes_local: the same as csrfTokenControlExcludes, but for local use only (never included in backup)

  • oauth2Enabled: default is true. If true, allows to use the OAuth2 SSO authentication system provided by the API

  • ssoSAMLEnabled: default is true. If true, allows to use the SAML SSO authentication system provided by the engine 

  • ssoOAuth2Enabled: default is false. If true, allows to use the OAuth2 SSO authentication system provided by the engine 

  • tokenHash: A base for the hashing of JWT tokens signature

  • tokenCleaningPeriod: period of the task of cleaning expired tokens

  • tokenLongLifeTime: lifetime of long life JWT tokens (in seconds)

  • tokenShortLifeTime: lifetime of short life JWT tokens (in seconds)

  • tokenMaxAge: (optional) max age of JWT tokens (in seconds)

  • jwtAlgorithm: JWT tokens hash algorithm (HS256, HS384 or HS512)

  • errorSupport: configuration of error support in error message

    This is a JSon. You can configure default message for the client, or keys and parameters so that the customer can generate his own messages. The default value is:

    {"key":"WEDIA_ERROR_SUPPORT","params":["support@wedia-group.com"]}

    • string form

      if the value is a string, then this is the support message that will be presented

    • object form

      the object has two properties:

      • key: the key for the message

        • WEDIA_ERROR_SUPPORT

          A message presenting one value (the email of support service) and the Wedia name

        • EMAIL_ERROR_SUPPORT

          A altenative of WEDIA_ERROR_SUPPORT message without Wedia mention

      • params:

        Parameters for the message. Default messages has only one parameter:

        1. support email address

      • value: (optional) a default static message. If this property is omitted, one is generated with key and params from the REST API Plug-in bundle.

    • array form

      An array of several messages.

  • allowDebugInProduction: boolean. Allows to temporarily allow debug mode, even in production. Be careful to enable this option exceptionally to limit API vulnerabilities to certain attacks.

  • presetPrefix: prefix for preset (for automatic naming) exposed from Image Processing Configuration

  • defaultCharset: default charset for API request parameters and headers

  • defaultContentCharset: default charset for for API request and response body

  • docPortalWithHelpers 2021.5 : default is false. If true, messages are displayed to help solve the errors. As this information is related to the internal functioning of the Wedia solution, it does not generally speak to external parties and is therefore not displayed by default.

  • apiDocSecure: default is true. If false, access to the API documentation is not secured (it is not necessary to authenticate to consult it).

It is not recommended to put false on a server accessible on the web.

See Redoc Swagger API Documentation

  • apiDocRenderer: type of default HTML/CSS renderer for OAS3.0 documentation

  • apiDocLazyRendering 2021.6 : if true, ReDoc's lazy rendering mode is enabled (supposed to improve its display speed)

  • apiDocCache: enable or not OAS3.0 file cache. When the cached file is generated, the documentation is always read from the file, so no configuration changes can be seen in the documentation.

    • ALWAYS: always cached

    • NEVER! never cached

    • ONLYPROD: cached only if production mode is activated

  • apiDocCacheClearOnRestart: boolean, true to delete the OAS3.0 cached files when the plug-in restarts

  • apiDocCacheGenOnRestart: boolean, default is true. If true, OAS files describing the API documentation are generated when the plugin starts. If false, OAS files describing the API documentation are generated when requested (if caching is enabled, when first requested). This can penalize the request, but will queue up other simultaneous requesters, or even reject them (in error) if the timeout is exceeded. It is therefore recommended to leave this value at true, except on development servers, when this documentation is not used, in order to preserve resources (disk space, memory, cpu).

  • apiDocInternalCache: boolean, default is true. If true, activates the internal cache during generation. Consumes more memory, but saves generation time. 

  • apiDocOasStream: 2022.1 a json object to configure the download of an OAS3 file
    The default configuration provided should be fine in general. If you have problems with file loading times (especially large files), please contact @Joël DRIGO before changing this configuration. See more details here.

  • apiDocInfoExcluded: 2022.1 a json array to configure the list of information to be excluded from the REST API documentation. See more details here.

  • apiDocPortal: 2022.1 a json object to configure the REST API documentation display (the rendering portal, not the user documentation portal). See more details here.

    • alwaysGenerateCacheForTagGroups: 2022.1 a boolean, default is false. If true, the tag group cache is generated even version 1 of the documentation display is selected (these files are not used by the documentation portal version 1 but could be loaded (or displayed) directly via the dedicated URLs if wanted)

  • languageObject: default is restapilang. The object (structure) used to control the languages (by example lang). The structure of the object must be the same as the object lang.  If the value of this parameter is empty or corresponds to a non-existent object, the language control is disabled (a user who logs in with an unmanaged language will have the messages in the default language).

  • disableNotAcceptableLanguageException: default is false. if true, uses the first found locale instead of throwing a 406 Not Acceptable when no valid locale is found in a query (an invalid locale is a locale that is not defined in the language object, see parameter languageObject). If false, throws an error to the requester.

  • notAcceptableLanguageExceptionLocale: Locale by default if request locale is not acceptable (see parameters languageObject and disableNotAcceptableLanguageException). If no value set, use default indexation language.

  • checkResetPassword: default is true. If true, activates the test of the changepass property of the user at the connection. 

  • binaryUpdateAcceptedPaths: defines the paths accessible in the SAN for the assignment of files by path, to a field of type binary or image, during a creation or a modification. It is a JSON array of paths (relative to the SAN). By default, the file and image folders are allowed as file sources.

Be careful not to give access to sensitive files, as this would allow access to these files from outside, by creating/modifying assets.

  • binaryUpdateAcceptedURLS: defines the HTTP URLs allowed as file source when assigning files by URL, to a binary or image field, when creating or modifying. It is a JSON array of URLs (strings). By default, no URL is allowed.
    Example (for an import from Unspash) :

    [ "https://unsplash.com/", "https://images.unsplash.com/" ]

  • profilQuery: a query (JSonQuery) to filter the users manageable by the profile service

  • profilUpdateMeQuery: a query (SQL) to select the users who can modify themselves (if no query, all users can modify themselves, as long as the security configuration allows it)

  • profilDefaultRoleId: the identifier of the default role assigned to a user created via the profile service

  • ignoreQuery:  if true, indicates that query errors due to non-existent properties are ignored (in this case, the answer is just empty, as if no instance matched the query). If false, the service returns a query error

  • defaultI18Nquery: this is the default value of the i18n/query property in the configuration of a DAM or DATA service. This property determines whether a query is automatically localized according to the API request locale

  • allI18Nquery: this parameter determines how, in a request, a localized field is processed if automatic localization is disabled in an API request: if its value is true, then a request is made on all locales of the field, otherwise a request is made on the default field only. In other words, if the value is true, the preparedwhere built from a JSonQuery works the same way as the fulltext search.

  • defaultMassImportSimulationMetadataVersion (temporary): determines the version of the JSon format used to expose the simulation results. Exists to connect an older Portal to a newer version of the API.

  • defaultFacesVersion (temporary): determines the version of the JSon format used to expose facet evaluation results. Exists to connect an older Portal to a newer version of the API.

  • aggGateDebug: activates the timing of the aggregate services

  • ignoreDXM: if true, the creation of API cookies does not take into account the fact that DXM is activated

  • ignoreImagingFactoryStateInStatus: by default, the API takes into account the availability of imaging services to determine its state (which impacts the overall state of the platform). Thus, if the imaging services are not available, the API is considered to be in a degraded state and not available. If the value of this parameter is set, the state of the imaging services is ignored.

  • JSPBaseWhere: allows to make base where API by JSP (obsolete/deprecated, therefore disabled by default : prefer the PrepareWhereService, or the Business Services of the API).

  • applyDependencyBaseWheres: boolean, default to false: if true, the base where are applied automatically on metadata children reporting (in dam/data list/view service responses)

  • dependencyBaseWheresMapping: string, default is base_list: the name of the context used by default, if no PreparedWhereService is found for the default dependency context name (list_children). See details in Bases

  • applyAggFieldBaseWheres: boolean, default to false: if true, the base where are applied automatically on aggregates reporting (in dam/data list/view service responses)

  • aggFieldBaseWheresMapping: string, default is base_list: the name of the context used by default, if no PreparedWhereService is found for the default dependency context name (list_aggs). See details in Bases

  • applyAggFieldQueryOnChild: boolean, default is false ; if true, if applyAggFieldBaseWheres is set to true, apply base where also on field of type child (as by default, the base where is only applied for “childmulti”)

  • checkBSDates: boolean, default is false. If true, enable again the disabled by default test of dates when checking business service extensions plugins jar.

Variables in parameter values

Directory type parameters (ie workdir and tempdir) allow the use of variables. These variables are replaced in the parameter value by the corresponding value, if determined, or an empty string otherwise.

A variable is defined by the sequence ${varname} where varname is :

  • the name of a system property (for example, ${java.io.tmpdir} for the system propertyjava.io.tmpdir)
    The list a available variables can be found in java.lang.System getProperties() method javadoc (see The Java™ Tutorials / System properties for more details). A property can be also set in command line with -Dproperty=value option (see https://docs.oracle.com/en/java/javase/13/docs/specs/man/java.html , section Standard Options for Java).

  • 2021.5 the name of a wedia property among (for example ${app.site.name} for the site name)

    • app.site.name

    • app.company.name

    • app.node.name (no value if not clustered)

    • app.env.type

    • app.cluster.name

    • app.server.name

    • app.var. followed with the name of an application variable

  • 2021.5 a common separated name list of the previous names, possibly finalized by a constant, between exclamation marks. In this case, the value of the first variable that has a value will be used.
    By examples :

    • ${app.site.name,app.node.name}
      The value of app.site.name if determined, otherwise the value of app.node.name.

    • ${app.site.name,app.node.name,!temp!}
      The value of app.site.name if determined, otherwise the value of app.node.name, otherwise the value temp.

View the current plugin configuration

2021.6

The Setup section of the API Designer allows you to see the configuration in use, with the actual values (default, override, evaluated, etc). The URL of this section is (here on club-wed for example) :

https://club-wed.wedia-group.com/_plugins/WXM_RESTAPI/page/admin/pluginconfig/admin.jspz

End point configurations

End point configurations are stored in the configuration folder of the plug-in (/config) in files in files whose name begins with an underscore and the suffix is .txt. There can also be folders whose name starts with an underscore.

In the /config directory, you can find other files released with the plug-in. These are necessary for the execution of the plugin and must not be modified or moved.

These end point configuration files could be put in an other plug-in to make easier the deployment of plug-in WXM_RESTAPI (to avoid to lose the end point configurations that are not comming with the WXM_RESTAPI plug-in release).

The name of this plug-in is by default WXM_RESTAPI_CONFIG (the name of the API plugin-in followed by _CONFIG). This plug-in is detected automatically if it is activated. The name of this plug-in can be changed (see property configPluginName).

To create a separate configuration plugin (when the configuration is still in WXM_RESTAPI):

  1. create the plugin as usual (with a minimal config.xml)

  2. move the configuration from WXM_RESTAPI

  • files of WXM_RESTAPI/config to the config folder of this plugin
    configuration files are those that start with underscore and txt type

  • move also the resource configuration directories (those that start with underscore and end with _RSC)

caution: don’t move any files or directories from "WXM_RESTAPI/config/default" folder), including this directory

When starting or restarting WXM_RESTAPI, the separate configuration plugin must be activated: you can’t check what configuration plugin is used in the API administration page, in the Plugin Status section.

Necessary structures

  • restapiapp: object to store application tokens (the name of the object can be modified in plug-in configuration). The structure may not exist, but it should not be changed in any way

  • restapitk: object to handle jwt tokens. The structure must exist and its definition must not be changed

Securing the administration

The plugin comes with secure administration pages for the roles:

  • Administrators

  • Developer

  • ApiOperators

  • TestOperators

  • ApiWatchers,

  • AuthOperators,

  • AuthWatchers,

  • Watchers

since 11.17 In administration menu, feature icons are filtered by roles:

role

available features

role

available features

Administrators

all

Developer

all

ApiOperators

  • Application managing

  • OAUTH2 set-up

  • Documentation

  • JWT Token managing

  • Plugin status

  • Business services

TestOperators

  • Documentation

  • Plugin status

  • Business services


Configure Postman against Cross-origin resource sharing (CORS) restrictions

since 11.13

Fall 2018 With the desktop version of Postman, this configuration is no more needed.

First solution

Add a CORS filter rule for Postman origin with the following value for authorized origin :
chrome-extension://fhbjgbiflinjbdggehcddcbncdddomop

Second solution

Override Origin header in Postman, with the URL of your domain.