Skip to main content

SOAP/REST Service Request Context

Info

The article describes objects that are key elements of requests in communication with the database via SOAP and REST services. The Context object is used in all services and is the basis for analyzing user permissions and the form of the response. The widespread use in the HgDB solution resulted in the need to create a kind of communication standard between integrated systems. This is how the Context and Case Request Transportable Objects Open API project was created, which was used, among others, for communication between Mercury DB (HgDB) 3.0 and Iron - POI Excel Server.

Definition of the Context object​

Layers in which usedLogic, Business
TypeBusiness object
className/typeContext
Java implementationpro.ibpm.mercury.context.Context
DTO implementationpro.ibpm.mercury.context.Context
XML definitionhgdb-context-3.0.xsd

Context object. A very important element appearing in the call to each SOAP/REST service (as the arg0 argument in API 2.0, in API 3.0 as the context argument). Its task is not only to inform about the source/origin of the service request call, its fields are of a control nature and affect the way the request and response are processed.

List and meaning of individual fields/parameters
ParametersDescriptionTypeRequiredAllowed values ​​
appNameApplication nameStringYes
appVersionApplication versionStringYes
userNameUser nameStringYes
commentUser comment (why they are performing a given action)StringYes
maxResultsThe maximum number of results obtained as a result of searching for data. For complex queries, this is also the maximum number of results returned in subqueries.IntegerYesAn integer from 1 to 100000
queryTimeoutDefinition of a possible operation timeout - number of millisecondsIntegerYesInteger greater than 0
localeDefinition of the user's language version. Abbreviation of the structure <language_code>_<territory_code> where: language_code is the ISO 639-1 language code, territory_code is the UPS CodeStringNoExample: pl_PL
timeZoneDefinition of the user's time zoneStringNoExample: Europe/Belgrade
userFullNameAdditional information about the user - full nameStringNo
eager4omdBuilderInformation whether only the required data (minimum) should be sent - value true, or all possible data, value falseStringYestrue or false
trustedDataCan the data set be trusted? Control flag when user data is to be updated in the Mercury system. As you can see in the context, the user name and full name are sent - when we set the flag to true Mercury will update the full user name to the value given in the context.BooleanYestrue or false
ignoredCustomFieldsUsed in business services for saving. List of fields whose values ​​are to be ignored when comparing object versions. Control flag used in business services to identify the case type.Set<String>NoAllowed values ​​are described in the article on saving a case. Case save.
currentRoleCurrent user role. Data needed to register the team in which the user is making changes. The parameter value is required due to Permissions mechanism.StringYes
userRolesList of user roles (names). Based on this list, permissions to perform the operation/invoked service are verified (see the article on Permissions mechanism).Set<String>Yes
sourceOfRequestAcronym of the application/source of the action request. Required when the service is to identify a new type (TypeCase), group object (GroupCase), or store (Store). When creating such an object, appropriate information related to its origin is added.StringYes
rootTagNameUsed in business services. The name of the root tag of the XML document in which the case will be placed in the form of XML. If it is not set in the response, we will receive XML with the root tag "variable"StringNoObsolete parameter, currently unnecessary.
formatsUsed in business services. Format map, whose keys are the names of Mercury system parameters:
1. for specifying the number format: the key is the value number.format.number
2. for specifying the payment format, the key is number.format.currency
3. for specifying the date format used during communication, the key is the value date.format.long and date.format.short		Map<String, String> - see the following examples of XML definitions.No
ignoreAlternateFieldsInformation whether alternative fields should be ignored when building a search query - if we set the value false, the search will only take place on the basic fields. Default value: trueBooleanNotrue or false
decodeResultUsed in business services. Information whether the result, case parameters, should have decoded parameter values ​​(presentation values). The values ​​sent correspond to the DecodeMethod object, described in this documentation. Default value: DATE_AND_LOBStringNoOne of the values: NOTHING, DATE_ONLY, LOB_ONLY, DATE_AND_LOB, ALL_WITHOUT_LOB, ALL
decodeRequestUsed in business services. Information whether the values ​​of the parameters appearing in the request are presentation values. The values ​​sent correspond to the DecodeMethod object, described in this documentation. Possible values ​​to use are defined depending on the methods and services, which will be indicated during their description. Default value: DATE_AND_LOBStringNoOne of the values: NOTHING, DATE_ONLY, LOB_ONLY, DATE_AND_LOB, ALL_WITHOUT_LOB, ALL
ignoreCaseHeaderInResponseUsed in business services. Information whether the returned data in the business layer should contain the case header - used e.g. when downloading dictionaries stored as cases. Default value: falseBooleanNotrue or false
cacheUsageInformation about how caches are used when performing search queries. Default value is TO_USEStringNoOne of the values: TO_USE, NONE, REFRESH, TO_REMOVE
httpResponseCacheUsageUsed in business services. Additional cache space allows storing entire service results in its space, without the need to perform a query or transform case objects to XML, JSON. Default value: NONEStringNoOne of the values: TO_USE, NONE, REFRESH, TO_REMOVE
defaultLuceneSortClauseOptional parameter. Default sort clause used in processing the result of a query to the Lucene index. By default, it takes the value mrc_createDate (in the 3.0 model, the date the case was created). Example: code DESCStringNofield value format: <index_field_name> `[ASC
viewDefinitionUsed in business services. List of fields (names such as the names of fields in the Lucene index) that will be returned as a result of a query to the Index. Helpful for building the results table. Field values ​​must be stored in the Lucene index.StringNoAn example of use can be found in the article Searching for cases.
requestPropertiesUsed in business services. Additional parameters related to processing the request sent to the service.Map<String, String>NoExample usage can be found, among others, in the article on case saving Case saving.

Basic example of using context​

To construct an example object of type Context let's use the following assumptions:

  • The application that calls the service presents itself as BPM Process Vacation in version 0.0.1.
  • The external system has its own authentication mechanisms, based on which it knows the user's name and what roles they have (it knows which groups the user is assigned to). We therefore assume that this service is called by the external system on behalf of the authenticated user named ttesteusz with his full name Tadeusz Testeusz, who has the following roles: Director, CKBPM-Team, mrc-admin, mrc-user.
  • The service call was forced during the action, during which the user acts as Director
  • Assuming that the called Mercury DB system service is to perform the modification task, a comment to the task being performed is required, e.g. Change of mother's maiden name, at the client's request
  • The external system has identified the following language parameters of the user ttesteusz: pl_PL
  • The external system has identified the following parameters regarding the time zone of the user ttesteusz: Europe/Warsaw
  • Since the external system has identified all the user's data, it can pass information to the Mercury DB system that the data can be considered trusted and based on it, its data can be updated. We will set the trustedData flag to true.
  • In response, e.g. search services, parameters of type Date are to be sent in the presentation form in the format yyyy-MM-dd HH-mm-ss. The remaining parameters are to be sent in the form as they are saved in the database.
  • In a request (call), e.g. a data update service, Date type parameters will be sent in presentational form in the format yyyy-MM-dd HH-mm-ss. Also, LOB type objects are sent in presentational form, i.e. e.g. as XML, not as a pointer to a LOB object.

The maximum number of search results/processed will be set to 1000

Example content of the context object that will be sent to the service:

<context xmlns="http://business.dto.ws.hgdb.io/context"
	xsi:schemaLocation="http://business.dto.ws.hgdb.io/context http://hgdb.io/xsd/dto/hgdb-context-3.0.xsd"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <appName>BPM Proces Urlopowy</appName>
 <appVersion>0.0.1</appVersion>
 <userName>ttesteusz</userName>
 <comment>Changing mother's maiden name, at client's request</comment>
 <maxResults>1000</maxResults>
 <queryTimeout>100000</queryTimeout>
 <locale>pl_PL</locale>
 <timeZone>Europe/Warsaw</timeZone>
 <userFullName>Tadeusz Testeusz</userFullName>
 <eager4omdBuilder>true</eager4omdBuilder>
 <trustedData>true</trustedData>
 <currentRole>Dyrektor</currentRole>
 <!--Zero or more repetitions:-->
 <userRoles>Dyrektor</userRoles>
 <userRoles>CKBPM-Team</userRoles>
 <userRoles>mrc-admin</userRoles>
 <userRoles>mrc-user</userRoles>
 <!--Here we will insert a string containing the hostname and the environment acronym -->
 <sourceOfRequest>dev-bpm855-003.DEV</sourceOfRequest>
 <formats>
  <entry>
   <key>date.format.long</key>
   <value>yyyy-MM-dd HH-mm-ss</value>
  </entry>
 </formats>
 <decodeResult>DATE_ONLY</decodeResult>
 <decodeRequest>DATE_AND_LOB</decodeRequest>
 <ignoreCaseHeaderInResponse>false</ignoreCaseHeaderInResponse>
 <cacheUsage>TO_USE</cacheUsage>
 <httpResponseCacheUsage>NONE</httpResponseCacheUsage>
 <requestProperties />
</context>

After sending the above context object to the service, the following additional actions will be performed:

  1. User data will be updated (if not up-to-date) (data regarding the full user name, language settings and time zone will be completed)
  2. The list of user roles will be verified. If any of the roles does not exist in the system, it will be added automatically.
  3. If the context is used during data update, the entered comment, data of the changing user (their name) and information about the role they played when making changes will be saved to the change history.
  4. If the context is used during data update in services that automatically detect dependencies, then information about the object's origin will be saved for new objects.
  5. The field with the external context identifier will support type identification.
  6. If the context is used when updating data in business services, the system will allow for the correct interpretation of date field values, e.g. the sent date 2017-01-01 23:34:21 will be decoded and saved in the database as the appropriate number of milliseconds.

Request parameters requestProperties​

The requestProperties parameter is used in business services to send additional information that may be needed when processing the request. An example use is to send additional parameters that are not standardly supported by the context, but are required by a specific service. Below is a list of parameters that can be sent in this parameter. As the system develops, this list can be expanded with additional parameters:

Parameter nameTypeDescription
saveRequestContext1
.modifyComment		StringRequest modification comment. Used in business case recording services.
saveRequestContext1
.saveCaseAsType		StringA hint for a case save request. The type name/type identifier under which the case is to be saved. Used in
saveRequestContext1
.valueIsNullIfFieldNotExisisInRequest		BooleanA hint for a case save request. Whether to set them to an empty value null if the fields do not exist in the case save request (no object fields were sent). The default parameter value is read from the system configuration stored in the mercury.properties file, the configuration parameter is mercury2.saveRequestContext1.valueIsNullIfFieldNotExisisInRequest.default.
saveRequestContext1
.forceChangeType		BooleanA hint for a request to save the case. An additional parameter that takes one of the values true or false. The parameter allows or prohibits the creation of a new version of the type for the case if there is already one defined. parameter with a default value, which in development environments would be set to true, and in production environments to false. The default value of the parameter is read from the system configuration stored in the file mercury.properties, the configuration parameter is mercury2.saveRequestContext1.forceChangeType.default.
saveRequestContext1
.caseWithoutId		BooleanA hint for a case save request. A parameter giving a hint that any case identifier sent in the case save request is to be ignored. The consequence of using it for cases with a type without a primary key is that cases will be added with each save. For cases with a defined primary key, the case will be added only if there is no case with a given key value. very useful when, and even RECOMMENDED when copying cases between different instances of the HgDB database. accepted values: true or false. Default value: false.

Footnotes​

  1. The prefix saveRequestContext. in the parameter name means that it belongs to the group of parameters related to updating case objects. ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7

  2. The prefix mercury. in the name of a configuration parameter denotes belonging to the general set of Mercury DB (HgDB) 3.0 system parameters. ↩ ↩2

Tags:
Last updated on by SÅ‚awomir 'slawas' Cichy