Case Recording Services and Methods
This article will describe the mechanisms accompanying the recording of a case to the Mercury DB (HgDB) database at the business layer level. Despite the existence of case recording methods in the system in services related to the logical layer, it is not recommended to use them. They are treated as obsolete. Maintaining them as explicit services is necessary due to compatibility with other products that use this layer directly.
Available case recording services
The following case recording methods are available within the system within the services presented below.
CaseBusinessRest
The WADL definition for the service is available at:
https://<hgdb_server_name>[:port]/mercury-ws-app/restServices/CaseBusinessRest.wadl
where:
<hgdb_server_name>- the name of the server on which the Mercury DB (HgDB) database instance is running.[:port]- an optional port number on which the Mercury DB (HgDB) database instance is running. By default, this is port443for HTTPS and80for HTTP. If not provided, the default port for the protocol will be used.
Example: https://testcluster.hgdb.io/mercury-ws-app/restServices/CaseBusinessRest.wadl.
REST service of the business layer allowing for processing of case object data. The service has its counterparts supporting the SOAP protocols (ICaseBusinessAction) and Spring Remoting RMI (/CaseBusinessAction). It contains the following methods for saving cases:
| Method(HTTP Method) | Description | |
|---|---|---|
| ⬜ | save(POST) | Method to save a case (adding1 or updating2 an existing one) as a universal MrcObject object (see the article dedicated to universal MRC objects). ➤ Sample request |
| ⬜ | saveList(POST) | Method to save (adding1 or updating2 existing cases) a list of cases as a universal MrcList object (see the article dedicated to universal MRC objects). ➤ Example request |
| ⬜ | updateCaseParamsByParams(POST) | Method to update2 individual parameters of an existing case. ➤ Example request |
| ⬜ | updateCasesParamsByParams(POST) | Method to update2 individual parameters of a list of existing cases. ➤ Example request |
| ⬜ | remove(POST) | Remove3 a case from the database. ➤ Example request |
| ⬜ | removeList(POST) | Remove3 a list of cases from the database. ➤ Example request |
| ⬜ | removeSubCase(POST) | Update composite case2, remove the association between parent and child case assigned to the field in composite cases. ➤ Sample request |
| ⬜ | removeSubCasesAll(POST) | Update composite case2, remove all associations between parent and child cases assigned to the field representing the list in composite cases. ➤ Sample request |
| ⬜ | removeSubCasesList(POST) | Update composite cases2, removing several links between parent case and child cases assigned to a field representing a list in composite cases. ➤ Sample request |
CaseBusinessExtRest
The WADL definition is available for the service at:
https://<hgdb_server_name>[:port]/mercury-ws-app/restServices/CaseBusinessExtRest.wadl
where:
<hgdb_server_name>- the name of the server on which the Mercury DB (HgDB) database instance is running.[:port]- an optional port number on which the Mercury DB (HgDB) database instance is running. By default, this is port443for HTTPS and80for HTTP. If it is not provided, the default port for the protocol will be used.
Example: https://testcluster.hgdb.io/mercury-ws-app/restServices/CaseBusinessExtRest.wadl.
REST service of the business layer extending the functionality of CaseBusinessRest with additional methods. Services supporting the SOAP protocols (ICaseBusinessAction) and Spring Remoting RMI (/CaseBusinessAction) contain the saveXML method, which corresponds to the implementation of this service. The service contains the following methods for saving cases:
| Method(HTTP Method) | Description | |
|---|---|---|
| ⬜ | save(POST) | method for saving a case (or a list of cases) as an arbitrary object (see the article on representing case as any object). ➤ Example request |
ICaseBusinessAction
The WSDL definition for the service is available at:
https://<hgdb_server_name>[:port]/mercury-ws-app/services/CaseBusinessAction?wsdl
where:
<hgdb_server_name>- the name of the server on which the Mercury DB (HgDB) database instance is running.[:port]- an optional port number on which the Mercury DB (HgDB) database instance is running. By default, this is port443for HTTPS and80for HTTP. If not specified, the default port for the protocol will be used.
Example: https://testcluster.hgdb.io/mercury-ws-app/services/CaseBusinessAction?wsdl
Service of the business layer of the SOAP protocol and Spring Remoting RMI. The service implements a special method saveXML, which allows saving a case in XML form. It is equivalent to the save method in the CaseBusinessExtRest service:
| Method(HTTP Method) | Description | |
|---|---|---|
| ⬜ | saveXML(POST) | Method of saving a case (adding1 or updating2 an existing one) in the form of XML (see the article on representing a case as any object). |
| ⬜ | save(POST) | Method of saving a case (adding1 or updating2 an existing one) in the form of a universal MrcObject object (see the article on MRC universal objects). |
| ⬜ | saveList(POST) | Method of saving a list of cases (adding1 or updating2 existing ones) in the form of a universal MrcList object (see the article on MRC universal objects). |
| ⬜ | updateCaseParamsByParams(POST) | Method to update2 individual parameters of an existing case. |
| ⬜ | updateCasesParamsByParams(POST) | Method to update2 individual parameters of a list of existing cases. |
| ⬜ | remove(POST) | Remove3 a case from the database. |
| ⬜ | removeList(POST) | Remove3 a list of cases from the database. |
| ⬜ | removeSubCase(POST) | Update a composite case2, remove the link between the parent and child cases assigned to the field in composite cases. |
| ⬜ | removeSubCasesAll(POST) | Update a composite case2, remove all links between the parent and child cases assigned to the field representing the list in composite cases. |
| ⬜ | removeSubCasesList(POST) | Updated a composite case2, removing several links between the parent case and the child cases assigned to the list field in composite cases. |
CaseRest
The WADL definition for the service is available at:
https://<hgdb_server_name>[:port]/mercury-ws-app/restServices/CaseRest.wadl
where:
<hgdb_server_name>- the name of the server on which the Mercury DB (HgDB) database instance is running.[:port]- an optional port number on which the Mercury DB (HgDB) database instance is running. By default, this is port443for HTTPS and80for HTTP. If not provided, the default port for the protocol will be used.
Example: https://testcluster.hgdb.io/mercury-ws-app/restServices/CaseRest.wadl
REST service of the logical layer allowing for processing of case object data. The service has its counterparts supporting the SOAP (ICaseAction) and Spring Remoting RMI (/CaseAction) protocols. The service methods operate directly on the Case entity data. The service contains the following methods for changing case data:
| Method(HTTP Method) | Description | |
|---|---|---|
| ⬜ | insert(POST) | Inserting the Case entity1. ➤ Example request |
| ⬜ | insertBag(POST) | Inserting a list of Case entities1. ➤ Example request |
| ⬜ | update(POST) | Updating an existing Case entity2. ➤ Example request |
| ⬜ | updateBag(POST) | Updating a list of existing Case entities2. ➤ Example request |
| ⬜ | remove(POST) | Remove Case entity3. ➤ Example request |
| ⬜ | removeBag(POST) | Remove Case entity list3. ➤ Example request |
Context control parameters
The Context context object passed to the business and logical layer service methods contains a number of parameters that can be used to control the behavior of the case record. The most important of them are presented below.
Context field userName
The Context object field named userName allows you to pass the name of the user who performs the case save operation. The value of this field is saved in the createdBy and modifiedBy fields in the case object.
Context field currentRole
The Context object field named currentRole allows you to pass the role of the user who performs the case save operation. The value of this field is used to determine the user's permissions in the context of the case operation and to log user information in the createdByRole and modifiedByRole fields in the case object.
Context field sourceOfRequest
The Context object field named sourceOfRequest allows you to pass the request source, which is used to identify the place from which the case save request comes. The value of this field is saved in the sourceOfRequest field in the case object.
Context field ignoredCustomFields
In business layer services, during the case save operation (cases), its type (metadata) is identified in the initial phase. In this way, different versions of the case type definition can be created. The Context object field named ignoredCustomFields allows you to pass a list of fields that make up the type definition, changes to which are to be ignored during case type identification (they are not to affect the creation of a new version of the case type). The value of this field is a list of type String and contains the names of the fields of the following entities (details can be found in the article Case metadata):
- TypeCase - the main description of the type.
- TypeParam - a list of parameters, fields describing the case.
- ParamDefinition - definitions of individual fields.
Individual entities have a very advanced description, concerning not only the model, but also the ways of presenting the case. We can give the comparison algorithm a hint to ignore some changes, especially those concerning presentation, when invoking the case save action, when identifying changes. This is to leave the definition unchanged, even though the case metadata may differ due to the quality of the description sent to the case save.
A parameter rarely used in business methods of case save services. During many years of experience, it turns out that the default value of this field defined in the system is sufficient.
To explain this better, we will rely on an example. In the system, in the definition of the name field, a label (label) with the value Name was defined. In SOAP services, when sending case data to save, we rarely send the label attribute attached to the XML field tag. We send <name position="2" type="String">Test Name4</name> instead of <name position="2" type="String" label="Nazwa">Test Name4</name>. This is not an error, because we cannot expect the data loading system to know with what label we want to present the field of a given case. Additionally, we save on the size of the data being sent. Therefore, so that Mercury DB (HgDB) does not create a new version of the field definition with an empty label, we mark the comparison of this field to be ignored.
When you intend to use this field, you must remember that you must specify all fields whose change should be ignored during type version identification. Regardless of whether they are ignored in the default case type version identification mechanism or not. Otherwise, if you do not specify a field to be ignored, it will be included in the case type version identification and may cause the creation of a new case type version.
List of values for ignoredCustomFields parameter
| Field value | Default behavior | |
|---|---|---|
| ✅️ | MParamDefinition.description | Ignored |
| ✅️ | MParamDefinition.alternateName | Ignored |
| ✅️ | MParamDefinition.recomendedLabel | Ignored |
| ✅️ | MParamDefinition.isLatestVersion | Ignored |
| ✅️ | MParamDefinition.isIndexable | Ignored |
| ✅️ | MParamDefinition.htmlControlName | Ignored |
| ❌ | MParamDefinition.paramType | NOT Ignored |
| ❌ | MParamDefinition.subType | NOT Ignored |
| ✅️ | MParamDefinition.timeToLiveSeconds | Ignored |
| ✅️ | MParamDefinition.valueDefinition | Ignored |
| ✅️ | MParamDefinition.sourceType | Ignored |
| ✅️ | MParamDefinition.source | Ignored |
| ✅️ | MParamDefinition.sourceJndiName | Ignored |
| ✅️ | MParamDefinition.sourceJ2CName | Ignored |
| ✅️ | MParamDefinition.presentationUrlPrefix | Ignored |
| ✅️ | MParamDefinition.complexClass | Ignored |
| ✅️ | MParamDefinition.defaultValue | Ignored |
| ✅️ | MParamDefinition.fromDate | Ignored |
| ✅️ | MParamDefinition.toDate | Ignored |
| ✅️ | MParamDefinition.isEditable | Ignored |
| ✅️ | MParamDefinition.sourceOfObject | Ignored |
| ✅️ | MParamDefinition.mimeType | Ignored |
| ✅️ | MParamDefinition.knownLobMetadata | Ignored |
| ✅️ | MParamDefinition.isProtected | Ignored |
| ✅️ | MTypeParam.label | Ignored |
| ✅️ | MTypeParam.tooltip | Ignored |
| ❌ | MTypeParam.updateable | NOT Ignored |
| ✅️ | MTypeParam.withEmptyOption | Ignored |
| ✅️ | MTypeParam.isRequired | Ignored |
| ✅️ | MTypeParam.isSearchData | Ignored |
| ✅️ | MTypeParam.hasMultiValues | Ignored |
| ✅️ | MTypeParam.arg1 | Ignored |
| ✅️ | MTypeParam.arg2 | Ignored |
| ✅️ | MTypeParam.arg3 | Ignored |
| ✅️ | MTypeParam.arg4 | Ignored |
| ✅️ | MTypeParam.arg5 | Ignored |
| ✅️ | MTypeParam.actions | Ignored |
| ❌ | MTypeParam.xmlId | NOT Ignored |
| ✅️ | MTypeParam.cmisFieldName | Ignored |
| ❌ | MType.typeName | NOT Ignored |
| ✅️ | MType.description | Ignored |
| ✅️ | MType.isEditable | Ignored |
| ❌ | MType.sourceOfObject | NOT Ignored |
| ❌ | MType.code | NOT Ignored |
| ✅️ | MType.isActive | Ignored |
| ✅️ | MType.kind | Ignored |
| ✅️ | MType.fromDate | Ignored |
| ✅️ | MType.toDate | Ignored |
| ❌ | MType.isDocumentType | NOT Ignored |
| ✅️ | MType.checkStoreCounter | Ignored |
| ✅️ | MType.accountNumber | Ignored |
| ❌ | MType.externalObjectID | NOT Ignored |
| ❌ | MType.rootVersionContextID | NOT Ignored |
| ✅️ | MType.cmisTypeName | Ignored |
Additional explanation of the value syntax:
- the value consists of two parts separated by the
.character. - The first part (prefix) is the representation of the entity that the field applies to, the second is the name of the entity field. Prefixes:
- MParamDefinition - field related to the entity
ParamDefinition- field definitions - MTypeParam - field related to the entity
TypeParam- type parameters (type fields) - MType - field related to the entity
TypeCase- description of the case type
Context field requestProperties
The field of the Context object called requestProperties allows additional information to be passed to the business layer. The value of this field is a map, where the keys and values are of type String. The article dedicated to the chapter Request parameters requestProperties presents a detailed list of available parameters that can be passed in this field.
Process of saving a case in the business layer
The page is under construction and does not contain all the information yet. Please be patient.
- TODO Description of the mechanism for saving a case in the business layer.
Method of copying data between Mercury DB (HgDB) database instances
The page is under construction and does not contain all the information yet. Please be patient.
- TODO Describe the method of copying/transferring data between database instances..
Importing data from Excel files
The page is under construction and does not contain all the information yet. Please be patient.
- TODO Describe data import from Excel files.
Footnotes
-
The case addition process includes the action of adding a Lucene index document and identifying the case type. ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7
-
The case update process takes into account updates to the Lucene index document, as well as the change of the case type version, if any. ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11 ↩12 ↩13 ↩14 ↩15 ↩16 ↩17
-
The case deletion process, data stored in the
Caseentity, is configurable and by default involves moving data from the main table to the archive table. You can perform an action to recreate the case object. Deleting a case is accompanied by deleting the document from the Lucene index. ↩ ↩2 ↩3 ↩4 ↩5 ↩6